Dimo

Install and versions

npx dimo needs Node.js on this machine (npx ships with it). A global dimo install is optional; this documentation always writes npx dimo … so the current npm-resolved package is used.

The first npx dimo, npx dimo serve, npx dimo list, npx dimo install, or npx dimo --mcp run picks a Host-family archive from OS and CPU:

  • linux-x64, linux-arm64
  • macos-x64, macos-arm64
  • windows-x64, windows-arm64

macOS under Rosetta selects macos-arm64. Any other combination exits with Unsupported platform and the supported list.

Download progress prints to stderr. After checksums pass, dimo-server starts (or dimo-mcp for npx dimo --mcp). Later runs for the same tag and platform reuse the cache.

Print the CLI version:

bash
npx dimo --version
npx dimo -V
npx dimo version

The output looks like 0.1.3. That version maps to the default Host-family tag v0.1.3.

Cache and local directory

Downloads land in ~/.dimo/host-family/<tag>/<platform>/. After checksums pass, the tree is extracted and dimo-server / dimo-mcp are marked executable on Unix.

Point the CLI at an already extracted tree to skip download:

bash
export DIMO_HOST_FAMILY_DIR=/path/to/extracted-family
npx dimo serve --local

That directory must contain SHA256SUMS. Every file listed there is verified. A missing file or a digest mismatch raises Checksum mismatch or Host family is missing dimo-server.

Pinning and mirrors

Variable Role Default
DIMO_HOST_FAMILY_TAG Release tag v plus the CLI version, e.g. v0.1.3
DIMO_HOST_FAMILY_BASE URL prefix for the tarball https://github.com/DimoADE/Dimo/releases/download/<tag>
DIMO_GITHUB_REPO GitHub owner/name DimoADE/Dimo
DIMO_HOST_FAMILY_DIR Extracted family directory empty; use the download cache
DIMO_DEBUG Print CLI stacks on failure empty
bash
DIMO_HOST_FAMILY_TAG=v0.1.3 npx dimo serve --local
DIMO_DEBUG=1 npx dimo --version

Artifact names: dimo-host-family-<platform>.tar.gz and .tar.gz.sha256. The archive contains dimo-server, dimo-mcp, web/, and plugins/bundled/.

Running the extracted dimo-server with the same flags matches npx dimo. npx additionally sets DIMO_STATIC_ROOT to the packaged web/ tree so the Web UI static files are served.

Variable meanings and failures: Environment and troubleshooting. Start flags: Start the Host.

Start the Host

The Host process is dimo-server inside the family archive. npx dimo downloads that binary and starts it with the given flags. The default listen address is 127.0.0.1:17891. Projects, conversations, and plugins live in the local data directory; the Host token is stored there as well.

One data directory has one Host at a time. If the desktop app already occupies that directory, quit the desktop app before the commands below.

npx dimo

bash
npx dimo

Starts the Host on loopback and leaves LAN interfaces unbound. Use it for local scripts and opening http://127.0.0.1:17891 on this machine. The token stays in the data directory; the terminal omits the Token block by default. Control commands use the saved token, or DIMO_SERVER_TOKEN set before start.

This matches running ./dimo-server in an extracted family directory (dimo-server.exe on Windows). npx also sets DIMO_STATIC_ROOT to packaged web/ so the browser UI is available.

npx dimo serve / npx dimo web

bash
npx dimo serve
npx dimo web

The two commands are identical. web is an alias of serve. The Host listens on every NIC so a phone or another computer on the LAN can connect. After start the terminal prints:

text
Dimo Host 0.1.3
  http://127.0.0.1:17891
  http://192.168.x.x:17891
Token
  <host-token>

Export the line under Token as DIMO_TOKEN so control commands can call this Host. Open any printed http://… origin in a browser for the Web UI. Desktop Settings → Remote connection uses the same port and the same token.

Phone QR pairing needs the LAN origin. A 127.0.0.1 QR is unreachable from the phone.

npx dimo serve --local

bash
npx dimo serve --local

Runs the serve start path: print origins and token, serve the Web UI. Binds loopback only. Use it when this machine needs the Web UI and control commands, and the port should stay local.

--local on the command line overrides DIMO_SERVER_ALLOW_LAN=1.

npx dimo serve --port 18080

bash
npx dimo serve --port 18080
npx dimo serve --port=18080

Listen on 18080. The default is 17891. --port N and --port=N are equivalent. After changing the port, set DIMO_URL to http://127.0.0.1:18080. Browser URLs use the new port as well. Use this when 17891 is already taken.

A non-numeric port prints invalid --port and exits. A missing value prints missing value for --port.

npx dimo serve --rotate-token

bash
npx dimo serve --rotate-token

Generate a new Host token, write it to the data directory, and print it. Control commands and paired devices that still use the old token fail immediately; they need the new token or a new pairing. Use this after a suspected leak, or to drop every old device.

Rotation changes authentication only. Projects, conversations, and plugins stay in the same data directory.

npx dimo serve --lan

bash
npx dimo serve --lan

