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.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:
cargo is available:
Install the CLI
- With the install script
- Homebrew
- Debian / Ubuntu
- From crates.io
- From a source checkout
Downloads the release archive for your platform, sets up Rust, and
installs four programs side by side: In fish, end the line with Pass options through the pipe with Prebuilt archives exist for x86_64 and arm64 on both Linux and macOS. On
any other platform the script exits with
cerulion, cerulion-netd,
cerulion-connectd and cerulion-remoted. On Linux it also places the
ROS 2 Jazzy rmw and heap hook beside them.&& 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: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):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.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.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.
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: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.
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.