dimos/docs/usage/cli.md at main · dimensionalOS/dimos

title	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` / `--no-simulation`	bool	`False`	Enable MuJoCo simulation
`--replay` / `--no-replay`	bool	`False`	Use recorded replay data
`--replay-db`	TEXT	`go2_bigoffice`	Replay memory2 SQLite database name
`--new-memory` / `--no-new-memory`	bool	`False`	Clear persistent memory on start
`--viewer`	`rerun\|none`	`rerun`	Visualization backend
`--rerun-open`	`native\|web\|both\|none`	`native`	How to open the Rerun viewer
`--rerun-web` / `--no-rerun-web`	bool	`False`	Serve the Rerun web viewer
`--n-workers`	INT	`2`	Number of forkserver workers
`--memory-limit`	TEXT	`auto`	Rerun viewer memory limit
`--mcp-port`	INT	`9990`	MCP server port
`--mcp-host`	TEXT	`127.0.0.1`	MCP server bind address
`--transport`	`lcm\|zenoh`	platform-dependent	Transport backend for streams, RPC, and TF. Defaults to `zenoh` on macOS, otherwise `lcm`. 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
`--obstacle-avoidance` / `--no-obstacle-avoidance`	bool	`True`	Enable obstacle avoidance
`--detection-model`	`qwen\|moondream`	`moondream`	Vision model for object detection
`--robot-model`	TEXT	`None`	Robot model identifier
`--robot-width`	FLOAT	`0.3`	Robot width in meters
`--robot-rotation-diameter`	FLOAT	`0.6`	Robot rotation diameter in meters
`--planner-strategy`	`simple\|mixed`	`simple`	Navigation planner strategy
`--planner-robot-speed`	FLOAT	`None`	Planner robot speed override
`--mujoco-camera-position`	TEXT	`None`	MuJoCo camera position
`--mujoco-room`	TEXT	`None`	MuJoCo room model
`--mujoco-room-from-occupancy`	TEXT	`None`	Generate room from occupancy map
`--mujoco-global-costmap-from-occupancy`	TEXT	`None`	Generate costmap from occupancy
`--mujoco-global-map-from-pointcloud`	TEXT	`None`	Generate map from point cloud
`--mujoco-start-pos`	TEXT	`-1.0, 1.0`	MuJoCo robot start position
`--mujoco-steps-per-frame`	INT	`7`	MuJoCo simulation steps per frame

Configuration Precedence

Values cascade (later overrides earlier):

GlobalConfig default → simulation = ""
.env file → SIMULATION=mujoco
Environment variable → export SIMULATION=mujoco
Blueprint definition → .global_config(simulation="mujoco")
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> ...]

Option	Description
`--config` `-c`	Path to read JSON config file from (options can be overriden with `-o`
`--daemon`, `-d`	Run in background (double-fork, health check, writes run registry)
`--disable`	Module class names to exclude from the blueprint
`--option`, `-o`	Provide an configuration option to the blueprint (e.g. `-o voxelgridmapper.voxel_size=1`
`--help`	Display the available configuration options that can be changed with `-o` or the config file

# 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

# Replay Big Office (on Linux use --transport=zenoh; on macOS Zenoh is default when installed)
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

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

On macOS, heavy replay workloads can be unreliable over LCM UDP, so the default transport resolves to zenoh; 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 — 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 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-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 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

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 '{}']

Option	Description
`--arg`, `-a`	Arguments as `key=value` pairs (repeatable)
`--json-args`, `-j`	Arguments as a JSON string

dimos mcp call relative_move --arg forward=0.5
dimos mcp call relative_move --json-args '{"forward": 2.0, "left": 0, "degrees": 0}'
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

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`)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Global Options

Configuration Precedence

Commands

`dimos run`

Adding a New Blueprint

`dimos status`

`dimos stop`

`dimos restart`

`dimos log`

`dimos list`

`dimos show-config`

`dimos spy`

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`

`rerun-bridge`

File Locations

Uh oh!

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

Global Options

Configuration Precedence

Commands

dimos run

Adding a New Blueprint

dimos status

dimos stop

dimos restart

dimos log

dimos list

dimos show-config

dimos spy

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

rerun-bridge

File Locations

`dimos run`

`dimos status`

`dimos stop`

`dimos restart`

`dimos log`

`dimos list`

`dimos show-config`

`dimos spy`

`dimos agent-send`

`dimos mcp`

`dimos mcp list-tools`

`dimos mcp call`

`dimos mcp status`

`dimos mcp modules`

`humancli`

`lcmspy`

`agentspy`

`dtop`

`rerun-bridge`