CLI Commands

All commands support --help for detailed usage. Run cerulion --help to see the full list.

Quick Reference

Category	Command	Description
workspace	`workspace create <name>`	Create a new workspace
	`workspace init <location>`	Initialize in existing directory
node	`node create <type>`	Create a new node
	`node modify <type>`	Add inputs/outputs to a node
	`node build <type>`	Compile and validate
	`node run <type>`	Run single node (testing)
graph	`graph create <name>`	Create a graph definition
	`graph run <name>`	Execute a graph
topic	`topic list`	List all active topics
	`topic info <topic>`	Show topic details
	`topic echo <topic>`	Print messages in real-time
	`topic hz <topic>`	Measure publish rate
tui	`tui`	Launch interactive terminal UI

Workspace Commands

Workspaces are the top-level container for your Cerulion project. They hold nodes, graphs, and configuration.

workspace create

Create a new workspace with scaffolded structure.

cerulion workspace create <name>

Argument	Description
`name`	Name of the workspace to create

Example
Output

cerulion workspace create my-robot

workspace init

Initialize a workspace in an existing directory.

cerulion workspace init <location>

Argument	Description
`location`	Path to initialize (use `.` for current directory)

cd existing-project
cerulion workspace init .

Use workspace init when adding Cerulion to an existing project without creating a new folder.

Node Commands

Nodes are the building blocks of Cerulion applications. Each node is a processing unit with typed inputs and outputs.

node create

Create a new node from a template.

cerulion node create <type> [options]

Argument	Description
`type`	Node type name (becomes the node identifier)

Option	Description
`--period-ms <N>`	Run periodically every N milliseconds
`--ext-trigger`	Trigger from external event instead of timer

Periodic node
Triggered node

# Runs every 100ms
cerulion node create sensor_reader --period-ms 100

# Runs when input arrives
cerulion node create image_processor --ext-trigger

node modify

Add inputs, outputs, or bindings to an existing node.

cerulion node modify <type> <modification>

Modification	Description
`-i <schema> [name]`	Add an input port with the given schema
`-o <schema> <topic>`	Add an output port publishing to topic
`--ext-bind`	Bind to external trigger source

Add input
Add output
Bind trigger

cerulion node modify sensor_reader -i SensorData
cerulion node modify processor -i ImageFrame camera_input

cerulion node modify sensor_reader -o TemperatureReading sensors/temperature

cerulion node modify processor --ext-bind

Input and output schemas must be defined first using cerulion schema create.

node build

Compile a node and validate its configuration.

cerulion node build <type>

Argument	Description
`type`	Node type to build

cerulion node build sensor_reader

Build validates schemas, checks port connections, and compiles the node code.

node run

Run a single node directly (useful for testing).

cerulion node run <type>

Argument	Description
`type`	Node type to run

cerulion node run sensor_reader

For production, use cerulion graph run to run multiple connected nodes. Use node run for testing individual nodes in isolation.

Graph Commands

Graphs compose multiple nodes into a connected pipeline. Nodes communicate via topics.

graph create

Create a new graph definition.

cerulion graph create <name> [options]

Argument	Description
`name`	Graph name

Option	Description
`-n <prefix>`	Namespace prefix for all topics in this graph

Simple
Namespaced

cerulion graph create perception

cerulion graph create perception -n robot1

Namespacing allows running multiple instances of the same graph with isolated topics.

graph run

Execute a graph (runs all staged nodes).

cerulion graph run <name>

Argument	Description
`name`	Graph name to run

cerulion graph run perception

Topic Commands

Topics are named channels for pub/sub communication between nodes.

topic list

List all active topics.

cerulion topic list

Example output:

TOPIC                      TYPE              PUBLISHERS  SUBSCRIBERS
sensors/temperature        TemperatureData   1           2
sensors/humidity           HumidityData      1           1
camera/front/image         ImageFrame        1           3

topic info

Show detailed information about a topic.

cerulion topic info <topic>

Command
Output

cerulion topic info sensors/temperature

Topic: sensors/temperature
Schema: TemperatureData
Transport: local (iceoryx2)

Publishers:
  - sensor_reader (PID 12345)

Subscribers:
  - display_node (PID 12346)
  - logger_node (PID 12347)

Message Rate: 10.0 Hz

topic echo

Print messages from a topic in real-time.

cerulion topic echo <topic>

Command
Output

cerulion topic echo sensors/temperature

[1705234567.123] temperature: 22.5, unit: "celsius"
[1705234567.223] temperature: 22.6, unit: "celsius"
[1705234567.323] temperature: 22.5, unit: "celsius"
^C

Press Ctrl+C to stop echoing. Add --count N to echo only N messages.

topic hz

Measure the publish rate of a topic.

cerulion topic hz <topic>

Command
Output

cerulion topic hz sensors/temperature

Subscribed to: sensors/temperature
Average rate: 10.02 Hz
  Min: 9.98 Hz
  Max: 10.05 Hz
  Std Dev: 0.02 Hz
Window: 100 messages

Interactive UI

cerulion tui

Launch the terminal user interface for visual system monitoring.

cerulion tui

Features:

Real-time node status monitoring
Topic message inspection
Graph visualization
Performance metrics
Keyboard-driven navigation

Key	Action
`q`	Quit
`Tab`	Switch panels
`Enter`	Select / Expand
`e`	Echo selected topic
`?`	Show help

Global Options

These options work with any command:

Option	Description
`--help`	Show help for command
`--version`	Show Cerulion version
`--verbose`	Enable verbose output
`--quiet`	Suppress non-error output
`--config <path>`	Use custom config file

Cerulion

Quick Reference

Workspace Commands

Node Commands

Graph Commands

Topic Commands

Interactive UI

cerulion tui

Global Options

Next Steps

Quickstart

Pub/Sub

Cerulion

​Quick Reference

​Workspace Commands

​Node Commands

​Graph Commands

​Topic Commands

​Interactive UI

cerulion tui

​Global Options

​Next Steps

Quickstart

Pub/Sub

Quick Reference

Workspace Commands

Node Commands

Graph Commands

Topic Commands

Interactive UI

Global Options

Next Steps