CLI reference
Review Dreamstate CLI commands and their documented syntax.
The dreamstate CLI is the terminal door to Dreamstate. Use it when an agent or an operator needs the same packs, skills, capability contracts, and runs available in Architect and MCP.
Start with discovery before a run: identify the workspace, search for a capability, read its contract, and then supply the required mode. For the shared controls, see MCP reference; this page covers the command syntax implemented by the CLI.
Session and workspace
dreamstate --help
dreamstate --version
npm install -g @trydreamstate/cli
dreamstate login
dreamstate login [--profile <name>] --token <ds_user_...|ds_live_...>
dreamstate login --no-skills
dreamstate logout
dreamstate install [--agents <claude codex grok>]
dreamstate status
dreamstate profiles <list|use|current|remove|env> [name]
dreamstate whoami
dreamstate credits
dreamstate auth login [--api-key-file <path>] [--no-skills]
dreamstate auth whoami
dreamstate workspaces list
dreamstate workspaces use <id|slug>Node.js 22 or newer is required. Run login for browser sign-in, or create a session in the app and pass its token to the same command on a remote or SSH machine. Successful login installs every hosted Dreamstate skill for each detected Claude Code, Codex, and Cursor installation. Use login --no-skills to skip skill installation. If no supported agent is detected or installation fails, login still succeeds and prints Run dreamstate skills install to install Dreamstate skills. logout deletes the stored credentials file. whoami shows the authenticated identity, and credits prints workspace usage and remaining credits, while workspaces list lists workspaces available to it and workspaces use selects one by identifier or slug. Use identity commands before discovery when a shell session could point at more than one workspace.
| Command | Arguments | Meaning |
|---|---|---|
login | Optional --token or --no-skills | Starts browser sign-in, accepts a session token, and installs skills unless skipped. |
logout | None | Clears the CLI session. |
whoami | None | Shows the authenticated identity. |
credits | None | Shows workspace usage and remaining credits. |
workspaces list | None | Lists workspaces available to the identity. |
workspaces use | ID or slug | Selects a workspace for later commands. |
status | None | Prints cli_version, server_version, release_sha, minimum_cli_version and skew. Exits 8 when this CLI is below the server minimum. |
install | Optional --agents claude, codex, grok | Installs the Dreamstate plugin (skills plus the hosted MCP server) for the named agents. |
profiles | list, use, current, remove, or env, plus an optional name | Lists, selects, prints, removes, or prints env for a local credential profile. |
auth login | Optional --api-key-file and --no-skills | Stores a key from a file. whoami and auth whoami both show the authenticated identity. |
Packs and skills
Packs help route a goal to an area of work. Skills give the agent operating guidance, and can be searched, inspected, installed, or checked from the CLI.
dreamstate packs list
dreamstate packs get <pack_id>
dreamstate packs route --goal <text>
dreamstate skills list [--query <query>] [--limit <n>]
dreamstate skills get <skill_id> [--file <path>]
dreamstate skills search <query> [--limit <n>]
dreamstate skills install [--skill <skill_id|*>] [--agents <codex claude-code cursor>] [--project] [--copy]
dreamstate skills doctor [--agents <codex claude-code cursor>] [--project]
dreamstate commands search <term>packs list and packs get read pack metadata. packs route --goal accepts a plain-language goal and returns the relevant domain route. A pack is not an authority grant. It guides discovery, while the selected capability contract still defines the accepted parameters, execution mode, cost policy, and effect policy. The --json-output flag is available on the pack commands shown in the CLI usage text.
skills list accepts an optional query and non-negative integer limit. skills get requires the skill id and can select a supporting file with --file. skills search treats the remaining positionals as the search phrase and also accepts a numeric limit. These reads help an agent learn the practice for a task, but they do not create a workspace object or make a capability executable.
skills install defaults its skill selection to * when --skill is absent. Its accepted agent values are codex, claude-code, and cursor. The parser accepts repeated, comma-separated, or space-separated agent values and refuses a value outside that list. --project and --copy change installation behavior. skills doctor checks the selected agent installation and accepts the same agent and project options.
Login installs hosted skills automatically for detected Claude Code, Codex, and Cursor agents. To install them later, run dreamstate skills install --agents claude-code codex cursor --skill '*'. The onboarding skill installs as dreamstate-first-win, with skill id first-win.
Tools and runs
Tool discovery returns candidates. tools get returns the exact input contract, which is the contract to check before composing a run. Runs are the durable record for work that continues or needs inspection.
dreamstate tools search --goal <goal> [--terms <csv>] [--limit <n>] [--toolset <pack_id>]
dreamstate tools get <capability_id>
dreamstate tools run <capability_id> [--params <object>|--json <body>] [--turn-token <token>] (--live | --dry-run | --mode <smoke_test|dry_run|live>) [--approved] [--approval-id <uuid>] [--approved-effect-unknown] [--max-credits <n>] [--max-live-sends <n>] [--quote-hash <sha256:...>] [--idempotency-key <key>] [--wait-timeout <seconds>] [--no-wait] [--open]
dreamstate runs list [--limit <n>] [--cursor <cursor>] [--json <query>]
dreamstate runs get <run_id>
dreamstate runs status <run_id>
dreamstate runs wait <run_id> [--wait-timeout <seconds>]
dreamstate runs events <run_id>
dreamstate runs cancel <run_id> [--state-version <n>] [--reason <text>] [--json <body>] [--idempotency-key <key>]The search parser requires --goal, --terms, or a JSON query containing a goal or query terms. --terms is parsed as comma-separated values, trims every value, removes duplicates, and rejects an empty resulting list. --limit is parsed as a non-negative integer before the request is sent. --toolset is forwarded as the discovery scope field, which narrows a search but does not change the installed CLI commands or the MCP roster.
tools get requires one capability identifier after the command. The CLI passes that identifier to the tool route, whose returned contract is the authoritative place to learn parameter names, output shape, available modes, and policy. A script should not derive a body from a suffix such as create or run, because the schema is resolved from the active catalog and workspace rather than from the CLI grammar.
tools run accepts exactly one parameter form. Use --params for the capability parameter object, or use --json for a complete request body. The parser rejects both flags together. If the JSON body already contains an execution-envelope field such as params, mode, agent_session_id, approved_effect_unknown, or max_credits, it is treated as the complete request. Otherwise, the object is placed under params.
The mode switches are mutually exclusive. --live, --dry-run, and --mode can select a mode, but more than one selected value produces a CLI usage error. --mode accepts only smoke_test, dry_run, or live. The server, rather than the parser, returns mode_required for a mutation with no mode so its structured repair stays identical across terminal, MCP, REST, and Architect calls.
Use --turn-token to send the token returned by discovery, --max-credits for a non-negative execution ceiling, and --idempotency-key for a replay-safe request. --approved is sent only with --live. --approval-id must be the uuid of a recorded approval. A bad value throws --approval-id must be the uuid of a recorded approval. --quote-hash must be the sha256: plus 64 hex quote a dry run returned. A bad value throws --quote-hash must be the sha256:<64 hex> quote_hash a dry run returned. --approved-effect-unknown forwards the literal approved_effect_unknown: true. tools run --max-live-sends <n> maps to params.max_live_sends (integer >= 1), never a top-level run field. A top-level max_live_sends throws max_live_sends is a capability parameter. Put it in params.max_live_sends or pass --max-live-sends. Use this flag only when the fetched capability schema declares it, such as a one-contact workflow run. Sequence lifecycle and enrollment calls do not accept it and have no lifetime send ceiling. A live external send above the paid-run row threshold needs --approved, a matching --quote-hash, and, when declared by that capability, params.max_live_sends at least the recipient count. The server error code is live_sends_require_approval. The CLI waits for a terminal run status by default for 120 seconds. --no-wait returns immediately, and --wait-timeout accepts a non-negative numeric override. On timeout, the CLI prints the latest run envelope rather than fabricating a terminal result.
Specialized commands
The CLI also exposes dedicated sequence, workflow, knowledge, unibox, and worksheet import commands. Their subcommands are passed through as verbs and flags; check their command help before using a write action.
dreamstate sequences <verb> [args] [flags]
dreamstate workflows <verb> [args] [flags]
dreamstate knowledge <verb> [args] [flags]
dreamstate unibox <verb> [args] [flags]
dreamstate tables import --table-id <uuid> --file <path> [--format <csv|json|jsonl|xlsx>] [--preview] [--upsert-key <header>] [--row-kind <person|company>] [--keep-unmapped-columns <true|false>]| Import flag | Required | Meaning | Default |
|---|---|---|---|
--table-id | Required | Worksheet identifier that receives the import. | None |
--file | Required | Path to the local import file. | None |
--format | Optional | One of csv, json, jsonl, or xlsx. | Inferred when omitted |
--preview | Optional | Previews the import. | Off |
--upsert-key | Optional | Header used to match existing rows. | None |
--row-kind | Optional | person or company. Anything else is a usage error. | None |
--keep-unmapped-columns | Optional | true or false. false is forwarded as keepUnmappedColumns false. | Omitted |
The sequences, workflows, knowledge, and unibox command groups take a domain verb followed by arguments and flags. The top-level help does not define a universal argument list for those verbs, so use each command's help and the discovered contract before using a write. This keeps a terminal script aligned with the domain operation instead of assuming the worksheet-import grammar applies to a sequence, a workflow, a knowledge verb, or a unibox verb.
knowledge verbs call customer knowledge capabilities. Graph verbs cover nodes (create, get, update, archive, restore, delete) and relations (create, get, update, archive, delete), plus edges-list, search, traverse, export, and contract-get. compose-document calls knowledge.brain.knowledge.compose_document. A positional id maps to node_id or relation_id. unibox verbs call customer inbox capabilities: list, get, messages, status, snooze, unsnooze, triage, drafts, draft-edit, draft-approve, labels, analytics, analyze, resync, sync-status, and comment threads. Both groups take the same run flags as tools run, require an authenticated session, and read remote fields from tools get for that capability.
The importer requires both --table-id and --file. Its table id is the worksheet receiving the data, and file is the local source path. --format is an override rather than a requirement: csv, json, jsonl, and xlsx are the only accepted values, while an omitted format is not forwarded and is derived from the local file. An unsupported format produces a CLI usage error before an import request is made.
--preview is a boolean import control, as is the global JSON-output option. --background was removed in 1.3.3: dreamstate tables import always runs to completion in this process. Run the same command without it. --upsert-key is a trimmed header name used to match existing rows. When it is empty after trimming, the CLI does not forward it. --row-kind accepts only person or company. --keep-unmapped-columns accepts only true or false. Importing a file is a specialized operation. Use the tables pack and tool search when you need a different workbook action, a current capability contract, or a clear execution mode.
Run commands are kept separate from capability commands because they operate on an existing durable run. runs list accepts --limit (integer 1 to 500), --cursor, and a JSON query object. runs get and runs events require a run id. runs resume was retired: the server has no generic run resume. A table run checkpoint resumes with: dreamstate tools run tables.table_runs.resume --params '{...}' --live. Start a new run for anything else. runs cancel accepts either a JSON body or the state-version and reason flags, never both. The state version is parsed as a non-negative integer.
A run cancellation may need its current state version even when the operator already has a run id. The CLI can read it from a run response when possible, but it refuses to invent zero if the run response does not contain a safe integer state version. In that situation, pass --state-version explicitly after reading the current run. The server can then detect whether another worker changed the run before the cancellation request arrived.