CLI reference - Cerulion Docs

The cerulion binary groups all functionality under top-level commands: workspace, node, graph, topic, schema, tui, trace, and clean. Synopsis notation uses <required>, [optional], {a|b} (choice), and ... (repeatable). Synopsis lines are not directly runnable; each command includes a separate runnable example.

Global

cerulion [--verbose] <command> [args...]

Flag	Long	Type	Default	Meaning
verbose	`--verbose`	bool	false	Enable debug-level logging. Long form only — there is no `-v`. Applies to every subcommand.

On error, cerulion prints Error: <msg> to stderr and exits with a failure code. Most commands require a workspace, discovered by walking upward for a Cargo.toml containing [workspace] plus a graphs/ directory. workspace create/init, tui, trace, and clean do not require discovery. topic * uses iceoryx2 discovery and needs no workspace.

workspace

cerulion workspace create

Create a new workspace directory.

cerulion workspace create <name>

Arg / flag	Value name	Type	Default	Meaning
name (positional)	`<name>`	String	—	Required. Workspace directory to create at `./<name>/`.

Creates ./<name>/ with graphs/, nodes/, schemas/, Cargo.toml ([workspace], members=["nodes/*"], resolver="2", workspace dependencies for cerulion_core and native_ros2_messages), and .cargo/config.toml. Errors if ./<name> already exists. Prints Created workspace at <path>.

cerulion workspace create my_robot

cerulion workspace init

Initialize a workspace in place.

cerulion workspace init [location]

Arg / flag	Value name	Type	Default	Meaning
location (positional)	`[location]`	String	`.`	Directory to initialize in place (defaults to the current directory).

Initializes a workspace at location. Errors if a Cargo.toml with [workspace] already exists there. The workspace name is the directory’s file name (fallback cerulion_ws). Prints Initialized workspace at <path>.

cerulion workspace init .

node

Subcommands: create, delete, modify, build, stage, run, list, info. All require workspace discovery.

cerulion node create

Create a node type.

cerulion node create <node_type> [-o SCHEMA NAME] [-i SCHEMA NAME] [-T SCHEMA NAME] [--policy SPEC] [--raw-ffi]

Flag	Short/Long	Value names	Type	Default	Meaning
node type	(positional)	`<node_type>`	String	—	Required. Becomes folder `nodes/<node_type>/` and (PascalCased) the struct name. Validated: non-empty, alphanumeric/underscore, must not start with a digit.
output port	`-o` / `--output`	`SCHEMA NAME`	2 values	—	Add one output port. Both SCHEMA and NAME required. At most one `-o` per `create`.
input port	`-i` / `--input`	`SCHEMA NAME`	2 values	—	Add one regular input. Both required. At most one `-i` per `create`.
trigger input	`-T` / `--trigger-input`	`SCHEMA NAME`	2 values	—	Add a trigger input → field emitted as `#[input(trigger)]`, policy set to `data_trigger=<NAME>`. Both required. At most one `-T` per node.
policy	`--policy`	`SPEC`	String	(defaulting rules)	Trigger policy. See Trigger policies.
raw FFI	`--raw-ffi`	—	bool	false	Generate the raw `extern "C"` FFI template instead of the `#[cerulion_node]` macro template.

Schema is accepted in both sensor_msgs/Image (slash, canonical) and sensor_msgs::Image (colon) forms; canonicalized to slash. Output prints Created node type '<node_type>'.Generated files: nodes/<type>/Cargo.toml (cdylib, cdylib feature default) and nodes/<type>/src/lib.rs (macro or raw-FFI). Nothing is added to the workspace Cargo.toml if it already uses the "nodes/*" glob (the default).Validation errors (clean messages, no panic): passing a flag twice; -T name colliding with -i name; --policy data_trigger=NAME not matching a declared input; a source-only node (no -i/-T) without an explicit non-data --policy.

cerulion node create detector -T sensor_msgs/Image image -o geometry_msgs/PoseArray detections

cerulion node delete

Delete a node type.

cerulion node delete <node_type>

Arg	Value name	Type	Meaning
node type (positional)	`<node_type>`	String	Required. Node type to delete.

Removes nodes/<node_type>/ (recursive) and the workspace member entry. Errors NodeNotFound if absent. Prints Deleted node type '<node_type>'.

cerulion node delete detector

cerulion node modify

Modify an existing node type in place.

cerulion node modify <node_type> [-i SCHEMA NAME] [-T SCHEMA NAME] [-o SCHEMA NAME] [--policy SPEC]

Flag	Short/Long	Value names	Notes
node type	(positional)	`<node_type>`	Required. Node type to modify.
input port	`-i` / `--input`	`SCHEMA NAME`	Add a regular input. At most one per call.
trigger input	`-T` / `--trigger-input`	`SCHEMA NAME`	Add a trigger input (`#[input(trigger)]`) and set policy `data_trigger=<NAME>`, clearing conflicting node-level policy args. At most one per call.
output port	`-o` / `--output`	`SCHEMA NAME`	Add an output. At most one per call.
policy	`--policy`	`SPEC`	Set/replace the trigger policy. `data_trigger=NAME` requires NAME to be an existing input or one added in the same call.

