Service CLI
npx dimo is the Host-family command-line entry. On first run it downloads the Host-family archive for this OS from GitHub Releases, verifies checksums, and starts dimo-server. After a Host is running, the same CLI sends control requests (conversations, workflows, projects, files).
It starts a headless Host and the Web UI in a browser. The desktop GUI ships as a separate installer; see the guide Install the desktop app.
The npm package name is dimo; the current version is 0.1.3. Every example below starts with npx dimo, so it runs without a global dimo install.
Help and version
npx dimo --help / npx dimo help / npx dimo -h: print the top-level usage covering Host start, local Agent install, control commands, and plugin commands. The three forms are equivalent.
npx dimo help serve: print Web UI start usage only. Replace serve with list, install, conversation, workflow, project, workspace, session, file, git, agent, or plugin for that topic. npx dimo conversation --help matches npx dimo help conversation. npx dimo help list and npx dimo help install print the local installer usage.
npx dimo --version / npx dimo -V / npx dimo version: print the CLI version, for example 0.1.3. That version also selects the default Host-family tag v0.1.3.
Starting the Host
npx dimo: start the Host on loopback127.0.0.1:17891. For local scripts and a local browser.npx dimo serve/npx dimo web: start the Host on LAN interfaces, open the Web UI, and print origins plus the Host token.webis identical toserve.npx dimo serve --local: print origins and token and serve the Web UI, bound to loopback only.npx dimo serve --port 18080: listen on18080. The default is17891.npx dimo serve --rotate-token: generate a new Host token, save it, and print it. The previous token fails immediately.npx dimo --mcp: startdimo-mcp(the local MCP server agents call). Remaining arguments go to that binary.
Flags combine, for example npx dimo serve --local --port 18080. Details: Start the Host.
Install Agents locally
These commands open the Host data directory, list or install Runtime and ACP, skip HTTP, and leave DIMO_TOKEN unused. Details: Install Agents locally.
npx dimo list: list the 13 built-in Agents, plus official ACP Registry entries whose identity is outside the built-in table.npx dimo list --refresh: fetch the official Registry snapshot, then print.npx dimo list --json: print a JSON array.npx dimo install claude_code --yes: install that Agent’s Runtime and ACP into the user environment, skipping the prompt.npx dimo install claude_code -y -g: same as the previous line.-gis accepted and has no extra meaning.
Without a terminal, --yes or -y is required. npx dimo agent list still calls a running Host; see file, git, agent.
Control commands
These require a running Host and DIMO_TOKEN in the environment. DIMO_URL defaults to http://127.0.0.1:17891. Flags, return values, and examples live on the dedicated pages.
Conversations, see conversation:
npx dimo conversation create: create a conversation and optionally submit the first message, starting the first turn.npx dimo conversation send: send text to an existing conversation. An idle conversation starts a new turn; an in-flight turn queues the text.npx dimo conversation steer: append guidance to the in-flight turn. It stays on that turn.npx dimo conversation child/npx dimo conversation fork: create a child conversation, usually to delegate to another agent. The two commands are identical.npx dimo conversation show/npx dimo conversation output: read the current output projection and turn status. The two commands are identical.npx dimo conversation relations: list parent-child relations (delegated children).npx dimo conversation wait: poll about once a second until the current turn reaches a terminal status.npx dimo conversation cancel: cancel the in-flight turn. Timeline content and files already written stay.
Workflows, see workflow:
npx dimo workflow validate: validate workflow JSON and report errors. No runnable version is created.npx dimo workflow publish: publish an immutable version after validation.npx dimo workflow run: start a run from a published version, bound to a workspace.npx dimo workflow show: fetch the run, its steps, and its events in one JSON object.npx dimo workflow wait: poll run status until a terminal state.npx dimo workflow history: read the event stream for incremental sync or debugging.npx dimo workflow cancel: stop scheduling new steps and cancel in-flight agent turns.npx dimo workflow resume: submit a decision (retry/accept/skip/cancel) when a run sits on approval, review, or a failed step.
Projects, workspaces, and session cards, see project, workspace, session:
npx dimo project list: list every project on this Host.npx dimo project show: read one project, including its repositories.npx dimo project create: register a project, optionally binding a repository path.npx dimo project delete: delete the project and its conversations and workspace data. Permanent.npx dimo workspace list: list workspaces (project root folders or Git worktrees).npx dimo workspace show: read one workspace path, branch, and parent project.npx dimo session list: list session cards on a workspace.npx dimo session show: read one session card.npx dimo session create: create a session card by workspace or by project.npx dimo session delete: delete a session record.
Files, Git, and agents, see file, git, agent:
npx dimo file tree: list a directory tree on the Host machine.npx dimo file read: read a text file on the Host.npx dimo file write: write a file on the Host. This changes disk directly.npx dimo git status: read Git status for a workspace repository.npx dimo git stage: stage a path inside the workspace.npx dimo git commit: commit staged changes.npx dimo agent list: list added agents’ auth and enabled state on a running Host. Local install usesnpx dimo list/npx dimo install.
Conventions: Control-plane conventions. Token and URL: Connect to a Host.
Other
npx dimo plugin: pack a.vxp, plusadd/list/update/remove/gc-runtimes/test --host. See plugin.npx dimo review: this entry is outside the Host family and exits with an error.
Next: Install and versions, Start the Host, Connect to a Host.