CLI Reference

The dimos CLI manages the full lifecycle of a dimOS robot stack: start, stop, inspect, and interact.

Global Options

Every GlobalConfig field is available as a CLI flag. Flags override environment variables, .env, and blueprint defaults.

dimos [GLOBAL OPTIONS] COMMAND [ARGS]

Flag	Type	Default	Description
`--robot-ip`	TEXT	`None`	Robot IP address
`--robot-ips`	TEXT	`None`	Multiple robot IPs
`--simulation`	TEXT	empty	Select simulation (`mujoco` or `dimsim`); a bare flag selects MuJoCo
`--replay` / `--no-replay`	bool	`False`	Use recorded replay data
`--replay-db`	TEXT	`go2_short`	Replay memory SQLite database name
`--record [sqlite\|mcap]`	`sqlite\|mcap`	off	Record selected streams to one artifact; bare `--record` means SQLite (Recording)
`--record-engine`	`python\|rust`	`python`	Recording implementation; Rust is experimental and never selected implicitly
`--record-topics`	TEXT	`*`	Comma-separated globs on stream names to record
`--record-encoding-threads`	INT	unset (Rust uses `4`)	Native encoding workers; valid only with `--record-engine rust`
`--viewer`	`rerun\|none`	`rerun`	Visualization backend
`--n-workers`	INT	`2`	Number of forkserver workers
`--transport`	`lcm\|zenoh`	`zenoh`	Transport backend for streams, RPC, and TF. Zenoh is the default on every platform and is pinned to localhost until you pass `--robot-ip` or enable scouting. Set `DIMOS_TRANSPORT` (env var or `.env`) to switch every process at once. Standalone CLIs like `humancli`, `agentspy`, and `dtop`, which also accept `--transport`.
`--dtop` / `--no-dtop`	bool	`False`	Enable live resource monitor overlay
`--robot-model`	TEXT	`None`	Robot model identifier
`--robot-width`	FLOAT	`0.3`	Robot width in meters, shared by the navigation and patrol modules
`--robot-rotation-diameter`	FLOAT	`0.6`	Robot rotation diameter in meters

Configuration Precedence

Values resolve in this order: schema defaults → blueprint values → JSON config → .env → environment → CLI flags. Global environment variables use uppercase field names, such as ROBOT_IPS (transport also accepts DIMOS_TRANSPORT).

Module settings go after the blueprint names, for example dimos run unitree-go2 --go2connection.replay-exit true. Use dimos run <blueprint> --help for that stack's options. See Configuration for the migration from global flags.

Module booleans require an explicit value (--go2connection.replay-exit true or --go2connection.replay-exit=true); they have no bare-flag or --no- form. Global booleans still accept paired flags such as --replay / --no-replay.

Commands

`dimos run`

Start one or more robot blueprints. Built-in dimOS blueprints use bare names such as unitree-go2; external blueprints installed from Python packages use namespaced names such as my-robot-stack.go2.

dimos run <blueprint> [<blueprint> ...] [--daemon] [--disable <module> ...] [--<config-field> <value> ...]

Option	Description
`--config`, `-c`	Path to a JSON configuration file; dynamic flags override its values
`--daemon`, `-d`	Run in background (double-fork, health check, writes run registry)
`--disable`	Module class names to exclude from the blueprint
`--<config-field>`	Set a blueprint configuration field using its kebab-case name, for example `--voxel-size=1`; qualify ambiguous fields as `--voxelgridmapper.voxel-size=1`
`--local-relay`	Start a relay on this machine and open the cockpit in the browser (see Web)
`--relay-url`	Connect the robot to a relay started elsewhere, by its HTTP URL; `--relaybridgemodule.relay-ca` adds a private CA and `RELAYBRIDGEMODULE__RELAY_KEY` the robot's key (see Bridge)
`--help`	Display the run options and available blueprint configuration flags

Dynamic values accept both --field=value and --field value. A shorthand is available only when it identifies one active module. If two modules expose the same field, the CLI reports the ambiguity and lists stable qualified forms such as --relocalizationmodule.map-file. Global flags work on either side of run; older wrapper-style overrides are no longer accepted.

# Foreground (Ctrl-C to stop)
dimos run unitree-go2

# Background (returns immediately)
dimos run unitree-go2-agentic --daemon

# Replay with Rerun viewer
dimos --replay --viewer rerun run unitree-go2