Mutates the node’s src/lib.rs in place (preserves the tick body, comments, and other fields). -T and --policy data_trigger=NAME are equivalent; supplying both requires they agree. Prints per-action lines, e.g. Added input 'image' to 'detector' as the data trigger, Set policy=period_ms=33 on 'detector', Promoted existing input 'x' to data trigger on 'detector'.

There is no --ext-trigger flag and no --no-trigger flag. The only user surface for setting external triggering is --policy external.

cerulion node modify detector -i sensor_msgs/Imu imu --policy period_ms=33

cerulion node build

Build a node crate.

cerulion node build <node_type> [--release]

Flag	Long	Type	Default	Meaning
node type	(positional)	`<node_type>`	—	Required. Node type to build.
release	`--release`	bool	false	Build in release mode.

Runs cargo build -p <node_type> (adds --release if set) in the workspace root. Errors BuildFailed (with cargo stderr) on failure. Prints Built '<node_type>'.

Requires cargo on PATH — the CLI shells out to it.

cerulion node build detector --release

cerulion node stage

Append a node instance to a graph YAML file.

cerulion node stage <node_type> [-i ID] [-g GRAPH] [-p PREFIX] [-I NAME SOURCE]...

Flag	Short/Long	Value names	Type	Default	Meaning
node type	(positional)	`<node_type>`	String	—	Required. Node type to stage.
id	`-i` / `--id`	—	Option<String>	node_type	Node instance ID (defaults to the node type).
graph	`-g` / `--graph`	—	Option<String>	auto	Target graph. If omitted: auto-selects the sole graph; errors if 0 or more than 1 exist.
prefix	`-p` / `--prefix`	—	Option<String>	—	Parsed but currently ignored in the handler. Topic prefix resolution lives on the graph, not here.
input binding	`-I`	`NAME SOURCE`	2 values, repeatable	—	Wire input `NAME` to `SOURCE`. `[node,port]` form → `node/port`; `node/port` passes through.

Outputs (with schemas) are auto-derived from the node’s source metadata. A duplicate node ID is an error. The modified graph is validated. Prints Staged '<type>' into graph '<graph>'.

cerulion node stage detector -g perception -I image [camera,image]

cerulion node run

Smoke-run a single node.

cerulion node run <node_type> [-p PREFIX] [-i ID]

Flag	Short/Long	Type	Default	Meaning
node type	(positional)	String	—	Required. Node type to run.
prefix	`-p` / `--prefix`	Option<String>	`standalone`	Topic prefix.
id	`-i` / `--id`	Option<String>	node_type	Instance ID.

Creates a hidden temp graph __temp_<type>, stages the node, runs it (not real-time, validation skipped), and deletes the temp graph YAML on exit. Ctrl+C stops it.

cerulion node run detector -p standalone

cerulion node list

List node types.

cerulion node list

No arguments. Prints a table with columns TYPE INPUTS OUTPUTS POLICY (counts plus a short policy label). Empty workspace prints No nodes found.

cerulion node list

cerulion node info

Show details for a node type.

cerulion node info <node_type>

Arg	Value name	Type	Meaning
node type (positional)	`<node_type>`	String	Required. Node type to inspect.

Prints Node type, Policy, and Inputs:/Outputs: (name plus schema or (untyped)). Metadata is parsed from src/lib.rs — the source is the single source of truth; there is no sidecar YAML.Policy short labels: period <N>ms, deadline <N>ms, sync <N>ms, sync ∞ (unbounded), external, trigger:<input>, - (none).

cerulion node info detector

graph

Subcommands: create, run, validate, list.

cerulion graph create

Create a graph file.

cerulion graph create <name> [-n PREFIX]

Flag	Short/Long	Type	Default	Meaning
name	(positional)	String	—	Required. Graph name → `graphs/<name>.yaml`.
prefix	`-n` / `--prefix`	Option<String>	—	Topic prefix. If omitted, the `prefix:` line is omitted from the file and resolved to the hostname (without `.local`) at load time.

Creates graphs/<name>.yaml. Errors if the graph already exists. Prints Created graph '<name>'.

cerulion graph create perception -n robot1

cerulion graph run

Run a graph.

cerulion graph run <name> [--real-time[=BOOL]] [--no-real-time] [--no-validate]

Flag	Form	Type	Default	Meaning
name	(positional)	String	—	Required. Graph to run.
real-time	`--real-time`, `--real-time true`, `--real-time false`	bool	`true`	Drive the sim clock from wall time with a ~1 ms sleep cadence. Bare `--real-time` is equivalent to `--real-time true`. Default ON.
no real-time	`--no-real-time`	bool	false	Full-speed, no 1 ms pacing (benches/replay). Wins if both passed. Equivalent to `--real-time false`.
no validate	`--no-validate`	bool	false	Skip pre-run workspace validation.