Allow listening on every NIC. npx dimo serve already enables LAN; this flag is the explicit form when combining with npx dimo (loopback) or when invoking dimo-server --lan directly.

If both --local and --lan are present, the process binds loopback only.

npx dimo --mcp

bash
npx dimo --mcp

Start dimo-mcp. The CLI strips --mcp and forwards remaining arguments to that binary. That process exposes local MCP tools to agents and has no Web UI. For the UI, use npx dimo or npx dimo serve.

Combined examples

bash
npx dimo serve --local --port 18080
npx dimo serve --rotate-token --port 17891

Environment variables can change defaults without extra flags: DIMO_SERVER_ALLOW_LAN=1 enables LAN; DIMO_SERVER_LISTEN=18080 or DIMO_SERVER_LISTEN=127.0.0.1:18080 overrides the port; DIMO_SERVER_TOKEN=… sets the token used at start. Full list: Environment and troubleshooting.

Unknown arguments fail parse and exit. npx dimo --help prints start usage. SIGINT (Ctrl+C) or SIGTERM stop the child; Windows uses taskkill /t.

To list Agents and install Runtime and ACP on this machine, use npx dimo list and npx dimo install. No port is bound. See Install Agents locally.

Install Agents locally

npx dimo list and npx dimo install list Agents and install Runtime and ACP on this machine. They open the same Host data directory (the same SQLite) as npx dimo serve. No port is bound. DIMO_TOKEN is unused. The HTTP service can stay down.

npx dimo agent list calls a Host that is already running and reads auth and enabled state for members already added. The commands on this page read and write the local Installation lock.

The first run still downloads the Host-family archive when needed, then forwards arguments to dimo-server. npx omits Starting Dimo Host for these utilities.

npx dimo list

List Agents this Host can install. The first group is the 13 built-in Agents. The second group is official ACP Registry entries whose identity sits outside the built-in table.

bash
npx dimo list

The default read uses the Registry snapshot already cached on this machine. If it has never been refreshed, the ACP Registry section prints:

text
  (refresh with `dimo-server list --refresh`)

Each row has four columns: Agent id, display name, status, component detail. Example:

text
Built-in
  claude_code   Claude Code     uninstalled   adapter claude + claude-agent-acp
  codex         Codex           ready         adapter codex + codex-acp
  ...
ACP Registry
  some-agent    Some Agent      available     npx

Status comes from the local Installation lock:

  • ready: Runtime and ACP are in the lock; npx dimo serve can create a session with that Agent.
  • needs_repair: a lock exists and components need repair.
  • uninstalled: a built-in identity has no lock yet.
  • available: the Registry has the entry; membership / lock are not in place yet.

The last column on a built-in row is topology, for example adapter claude + claude-agent-acp or native …. A Registry row lists distribution kinds: npx, uvx, binary, or a combination.

Pass the Agent id (for example claude_code) to npx dimo install.

npx dimo list --refresh

bash
npx dimo list --refresh

Fetch a snapshot from the official ACP Registry, write it into the Host database, then print the catalog. Use this when a script needs the latest Registry entries. If refresh fails and a cache exists, the terminal prints registry refresh failed; using the cached snapshot and lists the cache. With no cache it fails: ACP Registry is unavailable.

npx dimo list --json

bash
npx dimo list --json
npx dimo list --refresh --json

Print an indented JSON array. Each object has agent_id, display_name, description, group (built_in or registry), status, and detail. --refresh and --json combine.

npx dimo install

Install that Agent’s Runtime and ACP into the user environment. After a successful ACP handshake, write the Installation lock.

bash
npx dimo install claude_code
npx dimo install claude_code --yes
npx dimo install claude_code -y
npx dimo install claude_code -y -g
npx dimo install some-agent --yes

<agent-id> is required and comes from the first column of npx dimo list. A missing id prints Usage: dimo-server install <agent-id> [--yes] and exits non-zero. An unknown id prints unknown Agent …; run dimo-server list.

With a terminal and without --yes, the CLI prints the Plan (component id, distribution kind, source) and asks:

text
Install these user-environment packages? [y/N]

y / yes continues. Any other answer cancels with installation canceled.

npx dimo install --yes / npx dimo install -y

bash
npx dimo install claude_code --yes
npx dimo install claude_code -y

Skip the prompt and install the Plan. When there is no terminal, --yes or -y is required; otherwise the CLI prints pass --yes to install without a prompt. Use this in CI, pipes, and any non-TTY script.

npx dimo install -g

bash
npx dimo install claude_code -y -g
npx dimo install claude_code --yes --global

-g and --global are accepted and ignored. Install already writes the user environment (the user npm prefix, uv tools, ~/.local/bin). There is no second global/local mode.

What install does