# Record every stream of a run, then replay it
dimos --record --simulation run unitree-go2
dimos --replay --replay-db recordings/<run-id>/memory.db run unitree-go2

# Replay Big Office (Zenoh is the default transport)
dimos --transport=zenoh --dtop --replay --replay-db=go2_bigoffice run unitree-go2

# Real robot
dimos run unitree-go2-agentic --robot-ip 192.168.123.161

# Blueprint configuration (both value forms are accepted)
dimos run unitree-go2 --map-file recording_go2

# Compose modules dynamically
dimos run unitree-go2 keyboard-teleop

# Run an externally packaged blueprint
dimos run my-robot-stack.go2

# Compose built-in and external blueprints
dimos run unitree-go2 my-robot-stack.keyboard-teleop

# Disable specific modules
dimos run unitree-go2-agentic --disable OsmSkill WebInput

External blueprint names are always fully qualified as <canonical-distribution-namespace>.<external-local-blueprint-name>. The namespace is derived from the installed Python distribution name by lowercasing it and collapsing runs of -, _, and . into -. The local blueprint name is the entry point name and must be lowercase kebab-case, for example keyboard-teleop.

Heavy replay workloads can be unreliable over LCM UDP, which is one reason zenoh is the default transport; you can still force either path explicitly with --transport=lcm or --transport=zenoh.

When --daemon is used, the process:

Builds and starts all modules (foreground, so you see errors)
Runs a health check (polls worker PIDs)
Forks to background, writes a run registry entry
Prints run ID, PID, log path, and MCP endpoint

Adding a New Blueprint

For an in-repository dimOS blueprint, define a module-level Blueprint variable and regenerate the built-in registry:

pytest dimos/robot/test_all_blueprints_generation.py

This auto-generates dimos/robot/all_blueprints.py for built-in blueprints. External packages do not edit that file; they expose blueprints through Python package entry points. See blueprints for composition and external publishing details.

`dimos graph`

Render a Blueprint's stream flow as a Graphviz SVG without starting the Blueprint or opening its runtime transports. RPC relationships are hidden by default; pass --rpc to include RPC contracts and their declared Spec methods as dashed edges.

dimos graph unitree-go2-agentic
dimos graph unitree-go2-agentic --rpc --output go2-agentic.svg

The default output is <blueprint>.svg in the current directory. Graphviz's dot executable must be installed.

`dimos shell`

Open an IPython session attached to the coordinator on the configured transport bus:

dimos shell

The command requires an interactive terminal. For scripts and automation, use Dimos.connect() through the Python API instead. While attaching, the shell displays a waiting indicator and retries coordinator discovery within the default five-second connection budget.

The shell starts with five names:

Name	Purpose
`app`	Connected `Dimos` instance; access modules and invoke RPCs directly
`guide()`	Reprint the shell's quick-start guide
`modules()`	Print module instances, classes, and RPC counts
`rpcs()`	Print every RPC's signature and docstring summary
`describe(value)`	Pretty-print a module or RPC's signature and documentation

For example:

modules()
guide()
rpcs("StressTestModule")
describe("StressTestModule.ping")
app.StressTestModule.ping()

For example, describe("StressTestModule.echo") prints:

RPC: StressTestModule.echo
Signature: echo(message: str) -> str

Documentation:
Echo a message back to the caller.

Use app.describe(...) when you want the structured ModuleInfo or RpcInfo record instead of formatted output.

Discovery is live, so modules loaded after attachment appear on the next modules() or rpcs() call. Use app.list_modules() and app.list_rpcs() when you want structured records. Exact instance names select one deployment when multiple instances share a class.

RPC calls execute immediately against the running system. The shell does not filter methods or ask for confirmation, so an RPC may move hardware or change lifecycle state. Start with a non-hardware, simulation, or replay stack.

Exiting IPython closes only the shell's client connection. The coordinator and its modules keep running. If the coordinator stops or restarts, calls fail visibly; start a new dimos shell session to reconnect.

The shell normally displays the CLI run ID and blueprint. Coordinators launched directly from Python have no run-registry metadata and are shown as unregistered coordinator.

`dimos status`

Show the running dimOS instance.

dimos status

Reads the run registry, verifies the PID is alive, and displays: run ID, PID, blueprint name, uptime, log path, and MCP port.

`dimos stop`

Stop the running dimOS instance.

dimos stop [--force]