Loads cdylibs, builds the runtime, and steps the simulated clock in 1 ms increments until Ctrl+C or a node requests shutdown. Validation failures only warn and continue; they do not block run. The environment variable CERULION_CPU_DMA_LOCK=1 acquires a CPU DMA latency lock for the run (best-effort; warns on failure). graph run also runs an iceoryx2 dead-node cleanup at start.

Requires cargo on PATH — run loads compiled cdylibs from target/{debug,release}/.

cerulion graph run perception --no-real-time

cerulion graph validate

Validate a graph.

cerulion graph validate <name>

Arg	Value name	Type	Meaning
name (positional)	`<name>`	String	Required. Graph to validate.

Runs the validation report (topology, node crate exists, ports parse, cdylib exists, input bindings and schema match, data_trigger bindings). Prints the report and exits non-zero if any check fails.

cerulion graph validate perception

cerulion graph list

List graphs.

cerulion graph list

No arguments. Lists graph names (file stems of *.yaml), sorted. Empty prints No graphs found.

cerulion graph list

topic

Uses iceoryx2 service discovery — enumerates services ending in /data (Cerulion creates {topic}/data and {topic}/event per topic). No workspace required.

cerulion topic list

List active topics.

cerulion topic list

Lists active topic names (sorted). Header TOPIC. Empty prints No active topics.

cerulion topic list

cerulion topic info

Show topic info.

cerulion topic info <topic>

Arg	Value name	Type	Meaning
topic (positional)	`<topic>`	String	Required. Topic to inspect.

Prints the topic info string.

cerulion topic info robot1/camera/image

cerulion topic echo

Print messages from a topic.

cerulion topic echo <topic>

Arg	Value name	Type	Meaning
topic (positional)	`<topic>`	String	Required. Topic to subscribe to.

Subscribes and prints messages until Ctrl+C. Pretty-prints std_msgs/String and sensor_msgs/Image (by FNV-1a schema hash); hex preview otherwise.

cerulion topic echo robot1/camera/image

cerulion topic hz

Measure publish rate.

cerulion topic hz <topic>

Arg	Value name	Type	Meaning
topic (positional)	`<topic>`	String	Required. Topic to measure.

Measures the publish rate until Ctrl+C.

cerulion topic hz robot1/camera/image

schema

Subcommands: create, delete, info.

cerulion schema create

Create a schema file.

cerulion schema create <name>

Arg	Value name	Type	Meaning
name (positional)	`<name>`	String	Required. Schema name → `schemas/<PascalName>.yaml`.

Creates schemas/<PascalName>.yaml with a schemas: skeleton (description plus a fields: comment). Errors if the schema exists. Prints Created schema '<name>'.

cerulion schema create Reading

cerulion schema delete

Delete a schema file.

cerulion schema delete <name>

Arg	Value name	Type	Meaning
name (positional)	`<name>`	String	Required. Schema to delete.

Removes schemas/<name>.yaml. Errors SchemaNotFound. Prints Deleted schema '<name>'.

cerulion schema delete Reading

cerulion schema info

Show schema details.

cerulion schema info <name>

Arg	Value name	Type	Meaning
name (positional)	`<name>`	String	Required. Schema name. Accepts qualified ROS2 names like `sensor_msgs::Image`.

First tries a ROS2 .msg lookup at ../native_ros2_messages/msg/<pkg>/<Type>.msg (for qualified names); prints fields, Rust types, and min wire size. Falls back to a workspace YAML schema (prints Schema, Description, Fields, Hash: 0x...).

cerulion schema info sensor_msgs::Image

tui

cerulion tui

Launches the interactive ratatui dashboard. Logging is suppressed in TUI mode.

cerulion tui

trace inspect

cerulion trace inspect <dir> [-t TOPIC] [-n N] [-r]

Flag	Short/Long	Value name	Type	Default	Meaning
dir	(positional)	`<dir>`	String	—	Required. Directory of `trace_*.jsonl` bag files.
filter	`-t` / `--filter`	`TOPIC`	Option<String>	—	Filter by exact topic.
limit	`-n` / `--limit`	`N`	Option<usize>	—	Limit the number of records.
reverse	`-r` / `--reverse`	—	bool	false	Reverse order (most-recent first).

Reads trace_*.jsonl bag files (lexicographic order) and prints <topic> seq=<N> t=<ts>ns schema=0x<HASH> per record.

cerulion trace inspect ./traces -t robot1/camera/image -n 100 -r

clean

cerulion clean

Removes iceoryx2 on-disk bookkeeping for dead nodes only (live sibling processes are untouched). Prints cleanup counts plus per-cause remediation.

cerulion clean

Documentation Index

​Global

​workspace

​node

​graph

​topic

​schema

​tui

​trace inspect

​clean

Global

workspace

node

graph

topic

schema

tui

trace inspect

clean