npx dimo install runs these steps:

  1. Open the Host data directory (DIMO_DATA_DIR overrides it) and use the same SQLite as npx dimo serve.
  2. A built-in Agent goes straight into the plan. A Registry Agent is added to membership first, then planned.
  3. Components already on PATH at a version at least as new as the lock are reused, with Reusing … at …. When the whole plan is already satisfied, it prints Using the user-environment CLI that already matches the locked versions.
  4. Remaining components are written into the user environment: npm install -g --prefix …, uv tool install, or a Binary download into ~/.local/bin.
  5. Handshake the installed ACP. On success, write the Installation lock and set lifecycle to ready. A success line looks like Installed claude_code runtime … / ACP ….
  6. npx dimo serve can then create a session with that Agent.

Missing Node/npm prints npm was not found; install Node.js and npm first. Missing uv prints uv was not found; install uv first. The CLI uses the toolchain already on this machine. A hosted Node stays out of this path.

User-declared Agents are installed from desktop Settings → Agents. A retired identity fails this command.

Calling the binary

npx dimo forwards these arguments to dimo-server. With an extracted Host family you can invoke the binary directly:

bash
dimo-server list
dimo-server list --refresh
dimo-server list --json
dimo-server install claude_code --yes
dimo-server agents list
dimo-server agents install codex
dimo-server agents install claude_code --yes

dimo-server agents list matches dimo-server list. dimo-server agents install matches dimo-server install. On Windows the executable is dimo-server.exe.

Help

bash
npx dimo help list
npx dimo list --help
npx dimo help install
npx dimo install --help

These forms print usage only. The data directory stays closed. The Registry stays untouched.

Common failures

pass --yes to install without a prompt: there is no terminal. Add npx dimo install AGENT_ID --yes.

installation canceled: the confirm prompt was not answered with y / yes.

npm was not found; install Node.js and npm first / uv was not found; install uv first: install that toolchain on this machine, then rerun npx dimo install.

ACP Registry is empty: run npx dimo list --refresh first.

unknown Agent: the id is missing from the built-in table and from the current Registry snapshot. Run npx dimo list or npx dimo list --refresh.

could not open the Host data directory: the data directory could not be created or opened. Check DIMO_DATA_DIR and disk permissions.

ACP process exited before initialize: the installed ACP failed handshake. Inspect that Agent’s install output, fix it, then run npx dimo install again.

Connect to a Host

Control commands call a running Host over HTTP:

text
POST {DIMO_URL}/api/v1/call/{command}
Authorization: Bearer {DIMO_TOKEN}
Content-Type: application/json
x-dimo-protocol-version: 1.0

The body is { "operation_id": "<uuid>", "args": { ... } }. On success, stdout prints data. On HTTP error the process exits non-zero and prints code: message.

Start the Host first (npx dimo or npx dimo serve), export the token in the same shell, then run control commands such as npx dimo agent list.

Environment variables

Variable Role Default
DIMO_URL Host root URL; trailing slashes are stripped http://127.0.0.1:17891
DIMO_TOKEN Host token, required none; missing yields DIMO_TOKEN is required
bash
export DIMO_URL=http://127.0.0.1:17891
export DIMO_TOKEN='<paste-token>'
npx dimo agent list

Token sources:

  1. The Token block from npx dimo serve.
  2. Access Token under desktop Settings → Remote connection, for the same Host.
  3. The value supplied as DIMO_SERVER_TOKEN at start.

Keep the token in the environment, the OS keychain, or the Host data directory. Repositories, chat logs, and shell history that will be committed should hold placeholders only. After rotation the previous token fails immediately; point every control command at the new value. Rotation is npx dimo serve --rotate-token.

After a port change, update DIMO_URL as well. If the Host ran npx dimo serve --port 18080, then export DIMO_URL=http://127.0.0.1:18080.

Local browser

With npx dimo serve --local or a loopback origin, open http://127.0.0.1:17891 on this machine. Web UI files come from DIMO_STATIC_ROOT (npx points at packaged web/). Agents, Git, and the terminal still execute on the Host machine.

With plain npx dimo (no serve), the token is omitted from the terminal by default. The local browser can still open the loopback origin; control commands need the token from the data directory or DIMO_SERVER_TOKEN.

LAN and workstations

npx dimo serve listens on every NIC by default. A browser or another desktop on the same LAN uses the printed LAN origin and token. Phone QR pairing needs LAN enabled; a 127.0.0.1 QR is unreachable from the phone. Pairing presets are in the guide Connect to a Host.

Public access terminates TLS on a reverse proxy, then forwards to the Host port. Set DIMO_URL to https://host.example.

Occupancy

One data directory has one Host at a time. When dimo-server occupies the directory, the desktop attaches as a client to that URL. When the desktop occupies the directory, another npx dimo fails or conflicts; stop one process first.

While the Host is offline, control commands fail immediately. Offline cache exists only on paired client UIs.

Control-plane conventions

Control commands run after the Host is up. They call the Host over HTTP; agent processes stay on the Host. Finish Start the Host and Connect to a Host, then export DIMO_TOKEN.

Command shape:

bash
npx dimo <resource> <action> --flag value

