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

1. GlobalConfig default → simulation = False
2. .env file → DIMOS_SIMULATION=true
3. Environment variable → export DIMOS_SIMULATION=true
4. Blueprint definition → .global_config(simulation=True)
5. CLI flag → dimos --simulation run ...

Environment variables and .env values must be prefixed with DIMOS_.

---

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:

1. Builds and starts all modules (foreground — 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 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 (DIMOS_ROBOT_IP=192.168.123.161)