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]

Configuration Precedence¶

Values cascade (later overrides earlier):

1. GlobalConfig default → simulation = ""
2. .env file → SIMULATION=mujoco
3. Environment variable → export SIMULATION=mujoco
4. Blueprint definition → .global_config(simulation="mujoco")
5. CLI flag → dimos --simulation run ...

Environment variables and .env values use the field name in uppercase, for example ROBOT_IPS.

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> ...]

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-relocalization --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: 1. Builds and starts all modules (foreground, so you see errors) 2. Runs a health check (polls worker PIDs) 3. Forks to background, writes a run registry entry 4. 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:

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]

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]

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]

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-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.

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 (--mcp-port / --mcp-host to override).

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]

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. Can also be activated during a run with --dtop:

dimos --dtop run unitree-go2

Or run standalone:

dtop

rerun-bridge¶

Launch the Rerun visualization bridge as a standalone process (outside of a blueprint).

rerun-bridge

Also available as dimos rerun-bridge.

File Locations¶