Example: npx dimo conversation create --workspace … --agent …. Resources are conversation, workflow, project, workspace, session, file, git, agent. Actions are create, list, show, and so on. Tokens that start with -- are flags. A flag with no value, or whose next token also starts with --, is treated as on. Other flags take the following token as a string. A leftover token without -- raises Unexpected argument.

Help for each resource

These three forms print usage and skip HTTP:

bash
npx dimo conversation --help
npx dimo conversation help
npx dimo conversation -h

Replace conversation with workflow, project, workspace, session, file, git, or agent. Top-level help is npx dimo help. Per-topic help is also npx dimo help conversation.

npx dimo … --json

Print the result as one-line JSON for jq. Without the flag, objects and arrays still print as indented JSON; a bare string prints as-is.

bash
npx dimo agent list --json
npx dimo conversation show --conversation CONV_ID --json

npx dimo … --operation-id

Supply an idempotency key. The default is a generated UUID. When a script retries the same business operation, reuse one --operation-id so the Host treats both calls as one write.

bash
npx dimo conversation send \
  --conversation CONV_ID \
  --workspace WORKSPACE_ID \
  --agent AGENT_ID \
  --text "continue" \
  --operation-id 11111111-1111-1111-1111-111111111111

npx dimo … --timeout

Applies to wait commands only, in seconds, default 600. If the status is still non-terminal, the CLI raises Timed out after 600s.

bash
npx dimo conversation wait --conversation CONV_ID --timeout 120
npx dimo workflow wait --run RUN_ID --timeout 1800

Call contract

Every request carries operation_id. --conversation, --workspace, --agent, --id, and --run take stable Host IDs, usually UUIDs. Obtain IDs with npx dimo project list, npx dimo workspace list, npx dimo agent list, or the matching create, then pass them onward.

A missing required flag raises Missing required --name. An unknown action raises Unknown … action. HTTP failures exit non-zero and print code: message. If the Host is down or DIMO_URL is wrong, the error comes from the network layer.

conversation

Conversation commands operate a persistent dialogue between you and one agent on the Host. A turn is one cycle of “you send a message → the agent finishes answering”. At most one turn is in flight per conversation. The agent and workspace must already exist, and the agent must be enabled and authenticated. Start with npx dimo agent list and npx dimo workspace list to obtain IDs.

A running Host and DIMO_TOKEN are required. See Connect to a Host.

npx dimo conversation create

Create a conversation and optionally send the first message immediately.

bash
npx dimo conversation create \
  --workspace WORKSPACE_ID \
  --agent AGENT_ID \
  [--title TITLE] \
  [--prompt TEXT]

--workspace is the workspace ID (project root or a Git worktree), required. --agent is the agent’s stable kind, for example claude_code or codex, required. --title is the display name; omit it and the Host may name the conversation from the first message. --prompt is submitted as the first user message and starts the first turn.

The response is the new conversation JSON, including id. Later npx dimo conversation send, npx dimo conversation wait, and npx dimo conversation show take that ID as --conversation.

If the agent is disabled or unauthenticated, the Host rejects create. Enable and sign in under desktop Settings → Agents, then confirm with npx dimo agent list.

npx dimo conversation send

Send text to an existing conversation. An idle conversation starts a new turn. If a turn is already running, the text enters the input queue and runs in order after the current turn ends.

bash
npx dimo conversation send \
  --conversation CONV_ID \
  --workspace WORKSPACE_ID \
  --agent AGENT_ID \
  --text TEXT

All four flags are required. --text is plain text. This command sends text only: no images, attachments, or plugin actions. --workspace and --agent must match the conversation’s original binding.

The response is the submit JSON. Read turn status afterward with npx dimo conversation show or npx dimo conversation wait.

npx dimo conversation steer

Append guidance to the in-flight turn. It belongs to that turn; no new turn is created.

bash
npx dimo conversation steer \
  --conversation CONV_ID \
  --turn TURN_ID \
  --text TEXT

--turn must be the in-flight turn ID, from the turn field of npx dimo conversation show. All three flags are required. If the agent has no steering capability, the Host returns an error; the text stays a steering request and queued input is unchanged.

With no in-flight turn, the Host returns an error. To add work to an idle conversation, use npx dimo conversation send.

npx dimo conversation child / npx dimo conversation fork

Create a child conversation of an existing one, usually for delegation: the parent agent hands part of the work to another agent. npx dimo conversation fork matches npx dimo conversation child.

bash
npx dimo conversation child \
  --parent CONV_ID \
  --agent AGENT_ID \
  [--title TITLE] \
  [--prompt TEXT] \
  [--hidden]

--parent is the parent conversation ID. --agent is the agent for the child. --title and --prompt match npx dimo conversation create. --hidden marks the child invisible (visible=false). Enable Multi-agent collaboration under Settings → Plugins first; otherwise delegation is unavailable.

The response is the child conversation JSON. List relations later with npx dimo conversation relations --conversation CONV_ID.

npx dimo conversation show / npx dimo conversation output

Read the current output projection, including recent messages and turn.status. npx dimo conversation output matches npx dimo conversation show.

