> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cerulion.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Wire and run a graph
> Create a graph, stage node instances, wire their inputs, validate, and run it.
A graph is a `.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`.
```mermaid theme={null}
flowchart LR
camera[camera] -- "camera/image" --> detector[detector]
detector -- "detector/detections" --> out([detections])
```
*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](/cerulion/guides/define-a-node).
## Create a graph
`cerulion graph create ` writes `graphs/.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.
```bash theme={null}
cerulion graph create perception
```
```text theme={null}
Created graph 'perception'
```
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 ` 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. |
The `-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.
```bash theme={null}
cerulion node stage camera -g perception
```
```text theme={null}
Staged 'camera' into graph 'perception'
```
Wire the detector's `image` input to the camera's `image` output:
```bash theme={null}
cerulion node stage detector -g perception -I image [camera,image]
```
```text theme={null}
Staged 'detector' into graph 'perception'
```
Each `node stage` validates the resulting graph and rejects duplicate instance IDs.
## Validate vs run
These two commands treat failures differently:
* `cerulion graph validate ` 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 ` only **warns** on validation problems and continues. Use `validate` as a gate in scripts or CI.
```bash theme={null}
cerulion graph validate perception
```
`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 ` 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.
```bash theme={null}
cerulion graph run perception
```
`graph run` loads compiled cdylibs and needs `cargo` available, so build your
nodes first. It runs an iceoryx2 dead-node cleanup at start.
### 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. |
The default is live mode. To run deterministically (for replay or benchmarking), pass `--time-source virtual`:
```bash theme={null}
cerulion graph run perception --time-source virtual
```
Press Ctrl+C to stop a running graph.
## Smoke-test a single node
`cerulion node run ` 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.
```bash theme={null}
cerulion node run camera
```
Press Ctrl+C to stop it.
If you change a graph's topology between runs (add, remove, or rewire nodes)
and hit stale iceoryx2 service errors, run `cerulion clean` to clear
bookkeeping for dead nodes, then run again.
## Next steps
Watch the running graph with `topic echo`, `hz`, and the TUI.
Add or adjust the node types you stage here.