Option	Description
`--force`, `-f`	Immediate SIGKILL (skip graceful SIGTERM)

Default behavior: SIGTERM → wait 5s → SIGKILL. Cleans up the run registry entry.

`dimos restart`

Restart the running instance with the same original arguments.

dimos restart [--force]

Option	Description
`--force`, `-f`	Force kill before restarting

Reads saved CLI args from the run registry, stops the current instance, then re-runs with the same arguments.

`dimos log`

View logs from a dimOS run.

dimos log [OPTIONS]

Option	Description
`--follow`, `-f`	Follow log output (like `tail -f`)
`--lines`, `-n`	Number of lines to show (default: 50)
`--all`, `-a`	Show full log
`--json`	Raw JSONL output (for piping to `jq`)
`--run`, `-r`	Specific run ID (defaults to most recent)

dimos log                    # last 50 lines, human-readable
dimos log -f                 # follow in real time
dimos log -n 100             # last 100 lines
dimos log --json | jq .event # raw JSONL, extract events
dimos log -r 20260306-143022-a3f1-unitree-go2  # specific run

All processes (main + workers) write to the same main.jsonl. Filter by module:

dimos log --json | jq 'select(.logger | contains("RerunBridge"))'

`dimos list`

List all available blueprints. Built-in and external blueprints are grouped separately; external names are read from installed package metadata without importing their target modules.

dimos list

Example output:

Built-in blueprints:
  unitree-go2
  unitree-go2-agentic

External blueprints:
  my-robot-stack.go2
  my-robot-stack.keyboard-teleop

`dimos show-config`

Print resolved GlobalConfig values and their sources.

dimos show-config

`dimos cache clean`

Remove caches generated by dimOS, including downloaded robot assets, prepared URDFs, cooked scene meshes, the ament index, and the auto-downloaded Deno runtime. All of these live under the platform-specific dimOS cache directory.

dimos cache clean

The command does not remove logs, recordings, datasets, configuration, or third-party model caches. It refuses to run while a dimOS blueprint is active.

Before deleting anything, the command displays the cache root and every top-level entry currently present. It then asks for confirmation with a default of No. Pass --yes to skip the prompt in automation.

`dimos spy`

Universal transport spy: a live table of every topic on every pubsub transport (LCM, Zenoh, or both), with per-topic message rate, bandwidth, size, and liveness.

dimos spy                     # everything, all transports
dimos spy --transport zenoh   # filter to one transport (repeatable flag)
dimos lcmspy                  # deprecated alias for: dimos spy --transport lcm

`dimos login`

Device-code sign-in for the hosted platform; dimos logout and dimos whoami manage the stored key.

`dimos data`

Upload recordings (or any file) to hosted storage and pull them back. See Cloud data.

Subcommand	Description
`upload [PATH\|latest] [--since 1h] [--robot ID] [--kind KIND] [--chunk MB]`	Upload; no argument means the newest recording
`ls`	List uploads: id, date, kind, blueprint, topics, size, state
`pull [ID-PREFIX\|latest] [--dest PATH]`	Download to `downloads/`, sha256-verified
`status ID` / `quota`	Upload state and parts on server / storage quota

`dimos host`

Run this machine as a Host for distributed runs. See dimos host.

Agent & MCP Commands

`dimos agent-send`

Send a text message to the running agent via LCM.

dimos agent-send "walk forward 2 meters"

Works with any agentic blueprint. Does not require MCP. Publishes directly to the /human_input LCM topic.

`dimos mcp`

Interact with the running MCP server. Requires a blueprint that includes McpServer, for example unitree-go2-agentic. The MCP server runs at http://localhost:9990/mcp by default (--mcpserver.port / --mcpserver.host after the blueprint name to override; dimos mcp and an McpClient in the blueprint find the endpoint themselves).

To add MCP to a blueprint, include both McpServer (exposes skills as HTTP tools) and McpClient.blueprint() (LLM agent that fetches tools from the server):

from dimos.agents.mcp.mcp_client import McpClient
from dimos.agents.mcp.mcp_server import McpServer
from dimos.core.coordination.blueprints import autoconnect

# Example wiring (replace # -ed with your stack and skill):
my_mcp_blueprint = autoconnect(
    # my_robot_stack,
    McpServer.blueprint(),
    McpClient.blueprint(),
    # my_skill_containers,
)

`dimos mcp list-tools`