bash
npx dimo conversation show --conversation CONV_ID
npx dimo conversation show --conversation CONV_ID --json

--conversation is required. --json prints one line so scripts can read turn.status. Terminal statuses are completed, failed, cancelled, and interrupted.

npx dimo conversation relations

List parent-child relations (delegated children). Use the child IDs with npx dimo conversation show or npx dimo conversation cancel.

bash
npx dimo conversation relations --conversation CONV_ID

--conversation is required. With no children the response is an empty list.

npx dimo conversation wait

Poll the same read as npx dimo conversation show about once a second until turn.status is completed, failed, cancelled, or interrupted.

bash
npx dimo conversation wait --conversation CONV_ID [--timeout 600]

--conversation is required. --timeout is seconds, default 600. Timeout raises Timed out after Ns. The turn may still be running; inspect with npx dimo conversation show, or raise the timeout and wait again.

npx dimo conversation cancel

Cancel the in-flight turn. Timeline content and files already written stay.

bash
npx dimo conversation cancel --conversation CONV_ID [--reason TEXT]

--conversation is required. --reason is optional and stored as the cancel reason. To revert files, use Undo on that turn in the desktop session. With no in-flight turn, the Host returns an error.

Example sequence

bash
export DIMO_TOKEN='…'
export DIMO_URL=http://127.0.0.1:17891

npx dimo conversation create \
  --workspace "$WS" \
  --agent claude_code \
  --prompt "List the top-level directory" \
  --json
# read id from the output into CONV_ID

npx dimo conversation wait --conversation "$CONV_ID"
npx dimo conversation show --conversation "$CONV_ID"

workflow

Workflow commands operate a step graph: send a JSON source file to the Host for validation, publish an immutable version, then run that version. The file must be a JSON object; its path is --file. The workspace must already exist.

A running Host and DIMO_TOKEN are required. Graph editing and Studio are in the guide Graph Workflow.

npx dimo workflow validate

Validate only. No runnable version is created. Use it to check graph structure, dependencies, and step contracts before publish. Failures print the Host error code.

bash
npx dimo workflow validate --file path/to/graph.json

--file is required and must be a JSON file readable on this machine. The contents are sent as the definition. An invalid path or unparsable JSON fails in the CLI before the HTTP call.

npx dimo workflow publish

After validation, create an immutable workflow definition version. Later edits to the source file affect the next publish only; runs already started stay bound to this version.

bash
npx dimo workflow publish --file path/to/graph.json [--definition-id ID]

--file is required. --definition-id binds an existing workflow identity for a new version; omit it and the Host allocates a new identity. Pass the returned version ID to npx dimo workflow run --version.

npx dimo workflow run

Start a run from a published version, bound to a workspace.

bash
npx dimo workflow run \
  --version VERSION_ID \
  --workspace WORKSPACE_ID \
  [--input input.json] \
  [--policy policy.json]

--version and --workspace are required. --input defaults to {} and must be a local JSON file. --policy defaults to empty and overrides completion policy. The response is the run object; store id for npx dimo workflow show, npx dimo workflow wait, and npx dimo workflow cancel.

An unpublished source file cannot be run. Publish first with npx dimo workflow publish.

npx dimo workflow show

Fetch the run, its steps, and events (from sequence 0, up to 1000) and print them as one JSON object. Use it to see a stuck step and a waiting approval.

bash
npx dimo workflow show --run RUN_ID
npx dimo workflow show --run RUN_ID --json

--run is required. The object contains run, steps, and events. Step IDs come from steps and go to npx dimo workflow resume --step.

npx dimo workflow wait

Poll this run’s status until it reaches completed, failed, cancelled, interrupted, or the timeout.

bash
npx dimo workflow wait --run RUN_ID [--timeout 600]

--run is required. --timeout defaults to 600 seconds. After timeout, inspect the current step with npx dimo workflow show. A run sitting on approval is still non-terminal; wait continues until timeout or someone runs npx dimo workflow resume.

npx dimo workflow history

Read the event stream for incremental sync or debugging.

bash
npx dimo workflow history --run RUN_ID [--after N] [--limit 1000]

--run is required. --after is the last processed sequence, default 0. --limit defaults to 1000. A script can remember the last sequence and pass --after to fetch only new events.

npx dimo workflow cancel

Stop scheduling new steps and cancel in-flight agent turns. File changes already made stay in the workspace.

bash
npx dimo workflow cancel --run RUN_ID [--reason TEXT]

--run is required. --reason is optional. Cancelling an already finished run returns a Host error.

npx dimo workflow resume

When a run sits on approval, review, or a failed step, submit a human decision to continue.

bash
npx dimo workflow resume \
  --run RUN_ID \
  --decision retry|accept|skip|cancel \
  [--step STEP_ID] \
  [--output output.json] \
  [--reason TEXT]

--run and --decision are required. --decision values:

  • retry: run that step again; --step required
  • skip: skip that step; --step required
  • accept: accept the step’s candidate output; --step required; with --output, that JSON is the accepted content
  • cancel: end the whole run; optional --reason; --step omitted

