.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 with a prefix: line and an empty nodes: list. Pass -n/--prefix to set the topic prefix; omit it and the machine’s hostname is stamped into the file at create time, so topic names stay the same when the graph moves to another machine and a recording of it still replays.
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.
-I takes two values: the input port name, then its source. The source is written node/port, or as an absolute /prefix/node/port for a topic this graph does not produce.
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. A staged instance
carries no prefix of its own, so node stage has no prefix flag — to change
the prefix, edit the graph’s prefix: line.Stage the source node
Stage the consumer and wire its input
Wire the detector’s
image input to the camera’s image output:node stage validates the resulting graph and rejects duplicate instance IDs.
Validate vs run
Both commands run the same validation report (topology, node crates exist, ports parse, cdylibs exist, input bindings and schemas match), and both treat a failing check as fatal:cerulion graph validate <name>prints the report and exits non-zero if any check fails, without starting anything. Use it as a gate in scripts or CI.cerulion graph run <name>runs the report first and refuses to start if any check fails. Warnings stay advisory — the run continues.
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.
n leaves the file untouched and changes nothing about the run; --single-process opts out entirely. See Run a graph across processes.
Clock and validation flags
The default is live mode. To run deterministically (for replay or benchmarking), pass
--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.
Record and replay a run
Bag this run and re-execute your nodes against it.
Visualize a running graph
Render the live topics on the Cerulion Studio stage.