Skip to main content
The cerulion binary groups all functionality under top-level commands:
Synopsis notation uses <required>, [optional], {a|b} (choice), and ... (repeatable). Synopsis lines are not directly runnable; each command includes a separate runnable example.

Global

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, clean, doctor, completions, login, logout, account, telemetry, connect, viz, bag, flashback, and ros2 run/launch/migrate do not require discovery; schema info and schema list use a workspace when they find one and fall back to the built-in types when they do not. The topic commands use transport discovery and need no workspace.

workspace

cerulion workspace create

Create a new workspace directory.
Creates ./<name>/ with graphs/, nodes/, schemas/, Cargo.toml ([workspace], members=["nodes/*"], resolver="2", workspace dependencies for cerulion_core and native_ros2_messages), .cargo/config.toml, and a .gitignore carrying .cerulion/ (the workspace lock directory). Errors if ./<name> already exists.The cerulion_core and native_ros2_messages dependencies point at published crates, exact-pinned to the CLI’s own version, unless your cerulion binary was built from a Cerulion source checkout, in which case they are absolute path dependencies into that checkout. The decision keys on where the binary lives, never on the current directory. The command prints which it chose on the line under the created path.
Initialize a workspace in place.
Errors if a Cargo.toml with [workspace] already exists there. The workspace name is the directory’s file name.

node

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

cerulion node create

Create a node type.
SCHEMA accepts sensor_msgs/Image, sensor_msgs::Image, or a bare Image. Bare names resolve against your workspace schemas first, then the built-in ROS 2 messages; an ambiguous bare name errors and lists the candidates.Generated files: nodes/<type>/Cargo.toml (cdylib) and nodes/<type>/src/lib.rs.A source-only node (no -i/-T) must declare a non-data policy — --policy period_ms=N or --policy external.
Delete a node type.
Removes nodes/<node_type>/ (recursive) and the workspace member entry.
Modify an existing node type in place.
Splices new port fields into the macro struct and rewrites the node-level policy attribute in src/lib.rs. Your tick() body is untouched. --raw-ffi is not accepted here — the existing node form is preserved.
Compile a node type into a loadable library.
Shells out to cargo build for that crate with the cdylib feature, producing .so (Linux) or .dylib (macOS). CARGO_TARGET_DIR is honored.If the crate declares optional system dependencies, the build probes them with pkg-config first and enables each feature whose libraries are present; a missing one is reported loudly and the build continues without that feature.
Add an instance of a node type to a graph.
SOURCE is either relative (sensor/image → /<prefix>/sensor/image) or absolute (/vendor/camera/image, an external topic with no in-graph producer).
Run a single node type on its own.
Builds a hidden single-node graph and runs it on the live clock without validation, so you can exercise one node against topic echo. Networking follows the same defaults as graph run.
List the workspace’s node types.
Prints a TYPE INPUTS OUTPUTS POLICY table derived from each crate’s src/lib.rs.
Show one node type’s ports and policy.

graph

Subcommands: create, run, validate, list, levels, plan, profile, partition, pause, resume.

cerulion graph create

