.yaml file that wires node instances together by their ports. This guide takes you from an empty graph to a running one, and covers the difference between validating and running.
The perception graph you build below wires a camera instance to a detector instance: the detector’s image input reads the camera’s image output, which you set up with -I.
Figure: The example topology. -I image [camera,image] wires the detector’s image input to the camera’s image output.
Run these commands from inside a workspace. You need built node types first;
see Define a node.
Create a graph
cerulion graph create <name> writes graphs/<name>.yaml. Pass -n/--prefix to set a topic prefix; if you omit it, the prefix line is left out and resolves to the machine’s hostname at load time.
Graph files are YAML with a
.yaml extension and carry topology only. They
do not contain a policy: block. Trigger policies live on the node macro.Stage node instances
cerulion node stage <node_type> appends a node instance to a graph and auto-derives its outputs from the node’s source metadata.
| Flag | Value names | Meaning |
|---|---|---|
-i / --id | ID | Instance ID (defaults to the node type). |
-g / --graph | GRAPH | Target graph. Omit to auto-select (see below). |
-I | NAME SOURCE | Wire input NAME to SOURCE. Repeatable. |
-I source accepts either node/port or the [node,port] form; both resolve to node/port.
When you omit
-g, the CLI auto-selects the workspace’s sole graph. If there
are zero graphs or more than one, it errors and asks you to name one.Topic prefix is a graph-level setting: set it once on the graph with
graph create -n, and every staged instance inherits it. node stage accepts
a -p/--prefix flag for forward compatibility, but staging itself does not
alter prefix resolution.
Each
node stage validates the resulting graph and rejects duplicate instance IDs.
Validate vs run
These two commands treat failures differently:cerulion graph validate <name>runs the full validation report (topology, node crates exist, ports parse, cdylibs exist, input bindings and schemas match) and exits non-zero if any check fails.cerulion graph run <name>only warns on validation problems and continues. Usevalidateas a gate in scripts or CI.
graph validate prints a report and exits 0 when every check passes. A
non-zero exit means at least one check failed; read the report to see which.Run the graph
cerulion graph run <name> loads the compiled cdylibs, builds the runtime, and runs the graph until you stop it with Ctrl+C or a node requests shutdown. In the default live mode (--time-source real) it wakes and processes messages as they arrive.
Clock and validation flags
| Flag | Default | Effect |
|---|---|---|
--time-source real | (default) | Live mode — the graph wakes and processes messages as they arrive. |
--time-source virtual | — | Deterministic mode — the clock steps 1 ms per tick, for replay and benchmarking. |
--no-validate | off | Skip the pre-run validation check entirely. |
--time-source virtual:
Smoke-test a single node
cerulion node run <node_type> runs one node in a hidden temporary graph in live mode (validation skipped) and deletes that temp graph on exit. It is a quick way to check that a node loads and ticks without wiring a full graph.
Next steps
Inspect topics
Watch the running graph with
topic echo, hz, and the TUI.Define a node
Add or adjust the node types you stage here.