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:
npx dimo <resource> <action> --flag valueExample: 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:
npx dimo conversation --help
npx dimo conversation help
npx dimo conversation -hReplace 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.
npx dimo agent list --json
npx dimo conversation show --conversation CONV_ID --jsonnpx 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.
npx dimo conversation send \
--conversation CONV_ID \
--workspace WORKSPACE_ID \
--agent AGENT_ID \
--text "continue" \
--operation-id 11111111-1111-1111-1111-111111111111npx 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.
npx dimo conversation wait --conversation CONV_ID --timeout 120
npx dimo workflow wait --run RUN_ID --timeout 1800Call 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.