Create an empty graph file.
Load, validate, and execute a graph.
A failing validation check refuses the run before anything starts; warnings are advisory and the run continues.The run continues until Ctrl+C or a node calls request_shutdown(). On Unix under the real clock, an unpartitioned graph is executed multi-process by default — see Run a graph across processes.Exit status: 0 for a run that ends normally; 3 when one or more nodes returned NodeError::Fatal and were stopped during the run, after one Error: node '<id>' stopped on a fatal error: <message> line per stopped node; 1 for any other failure, which wins over 3.A run that stops normally spends a bounded pass of roughly two seconds on cleanup after the graph is over, reclaiming shared-memory state left behind by dead nodes; because the graph has already stopped, nothing you are waiting on is delayed. Whatever the budget does not reach stays for the next pass. A run killed with SIGKILL skips that pass, and the next run that stops normally picks up what it left. A run refused before it starts — an unknown graph name, for instance — does no cleanup at all.
Validate a graph without running it.
Runs the full check set — node libraries present, ports and schemas matching the node source, sources resolvable, trigger requirements satisfied, topic names well formed — and prints a per-check report ending in a count such as 9/9 checks passed. Exits non-zero on any failure, which makes it the command to run in CI.Node libraries must be built first; an unbuilt node fails its cdylib '<type>' check with cdylib for node '<type>' not found, followed by the paths searched and the cerulion node build command to run.
List the workspace’s graphs.
Show the execution levels the runtime derives from the wiring.
Prints each level with its nodes and their trigger policies, the edges that carry triggers, and — when the graph declares process_groups: — which group covers which levels. Exits non-zero if the declared partition is invalid.The partition verdict names every split block edge it found creditable, so this is the verb that answers whether a hand-written split will run:
Show the processes a run of the graph starts and the executor units inside each. Read-only.
Prints each process with its units and nodes, and the reason each unit starts where it does. A graph without process_groups: shows the layout graph run derives for it.
Measure per-node tick costs and edge rates.
Runs the graph locally, then writes a cost snapshot — per-node median tick cost, per-edge fire rates, and a frozen compute budget — that graph partition consumes. Nodes that never sampled enough fires are reported as isolated rather than guessed at.
Derive and write the graph’s process groups.
Writing is a surgical rewrite of the process_groups: block with a .bak backup alongside it.
Hold a live run still, then let it go on.
<run> is a graph name that matches exactly one live run, or the run id (0x and 32 hex digits, recorded in the run’s run.json). A pause holds every process of the run at its next step boundary and stops the run’s clock, so a period timer neither skips ticks nor bursts on resume, and a recording of the run shows no gap across the pause. Pausing a paused run, or resuming a running one, succeeds and changes nothing.
A pause is not an emergency stop. It does not stop hardware, and a publisher outside the graph keeps publishing into its inputs’ queues. A node that reads the hardware clock itself (real_ns()) still sees it advance.
Exit 0 on success, 4 when no live run matches, and 1 when the run cannot be paused: it runs on --time-source virtual or external, its graph has ros2: entries, or the name matches more than one run. Unix only.

topic

Topic commands attach to the running transport and need no workspace.

cerulion topic list

List active topics, locally and on the network.
Local topics print first and immediately. Robots on your account and their topics, found on one LAN or across networks, follow in ROBOTS and REMOTE TOPICS sections. A failed remote query is a loud note and still exits 0.
Show a topic’s schema and last-seen frame.
Print messages as they arrive.
Prints one YAML document per message: a # seq=.. ts=..ns schema=0x.. size=.. comment, a # <type> comment, the fields, then ---. Every type prints its fields this way, sensor_msgs/Image included. A frame no known schema names prints # comment lines that say why, with a hex preview of its first 64 payload bytes. Runs until Ctrl+C. A name that is not a local topic is looked for on the robots on your account and demanded for the length of the command; --local or CERULION_NETWORK=off keeps it local-only.
Measure a topic’s publish rate.
Print a topic’s message type.
Prints package/Type, or the bare name of a workspace schema declared with no package. Exits 1 with an error naming the topic when it is not found, sends no message within the wait (1 s local, 3 s remote), or carries a schema no known type names.
List the topics that carry a message type.
Prints every local topic, and every topic discovered on the network, whose type is <type>, one per line, sorted. Takes the name topic type and topic list -t print; the ROS 2 form package/msg/Type also works. A type no topic carries prints nothing and exits 0.
Measure a topic’s bandwidth.
Prints, once a second, the bytes per second of the topic’s payloads over the window, with their mean, smallest and largest size. On the obstacle_avoidance starter’s laser scan:
Publish a message given as JSON or YAML.
By default it publishes one message. Topics are single-writer, so a topic a graph already publishes is not one to publish into.
A message you publish reaches every subscriber of the topic, a robot’s controller included. Try it on a topic nothing acts on, such as a status topic of your own.
Save the newest frame of a camera topic as a JPEG.

service

Calls a service once and prints its response as JSON.

schema

cerulion schema create

