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:
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.
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.
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:
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.
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.
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.
<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.
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.
-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:
Open the Host data directory (DIMO_DATA_DIR overrides it) and use the same SQLite as npx dimo serve.
A built-in Agent goes straight into the plan. A Registry Agent is added to membership first, then planned.
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.
Remaining components are written into the user environment: npm install -g --prefix …, uv tool install, or a Binary download into ~/.local/bin.
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 ….
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:
The Token block from npx dimo serve.
Access Token under desktop Settings → Remote connection, for the same Host.
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.
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.
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.
--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.
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.
--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.
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.
--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.
--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.
--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.
--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.
--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.
--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.
--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.
--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.
--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.
--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.
--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.
--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.
--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.
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:
--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.
--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.
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.
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_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.
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.