Step IDs come from the steps list of npx dimo workflow show. A missing required --step raises Missing required --step.

project, workspace, session

These commands manage projects (engineering directories), workspaces (the directory tree a conversation reads and writes), and session lists on the Host. Paths are paths on the Host machine. A running Host and DIMO_TOKEN are required.

A project registers an engineering tree. A workspace is the directory bound to a conversation (project root or a Git worktree). A session card is a board entry. Dialogue content and turns use the conversation commands.

npx dimo project list

List every project on this Host.

bash
npx dimo project list
npx dimo project list --json

No extra flags. The response is an array of projects, each with id, name, repository paths, and related fields. Use id with npx dimo project show, npx dimo project delete, and npx dimo session create --project.

npx dimo project show

Read one project, including its repositories (the git repo IDs used as --repo on npx dimo git).

bash
npx dimo project show --id PROJECT_ID

--id is required. An unknown ID returns a Host error.

npx dimo project create

Register a project on the Host. With only a name, the Host creates or binds a directory by its own rules. With --path, that path is registered as a repository.

bash
npx dimo project create --name demo
npx dimo project create --name demo --path /home/you/src/demo

--name is required. --path is optional and must be a Git directory the Host can access, or a directory it will initialize. When --path is set, the repository display_name matches the project name and git_repo_path is that path. The response is the new project JSON; store id.

The path is on the Host machine. Running the CLI on another computer still points at the Host’s filesystem.

npx dimo project delete

Delete the project and its conversations and workspace data. Permanent.

bash
npx dimo project delete --id PROJECT_ID

--id is required. An in-progress conversation may cause the delete to fail; the Host returns the error. Confirm the target with npx dimo project show first. The Host response records what happens to the Git repository on disk.

npx dimo workspace list

List workspaces. A workspace is the directory bound to a conversation: the project root folder, or a Git worktree cut from that folder.

bash
npx dimo workspace list
npx dimo workspace list --project PROJECT_ID

Without --project, every workspace on the Host is listed. With --project, only that project’s trees. Each item includes a workspace id, used as --workspace on npx dimo conversation create and npx dimo session list.

New worktrees are created in the desktop New session → New workspace flow, then discovered with this command. This CLI has no separate “create worktree” action.

npx dimo workspace show

Read one workspace’s path, branch, and parent project.

bash
npx dimo workspace show --id WORKSPACE_ID

--id is required. Use it to confirm which directory tree a conversation will read and write.

npx dimo session list

List session cards on a workspace (the board entries).

bash
npx dimo session list --workspace WORKSPACE_ID

--workspace is required. The response includes session ID, title, agent, and status. Missing --workspace raises Missing required --workspace.

npx dimo session show

Read one session card.

bash
npx dimo session show --id SESSION_ID

--id is required. Difference from npx dimo conversation show: this command is the board/catalog record; npx dimo conversation show is dialogue output and turn status. In most cases the two IDs name the same conversation; trust the returned JSON.

npx dimo session create

Create a session card. Two shapes.

By workspace (the workspace must already exist):

bash
npx dimo session create \
  --workspace WORKSPACE_ID \
  [--agent AGENT_ID] \
  [--title TITLE] \
  [--prompt TEXT]

By project (the Host may pick the project’s default workspace):

bash
npx dimo session create \
  --project PROJECT_ID \
  [--workspace WORKSPACE_ID] \
  [--agent AGENT_ID] \
  [--title TITLE] \
  [--prompt TEXT]

--title, --prompt, and --agent are all optional. To bind an agent and send the first message immediately, npx dimo conversation create is the direct path. This command fits creating a board entry from a project catalog. The ID in the JSON can be passed to npx dimo conversation send.

With --project, the project-create API is used and --workspace may be omitted. With only --workspace (no --project), the workspace-create API is used. Missing both raises Missing required --workspace.

npx dimo session delete

Delete a session record. The Host decides whether an in-progress session can be removed; failures print an error.

bash
npx dimo session delete --id SESSION_ID

--id is required. This removes the Host session record. The workspace directory and Git history stay on disk.

file, git, agent

These commands read and write files on the Host machine, stage and commit Git changes, and list agents. Paths are resolved by the Host and belong to that machine. A caller with the Host token is authorized; production scripts keep paths inside a known workspace. A running Host and DIMO_TOKEN are required.

npx dimo file tree

List the file tree under a directory.

bash
npx dimo file tree --path /home/you/src/demo
npx dimo file tree --path /home/you/src/demo --depth 2

--path is required and is an absolute path on the Host. --depth is how many levels to expand, default 3, and must be a number. Use it in scripts to confirm layout before npx dimo file read / npx dimo file write. A missing path returns a Host error.

npx dimo file read

Read a file’s text and print it.

bash
npx dimo file read --path /home/you/src/demo/README.md

--path is required. Large or binary files may be truncated or rejected; the error code is in the response. Default print is the text; with --json the whole contents are a JSON string.

npx dimo file write