Create a workspace schema file.
Writes schemas/<name>.yaml — the name verbatim, no case change — holding a schemas: skeleton whose single entry key is the PascalCased name. cerulion schema create detections writes schemas/detections.yaml containing a Detections: entry. See Graph and schema files.
Delete a workspace schema.
Built-in ROS 2 messages cannot be deleted.
Show a schema’s fields, wire size, and hash.
Prints the recursive field tree marking fixed and variable fields, the fixed wire size, the schema hash, and where the definition came from. It resolves four sources, in this order: your workspace’s schemas/*.yaml, your workspace’s .msg store (schemas/<package>/msg/<Type>.msg), the built-in ROS 2 types, and a connected robot’s own types. The source: line names which one answered.
List available schemas.
Prints your workspace schemas, then your workspace’s .msg store, then every built-in ROS 2 message grouped by package. A built-in that a .msg store entry overrides is listed as <name> (shadowed by msg store '<name>').

bag

Recording and replay. See Record and replay a run.

cerulion bag record

Record live local topics into a bag.
This records topics from this machine’s shared memory, including topics already mirrored onto it; to record the robot, run it on the robot and copy the file afterwards. The capture is observability-grade: each channel carries the real wire hash but no schema name, which is everything bag play needs and enough for topic echo to decode from the workspace schema store.--resim compatibility is not claimed for a bag record bag, --run included. A standalone capture carries frames and no scheduler trace at all; a --run attach does carry the run’s effective graph, environment, manifests and a trace from its attach point, but its descriptors are still observability-grade. When you know you will re-execute, record the run with graph run --record.
Inspect a bag.
The report opens with:
It continues with record coverage (which topics the recorder tapped, declared or discovered) and node state (the state records a mid-run resume reads).A bag that carries a recorder health attachment also gets an absorbance block: per topic, whether the queue its recording tap was given holds that topic’s frames through the run’s own worst drain gap. Every topic with a verdict is counted; only the actionable ones are named — short, no claim, a stall the drain-gap histogram cannot rank, a pass on a floor rate, or a topic that fell short earlier and recovered. On a flashback capture the block describes the recorder that took the capture, over its whole run, not the captured window. See Record and replay a run.
Play a bag back, optionally re-executing your nodes.
--report and --tolerance need --verify, not merely --resim. A bare --resim all re-executes the graph without comparing anything, so there is no verdict for either flag to describe, and the command refuses rather than writing an empty report.
Replay is network-inert by construction: the bag is the input.
Counts depend on your recording. With --verify the exit code is 0 for a pass, 1 for a data violation, 2 for a bag that is not replay-grade or is corrupt, 3 for a node that failed to load or panicked, 4 for a tolerance-file error, 5 for an internal error, and 6 when the re-executed schedule diverged.
Rewrite an older bag so --resim accepts it.
Writes a new bag whose embedded graph has keys the graph format does not define taken out, listing every key it removes and asking first (--yes writes without asking, and is required when stdin is not a terminal; --dry-run writes nothing). It also rewrites frames that carry an older wire header with the current one, even when the graph already parses. The input bag is never modified, and every other frame and attachment is copied through unchanged. A bag whose graph already parses and whose frames already carry the current header is refused: there is nothing to migrate.

flashback

Captures roughly the last 30 seconds plus the next 15 seconds of every serving graph on this machine into recordings/flashbacks/. There is nothing to arm in advance — a live run already holds the rolling window. CERULION_FLASHBACK=off turns the capture plane off.

viz

Early access
cerulion viz attaches topics to the cerulion-vizd visualization daemon, which is in early access and is not part of the standard download. The command opens no viewer itself; the viewer is also in early access. Book 30 minutes with us to get access.

connect

Demanded topics are re-injected into your machine’s shared memory, so cerulion topic echo and topic hz see them like local topics. With no --topic and no --all, it prints the robot’s catalog and demands nothing. The robot admits only a machine on its access list. Sign the robot and this machine in to the same account with cerulion login: the robot adds this machine to its access list the first time this machine’s network daemon reads one of the robot’s topics, and connect is admitted after that.

ros2

The ROS 2 interop family: run and launch put stock ROS 2 entry points on Cerulion transport, migrate rewrites a colcon workspace’s C++ publish sites to the loaned-message API, and attach bridges a robot that is already running ROS 2.

run and launch

Runs a stock ROS 2 entry point on Cerulion transport — swap the command, not the stack. ros2 run demo_nodes_cpp talker becomes cerulion ros2 run demo_nodes_cpp talker; ros2 launch my_robot_bringup camera.launch.py becomes cerulion ros2 launch my_robot_bringup camera.launch.py. Unix only. Everything after run or launch is forwarded to the native ros2 run / ros2 launch untouched (hyphenated flags, the package form, launch arguments), except Cerulion’s own leading flags, given right after run or launch: --record-deliveries <DIR> (both verbs) records what each ROS 2 process consumed, and --replay-deliveries <LOG> (run only) replays one recorded process; see Replay a ROS 2 process. Apart from those, the argument surface is ROS 2’s, so consult ros2 run --help / ros2 launch --help, and a bad package name or a missing launch file is ros2’s own error. rmw_cerulion is tested in CI on ROS 2 Foxy, Galactic, Humble, Jazzy and Lyrical. The Linux packages and archives carry a library built for Jazzy, and Lyrical’s library is the separate cerulion-rmw-lyrical download; build it for another distro from source with tools/scripts/build_rmw.sh <distro>. Jazzy is the distro it has run on a robot with. ros2 topic list and rqt do not see topics that run on Cerulion’s transport; use cerulion topic list.
--adopt-take in the leading position is refused rather than forwarded: it exits 69, and CERULION_RMW_ADOPT_TAKE set in the environment exits 2. ros2 is a Python CLI that spawns your node as a further subprocess with close_fds=True, so the heap hook these launchers hand over never reaches the node and every take would be served by a copy; the refusal is there so you do not get the flag’s name without its effect. For zero-copy plain takes, launch the node executable directly with the hook preloaded and CERULION_RMW_ADOPT_TAKE=1 (Linux/glibc only).
Before forwarding, Cerulion stages the child environment: Cerulion then exec()s ros2 <verb> [ARGS...]: the process becomes ros2, so stdout, stderr, Ctrl+C, and the exit code pass through the kernel untouched, and a successful exec inherits ros2’s own exit code. The nodes keep their ROS names. A ROS 2 publisher on /camera/image_raw is the Cerulion topic /camera/image_raw — the fully-qualified name verbatim, leading slash included, for topics and for services alike. Nothing is prefixed, stripped, or aliased, so a native #[input] whose source: is /camera/image_raw reads that publisher directly, and a recording of the run carries the topic under the name ROS 2 uses. Each ROS 2 publisher also registers its topic with the machine’s network plane, so once that plane is up the topic is announced and a remote desk can demand it like a native node’s output — see Reach remote robots. Registration is best-effort and never blocks local ROS 2 pub/sub: a topic that could not be registered stays local-only and says so in a warning. Subscriptions register nothing, and a registration is not withdrawn when a publisher is destroyed — the topic stays announced, with no producer behind it, for the life of the process. Exit codes belong to Cerulion only when it never reached the exec: 69 librmw_cerulion.so missing (the message carries the build command and the override), or --adopt-take given · 127 ros2 not on PATH · 2 a usage error, such as a bare cerulion ros2, or CERULION_RMW_ADOPT_TAKE set in the environment · 1 any other pre-exec failure.
To bring stock ROS 2 nodes up alongside native Cerulion nodes from one graph file, declare them as ros2: entries and run cerulion graph run — see Graph and schema files.

migrate

Rewrites this colcon workspace’s C++ publish call sites to the ROS 2 loaned-message API (borrow_loaned_message() → fill → publish(std::move(loaned))) wherever a clang AST prover shows the rewrite is behavior-preserving. It is an AST transform over the workspace’s compile_commands.json, never a regex; anything it cannot prove lands in a manual-candidates report with the reason. rclpy nodes are report-only, because rclpy has no loaned-message API upstream. Migrating does not couple your workspace to Cerulion: rclcpp falls back to allocate-and-copy when the rmw cannot loan.
Initialization is not identical on every rmw, and the rewrite compensates. make_unique<T>() value-initializes, so every field your code does not write holds its declared default (a Quaternion’s w=1, zeros elsewhere). A loaned message is only initialized if the rmw does it, and rmw_fastrtps — the ROS 2 default — does not. The rewrite therefore emits <loaned>.get() = <MessageT>(); right after the borrow, so every field you do not write keeps the default make_unique gave it, on every rmw, for the cost of one value-init store.
Dry run is the default. It prints the full unified diff and the candidates report, and refreshes the machine-readable manifest at .cerulion/ros2-migrate-manifest.json — the only thing it writes. --write refuses a dirty git tree, then writes one commit plus cerulion-ros2-migration.patch and runs colcon build --packages-select over the affected packages. Undo with git revert <sha>, or git apply -R cerulion-ros2-migration.patch. If a pre-commit hook stages paths of its own, it stages them inside git commit — after this verb’s index check — so they land in the migration commit; the run warns and names them, and git apply -R is then the safe undo, because it reverses only the migration’s own edits. Requires a compile database (colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON) and the migration engine binary cerulion-ros2-migrate-clang, found beside the cerulion binary, on PATH, or via CERULION_ROS2_MIGRATE_TOOL. Exit 69 with build instructions when it is absent.

attach

Discovers a ROS 2 system’s topics, generates graphs/<name>.yaml plus a bridge configuration for the ones whose types resolve, and runs the bridge. See Bridge a ROS 2 system. Every run’s report ends with a MIGRATION section — there is no flag for it, and --dry-run prints it too. It groups the discovered processes (one DDS participant each) by what a restart under rmw_cerulion would buy: restartable today, when every message type on the process’s endpoints resolves locally; restartable once consent writes the schemas this attach resolved; or stays bridged, with the unresolvable types named. Endpoints with no ros_discovery_info record are counted as topics, not processes, and are reported as absence of evidence — a vendor or raw-DDS process, or a node table the window did not observe. ROS plumbing endpoints (parameter services, /rosout, /parameter_events, ros_discovery_info) are excluded from the judgment. The section then prints the equivalent cerulion ros2 launch line, a paste-ready ros2: graph block with <package>/<executable> placeholders, the bridged-versus-native cost facts, and a closing pointer at cerulion ros2 migrate. It is rendered from the discovery data already in hand: no extra network, no change to the outcome or exit code.

login and account

cerulion login signs this machine in with a device-code flow: it prints a short code and a verification URL, then waits for you to authorize it in a browser on any machine. Commands run under an account: on a machine that has never signed in, the first command that needs one runs the same flow when it is at a terminal, and anywhere else exits with code 7. --version, --help, completions, doctor, clean, telemetry and logout work before you sign in. cerulion logout signs this machine out: it removes the session from this machine and asks the account service to revoke it, then prints signed_out: account=<id>, or not_signed_in when there was no session. It exits 1 when the local sign-in file could not be rewritten, or when the machine was signed out but the service did not confirm the revoke; the session then stays valid at the service until it expires. account devices lists and revokes the machines registered to your account. Robot access management lives on the web account page, not the CLI.

completions

Shells: bash, elvish, fish, powershell, zsh. Completion covers subcommands, flags, and enum values, plus live names: topics, node types, graph names, schemas, robots pinned in robots.toml or seen on the LAN, and .mcap files. A completion never opens the network. For zsh, add two lines to ~/.zshrc. The generated script ends in compdef, which only exists once compinit has run, and the macOS system zshrc never runs it:
The second line regenerates the completion code each time a shell starts, so it keeps up with upgrades. Writing cerulion completions zsh into a file also works, but that file names the binary’s path, so regenerate it after an upgrade.

tui

An interactive dashboard with Nodes, Topics, and Echo tabs. Quit with q.

trace

Prints one line per record, <topic> seq=<N> t=<TIMESTAMP>ns schema=0x<HASH>, from the JSONL publish trace (trace_*.jsonl) in a directory. -t restricts to one topic by exact name, -n limits the count, and -r reverses to most-recent-first. This is not the MCAP bag; for recordings use cerulion bag.

clean

Removes the bookkeeping dead Cerulion processes left behind; live nodes are left alone. Reach for it when a graph’s topic topology changed between runs and topics look missing. It needs no account and reaches no network. cerulion clean --report-only deletes nothing: it lists what a plain cerulion clean would remove and ends with Report only: nothing was removed. When the dead-node sweep cannot clear every dead node, clean reports the leftover shared-memory state but does not reclaim it: a dead node that is still registered needs its state to be reaped later, so removing it would strand that node for good. Clear the reported failures, then run cerulion clean again. You rarely need this command — graph run sweeps dead nodes at start, and cleans up again when the graph exits normally.

doctor

Checks this machine for problems that slow or stop Cerulion: open-file limits, shared memory, stale nodes, disk space for recordings, sign-in state, clock sync, the ROS 2 library, the network daemon, and more. Each check reports pass, info, warn, fail or skip, and every warn and fail says why it matters and the exact command or edit that fixes it. No check needs root, and none writes a file or changes a system or network setting. It runs on a machine that has never signed in. Exit 0 when no check failed (warnings included), 1 when any check failed, 2 for a usage error.
An excerpt from a macOS host:

telemetry

Release builds of the CLI can send coarse usage events: which command ran, its exit code and a duration bucket. Never sent: command arguments, file or directory names, paths, topic, node, graph or robot names, URLs, email addresses, or message contents. Telemetry is on unless you turn it off, and any one of these turns it off:
cerulion telemetry status prints whether telemetry is on and which setting decided it, for example telemetry: on (default). Once this machine has signed in, events carry your account id; before that, a random id. The first command that could send prints a one-line notice and sends nothing in that run. A build from source sends nothing unless it was built or run with a telemetry key. Robot and runtime code (the graph runtime, the transport, the recorder, the network daemons, and your nodes) never sends anything, and no CLI command sends while the run is local-only (CERULION_NETWORK=off, --network off, or --local). telemetry itself works without signing in. The full list of events is at cerulion.com/telemetry.

Node macro

Every macro and field attribute available to a node author.

Graph and schema files

Every key in graph and schema YAML.

Environment variables

Logging, networking, recording, and runtime tuning variables.

Connect an MCP client

Early access. Connect an AI client to the hosted Cerulion MCP and Hindsight endpoints.