List all available skills exposed by the MCP server.

dimos mcp list-tools

Returns JSON with tool names, descriptions, and parameter schemas.

`dimos mcp call`

Call a skill by name.

dimos mcp call <tool_name> [--arg key=value ...] [--json-args '{}'] [--timeout SECONDS]

Option	Description
`--arg`, `-a`	Arguments as `key=value` pairs (repeatable)
`--json-args`, `-j`	Arguments as a JSON string
`--timeout`, `-t`	Seconds to wait for the tool. Default is 30 seconds. The client cuts off a skill that runs longer.

dimos mcp call move_to --arg x=3.2 --arg y=-0.5
dimos mcp call move_to --json-args '{"x": 2.0, "y": 0, "relative": true}'
dimos mcp call observe
dimos mcp call land

`dimos mcp status`

Show MCP server status: PID, uptime, deployed modules, skill count.

dimos mcp status

`dimos mcp modules`

List deployed modules and their skills.

dimos mcp modules

Standalone Tools

These are installed as separate entry points and can be run directly without the dimos prefix.

`humancli`

Interactive terminal for sending messages to the running agent.

humancli

`lcmspy`

Deprecated alias for dimos spy --transport lcm (the LCM-only view of the spy). Prefer dimos spy.

lcmspy

`agentspy`

Monitor agent messages and tool calls.

agentspy

`dtop`

Live resource monitor TUI: CPU, memory, and process stats. The cockpit shows the same data on its Stats tab (Stats() in cockpit(pages=[...])), which switches the monitor on by itself. Can also be activated during a run with --dtop:

dimos --dtop run unitree-go2

Or run standalone:

dtop

`dimos rerun-bridge`

Launch the Rerun visualization bridge as a standalone process (outside of a blueprint). It takes the bridge module's settings as flags or as RERUNBRIDGEMODULE__* environment variables, and serves the web viewer by default. Global options such as --transport are accepted after the command as well.

dimos rerun-bridge --rerun-open web --memory-limit 4GB
dimos rerun-bridge --transport lcm
RERUNBRIDGEMODULE__HOST=0.0.0.0 dimos rerun-bridge
dimos rerun-bridge --help

File Locations

Path	Contents
`~/.local/state/dimos/runs/<run-id>.json`	Run registry (PID, blueprint, args, ports). Used by `status`/`stop`/`restart`. Cleaned up when processes exit.
`~/.local/state/dimos/logs/<run-id>/main.jsonl`	Structured logs (main process + all workers)
`.env`	Local config overrides (`ROBOT_IP=192.168.123.161`)

Navigation Menu

Repository navigation

cli.md

cli.md

CLI Reference

Global Options

Configuration Precedence

Commands

`dimos run`

Adding a New Blueprint

`dimos graph`

`dimos shell`

`dimos status`

`dimos stop`

`dimos restart`

`dimos log`

`dimos list`

`dimos show-config`

`dimos cache clean`

`dimos spy`

`dimos login`

`dimos data`

`dimos host`

Agent & MCP Commands

`dimos agent-send`

`dimos mcp`

`dimos mcp list-tools`

`dimos mcp call`

`dimos mcp status`

`dimos mcp modules`

Standalone Tools

`humancli`

`lcmspy`

`agentspy`

`dtop`

`dimos rerun-bridge`

File Locations

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI Reference

Global Options

Configuration Precedence

Commands

dimos run

Adding a New Blueprint

dimos graph

dimos shell

dimos status

dimos stop

dimos restart

dimos log

dimos list

dimos show-config

dimos cache clean

dimos spy

dimos login

dimos data

dimos host

Agent & MCP Commands

dimos agent-send

dimos mcp

dimos mcp list-tools

dimos mcp call

dimos mcp status

dimos mcp modules

Standalone Tools

humancli

lcmspy

agentspy

dtop

dimos rerun-bridge

File Locations

`dimos run`

`dimos graph`

`dimos shell`

`dimos status`

`dimos stop`

`dimos restart`

`dimos log`

`dimos list`

`dimos show-config`

`dimos cache clean`

`dimos spy`

`dimos login`

`dimos data`

`dimos host`

`dimos agent-send`

`dimos mcp`

`dimos mcp list-tools`

`dimos mcp call`

`dimos mcp status`

`dimos mcp modules`

`humancli`

`lcmspy`

`agentspy`

`dtop`

`dimos rerun-bridge`