Write contents to a file on the Host. Supply --text or --file; if both are present, --text is used.

bash
npx dimo file write --path /home/you/src/demo/notes.md --text "hello"
npx dimo file write --path /home/you/src/demo/notes.md --file ./local.md

--path is required. --file points at a local file on the machine running the CLI; contents are read as UTF-8 and sent to the Host. This writes disk directly, with no agent permission prompt. Missing both content sources raises Missing required --file.

npx dimo git status

Read Git status (changed files, branch, and related fields) for a workspace repository.

bash
npx dimo git status --workspace WORKSPACE_ID --repo REPO_ID

--workspace and --repo are required. --repo comes from the repository list in npx dimo project show --id PROJECT_ID. Exact fields are those in the JSON.

npx dimo git stage

Stage one path inside the workspace.

bash
npx dimo git stage --workspace WORKSPACE_ID --repo REPO_ID --path relative/path.ts

All three flags are required. --path is relative to the workspace. One path per call; repeat the command for more files.

npx dimo git commit

Create a commit from staged changes.

bash
npx dimo git commit --workspace WORKSPACE_ID --repo REPO_ID --message "describe this change"

--workspace, --repo, and --message are required. An empty index returns a Host error. Push, pull requests, and rebase stay in the desktop Git panel, or an agent performs them after approval. This CLI stops at commit.

npx dimo agent list

List agents added to the Host, with install, auth, and enabled status.

bash
npx dimo agent list
npx dimo agent list --json

No extra flags. The stable kind in the array (for example claude_code) is the value for --agent. Disabled or unauthenticated rows still appear; npx dimo conversation create against them is rejected. Enable and sign in under desktop Settings → Agents first.

This command needs a running Host and DIMO_TOKEN. To list installable Agents and write Runtime and ACP on this machine, use npx dimo list and npx dimo install; HTTP can stay down. See Install Agents locally. Sign-in remains desktop Settings → Agents.

plugin

npx dimo plugin packs a deterministic .vxp and installs, lists, updates, uninstalls, and publishes packages on the current Host and the official marketplace. Templates and harness tests use dimo-plugin (source at packages/plugin-cli). Bind a Host with dimo plugin run server, then dimo plugin run dev from the plugin directory. See Development workflow.

When desktop or npx dimo serve is running, the command finds the local Host token. If no Host is up, add writes snapshots to ~/.dimo/imports/ and linked directories to ~/.dimo/imports/links.jsonl; the next launch imports them. Default URL is http://127.0.0.1:17891; override with DIMO_URL / DIMO_TOKEN. list, update, remove, gc-runtimes, and test --host need a running Host.

npx dimo plugin pack

bash
npx dimo plugin pack
npx dimo plugin pack .
npx dimo plugin pack ./my-plugin
npx dimo plugin pack ./my-plugin --output ./dist/office.vxp

The first argument is the plugin root; it defaults to the current directory. That directory must contain .dimo-plugin/plugin.json, README.md, and the rest of the layout in Package layout.

Order of work: full validation first (summary, schema, content index, integration refs). Failures print each code: message line and exit. On success a .vxp is written and stdout prints two lines:

text
/absolute/path/dist/<plugin-id>-<version>.vxp
sha256:<packageDigest>

--output sets the result file. The default is dist/<plugin-id>-<version>.vxp inside the plugin directory.

The same source packed twice with npx dimo plugin pack should yield the same sha256. Published npx packages embed plugin-cli under plugin-cli/. A missing directory raises Dimo Plugin CLI is unavailable; reinstall or upgrade the dimo npm package.

npx dimo plugin add

