Skip to main content
This page gets the cerulion CLI and its sibling programs onto your machine, signed in, and verified. The install script, Homebrew and the Debian package install prebuilt binaries; cargo install and a source checkout build them from source. Cerulion runs on Linux and macOS. Release binaries support Linux x86_64 and ARM64 (glibc 2.31 or newer, Ubuntu 20.04 and later) and macOS on Intel and Apple Silicon. Examples on this page use Cerulion 2.0.0. Generated dependency versions match the installed CLI.

Prerequisites

Rust toolchain

Rust 1.95 or newer, with cargo, to build nodes. Any Rust 1.95 or newer works; it does not have to match the compiler that built the CLI. The install script sets it up for you.

C toolchain

Building nodes needs a C toolchain, installed before Rust. Debian and Ubuntu: sudo apt-get install -y build-essential. macOS: xcode-select --install.

Cargo for node builds

cerulion node build runs Cargo from your PATH, or from ${CARGO_HOME:-$HOME/.cargo}/bin when it is not on your PATH, and says how to add it. cerulion graph run only loads the node libraries node build produced.
The install script keeps a Rust 1.95 or newer that is already there and otherwise installs current stable Rust through rustup, so on that route you can skip this step. Homebrew and Debian package users run cerulion-install-rust once instead. On a terminal, cerulion workspace create and cerulion node build offer to install Rust when 1.95 or newer is missing. For the crates.io and source routes, install Rust with rustup if you do not already have it:
Confirm cargo is available:

Install the CLI

Downloads the release archive for your platform, sets up Rust, and installs four programs side by side: cerulion, cerulion-netd, cerulion-connectd and cerulion-remoted. On Linux it also places the ROS 2 Jazzy rmw and heap hook beside them.
In fish, end the line with && source ~/.cerulion/env.fish instead.The script needs curl and tar. It resolves the latest stable release, checks the archive’s SHA-256, and refuses to install if it does not match. It keeps a Rust 1.95 or newer that is already there, and otherwise installs current stable Rust through rustup. Because all four programs land together, cerulion connect and remote access to this machine work without a source build.It installs into $CERULION_INSTALL_DIR, defaulting to ~/.cerulion/bin, links the programs into ~/.local/bin, and adds one line to your shell startup files, so new terminals find cerulion; the end of the command above does the same for the terminal you are in. Pass --no-modify-path to leave your startup files and ~/.local/bin alone; the script then prints the PATH line to add yourself. On a Mac with zsh the output ends like this:
Pass options through the pipe with sh -s --. --dir picks a different destination, --version pins a specific release, and --uninstall removes the install (pass the same --dir if you installed with one):
Prebuilt archives exist for x86_64 and arm64 on both Linux and macOS. On any other platform the script exits with error: unsupported platform; build from source, so use the crates.io or source tab. Under WSL2 it warns that WSL2 is unverified and unsupported, then installs the Linux artifact anyway.
The script selects the latest stable release, so it skips prereleases. Pass --version vX.Y.Z-PRERELEASE to install a prerelease explicitly.
macOS: the release binaries are not notarized. Binaries this script installs are fine, because curl sets no quarantine flag. But an archive you download in a browser is quarantined, and Gatekeeper then blocks all four binaries on first run. Clear the flag on all four from the extracted directory, since the CLI and its network daemon start the others:
If you used the crates.io or source route, open a new shell so rustup’s PATH takes effect. Then check that the binary resolves:

Sign in

Cerulion commands run under an account. Sign in once per machine; later commands read the result locally, so they keep working offline.
A robot or a headless box prints a short code to approve from a browser on any machine. cerulion --version, --help, completions, doctor, clean and telemetry work before you sign in. At a terminal, any other command starts this sign-in for you the first time; with no terminal (a script, a CI job, a coding agent’s shell) it exits with code 7 instead. For automation, point CERULION_HOME at a directory holding the state of a machine that signed in.
Using a coding agent? Ask it to run cerulion login in the background, show you the URL and code it prints, and wait while you approve the sign-in in your browser.
Keep cerulion-netd beside the cerulion binary. The CLI spawns it for live runs and for topic discovery, and it looks for it next to itself unless CERULION_NETD_BIN points elsewhere. Every route on this page puts them in the same directory, so this is already true unless you move one.

How generated workspaces resolve their dependencies

cerulion workspace create writes the root Cargo.toml for you, and it picks where cerulion_core and native_ros2_messages come from based on where the cerulion binary itself lives: The CLI prints which one it chose on the line under the created path, so the choice is never silent. The generated Cargo.toml also pins the iceoryx2 crates to a git revision under [patch.crates-io], which the first build fetches.

Verify the installation

Confirm everything is wired up: print the version, list the available commands, check the machine, set up completions, and scaffold a throwaway workspace.

Check the version

List the commands

Confirm the CLI runs and prints its help:
You should see the top-level commands, including workspace, node, graph, topic, bag and doctor.

Check the machine

cerulion doctor checks this machine for problems that slow or stop Cerulion and prints the fix for each. It needs no root, and it runs before you sign in; until you do, its account.login check fails:
It ends with a count line such as 4 pass, 4 info, 1 warn, 0 fail, 9 skip and exits non-zero only when a check failed.

Install shell completions

Optional, but it makes the CLI much easier to explore. Add the lines for your shell to its startup file, then open a new terminal:
These lines regenerate the completion code each time a shell starts, so they keep working after an upgrade. cerulion completions --help has the lines for fish, elvish and PowerShell.

Create a smoke-test workspace

Create a scratch workspace to confirm the CLI can scaffold a project. Like most commands, this needs the sign-in above:
Expected output, with the second line naming the dependency source it picked:
cerulion --version printed a version, cerulion --help listed the commands, cerulion login signed you in, and cerulion workspace create install_check created a new workspace. Your installation is working. You can delete the install_check directory once you are satisfied.
A robotic hand lights a switch as sensors glow blue to celebrate a verified installation

Questions or setup help?

The Cerulion CLI is open source. If you have a question, want help with your first run, or want early access to Hindsight (closed source), book 30 minutes with us.

Get help in 30 minutes

Bring a setup question, your use case, or a run you want to investigate.

Next steps

Quickstart

Build and run your first two-node graph end to end.

Concepts

Understand workspaces, nodes, graphs, topics, and schemas.

Connect an MCP client

Early access. Give your coding agent tools that analyze your robot recordings.