bash
npx dimo plugin add --web <git-or-url[#ref]> [--plugin ID] [--yes]
npx dimo plugin add --profile <file.vxp|archive> [--plugin ID] [--yes]
npx dimo plugin add --dev <dir> [--yes] [--detach]

--web accepts a marketplace page, Git repository, GitHub Release, or archive URL. #tag, #branch, and #commit pin the tree. A GitHub Release that ships a .vxp verifies SHA-256 when a digest or sibling .sha256 is present. --profile installs a local archive. --dev links a development directory: it builds first, then the Host watches the digest; without --detach it prints Worker stderr; --detach returns after linking. HMR is started by dimo plugin run dev. Use only one of the three modes. Without a flag, the command infers directory, file, or URL.

Add --plugin when the archive contains more than one package. Use --yes when stdin is not a TTY.

User path: Install a Plugin from the marketplace. Linked development: Development workflow.

npx dimo plugin list / update / remove

bash
npx dimo plugin list [--json]
npx dimo plugin update <id> [--ref tag] [--yes]
npx dimo plugin remove <id> [--yes] [--delete-data]
npx dimo plugin gc-runtimes

list is the Installed catalog, including source and lock. update fetches another snapshot from the locked origin; linked development plugins edit the source directory instead. remove uninstalls an installed package and keeps config by default; --delete-data deletes the Host-managed snapshot and config, and reclaims unreferenced Runtimes. A linked development directory is not deleted. gc-runtimes deletes Host-managed Runtimes that no plugin references.

Unknown subcommands such as npx dimo plugin init raise Unknown plugin command. Init belongs to dimo-plugin.

npx dimo plugin publish

bash
npx dimo plugin publish [dir|file.vxp]
npx dimo plugin publish --web <github-owner/repo[#tag]>

Submit a packed package or a GitHub repository into the official marketplace review queue. Register a marketplace account first. The GitHub owner must match the marketplace username.

Credentials come from --owner / --password, or DIMO_MARKET_OWNER / DIMO_MARKET_PASSWORD. The default catalog is https://dimo-ai.com; override with DIMO_MARKETPLACE_URL. Packed uploads can pass --show-tree to show the package tree; GitHub listings show it by default.

After review, one owner/plugin-name card keeps version history. A listed GitHub repository adds a version when a new tag is pushed and keeps older versions. Hosts that installed from that card or repository show an update affordance.

npx dimo plugin test --host

bash
npx dimo plugin test --host
npx dimo plugin test --host ./my-plugin

Runs link, enable, chrome / structure contribution appear-and-withdraw, Skill reload, and uninstall against a running Host. Looks up a local Host token when DIMO_TOKEN is unset.

npx dimo plugin --help / npx dimo help plugin

bash
npx dimo plugin --help
npx dimo help plugin

Prints usage for pack / add / publish / list / update / remove / gc-runtimes / test --host / run and skips the Host.

Environment and troubleshooting

Variables read when starting the Host

These apply when running npx dimo or npx dimo serve.

DIMO_HOST_FAMILY_TAG: GitHub Release tag to download. Default is v plus the CLI version, for example v0.1.3. Pin a Host build so scripts keep a matching binary.

DIMO_HOST_FAMILY_BASE: URL prefix for the tarball. Default https://github.com/DimoADE/Dimo/releases/download/<tag>. An internal mirror places the full archive on its own HTTP directory and sets this.

DIMO_HOST_FAMILY_DIR: already extracted family directory (must contain SHA256SUMS, dimo-server, web/). When set, download is skipped.

DIMO_GITHUB_REPO: GitHub owner/name, default DimoADE/Dimo.

DIMO_STATIC_ROOT: Web UI static file root. npx dimo points it at packaged web/. When you start dimo-server yourself and need the browser UI, point this at a web/ tree.

DIMO_SERVER_ALLOW_LAN: set to 1 and even npx dimo (loopback start) listens on every NIC. npx dimo serve --local on the command line still binds loopback only.

DIMO_SERVER_LISTEN: a port number such as 18080, or ip:port. Overrides the default 17891. Command-line --port also overrides the default port.

DIMO_SERVER_TOKEN: Host token used at start. When non-empty, the saved token in the data directory is ignored.

DIMO_DEBUG: any non-empty value prints a JavaScript stack on CLI failure.

DIMO_DATA_DIR: Host data directory. npx dimo serve, npx dimo list, and npx dimo install share this SQLite. Unset, the machine default data directory is used.

Variables read by control commands

DIMO_URL: Host root URL, default http://127.0.0.1:17891. A trailing / is stripped. Change this after a port change or an HTTPS reverse proxy.

DIMO_TOKEN: Bearer token, required. Missing it raises DIMO_TOKEN is required. Copy it from the Token block of npx dimo serve, or from desktop Settings → Remote connection.

Control commands also accept --json, --operation-id, and --timeout. See Control-plane conventions.

Common failures

Unsupported platform: this OS/CPU pair is outside the six published combinations (linux/mac/windows × x64/arm64). Use a supported machine, or open GitHub Releases and confirm that platform’s archive.

Host family download failed: network, firewall, or a bad tag. Check DIMO_HOST_FAMILY_TAG and open the Release page for dimo-host-family-<platform>.tar.gz.

Checksum mismatch: a corrupt cache or a truncated download. Delete ~/.dimo/host-family/<tag>/ and retry, or point at a verified DIMO_HOST_FAMILY_DIR.

Host family is missing dimo-server: the extracted tree is incomplete. Download again; copy the full archive, not a subset of files.

DIMO_TOKEN is required: the token is unset. Run npx dimo serve and copy from the terminal, or copy from the desktop remote-connection page.

Timed out after Ns: the turn or workflow was still non-terminal. Raise --timeout, or inspect with npx dimo conversation show / npx dimo workflow show.

Missing required --x: a required flag is absent. Compare with npx dimo help conversation (or the matching resource).

Plugin validation failed: the plugin pack failed validation. Fix by the printed code, see Package layout, then run npx dimo plugin pack again.

Port in use: switch to npx dimo serve --port 18080, or stop the process holding 17891.

pass --yes to install without a prompt: npx dimo install ran without a terminal and without --yes. Use npx dimo install AGENT_ID --yes.

npm was not found / uv was not found: the local installer needs Node/npm or uv already on this machine. Install the toolchain, then run npx dimo install. Full write-up: Install Agents locally.

bash
npx dimo help
npx dimo --version