Dreamstate CLI

Live terminal client for Dreamstate capability catalog. No pack list, capability list, or schema lives in package.

npm install -g @trydreamstate/cli

# Opens browser approval. No API key or prior CLI state needed.
dreamstate login

# Login installs every hosted Dreamstate skill plus router skill for detected Claude Code, Codex, and Cursor installations.
# Skip automatic installation when needed.
dreamstate login --no-skills

# SSH or remote box with no browser: paste the token minted by "Create session" in the web app.
dreamstate login --token <ds_live_...>

# Install the Dreamstate plugin (skills plus the hosted MCP server) into every
# Claude Code, Codex and Grok Build found on PATH. Safe to rerun; rerunning after
# a CLI upgrade updates the plugin. The agent asks you to sign in on first use.
npx @trydreamstate/cli install
dreamstate install --agents claude codex

# Install hosted skills for your agents (space-separated, comma-separated or repeated --agents).
dreamstate skills install --agents claude-code codex cursor --skill '*' --json

# Delete the stored credentials.
dreamstate logout

# Optional: point CLI at local or test API.
export DREAMSTATE_API_URL=http://localhost:3001/api/v1

dreamstate auth whoami
dreamstate whoami --json
dreamstate workspaces list
dreamstate workspaces use <id|slug>
dreamstate profiles list
dreamstate profiles use <profile_id>
dreamstate profiles current
dreamstate profiles remove <profile_id>
dreamstate profiles env <profile_id>
dreamstate packs list --workspace <id|slug>
dreamstate packs list
dreamstate packs get <pack_id>
dreamstate commands search "create a workbook and add rows"   # CLI commands first, then matching capabilities
dreamstate tools get <capability_id>
dreamstate tools search --goal "create a workbook" --limit 50 --toolset tables
dreamstate tools run tables.workbooks.create --params '{"name":"Pipeline"}' --mode live --approved

Credential profile grammar: dreamstate profiles <list|use|current|remove|env>.

dreamstate credits reads workspace credit status and overage settings through the canonical free workspace.usage.status_get capability and the same gate as tools run. --json returns one JSON envelope on stdout; version warnings go to stderr once per command.

login installs every hosted Dreamstate skill and router skill at user level for detected Claude Code, Codex, and Cursor installations. login --no-skills skips this step. If no supported agent is detected or installation fails, login still succeeds and prints Run dreamstate skills install to install Dreamstate skills. to stderr. With --json, login adds data.skills with either installed agents and file count or a skip reason. login --token <ds_user_...|ds_live_...> checks the token looks like a ds_user_ session or ds_live_ key, verifies it with whoami against the API, and only then stores it (mode 0600) and prints the same whoami output. The token is never echoed, and a rejected token is not stored. auth login keeps --api-key-file, stdin and DREAMSTATE_API_KEY. logout deletes ~/.dreamstate/credentials (or $DREAMSTATE_CONFIG_DIR/credentials), prints what it removed, and exits 0 even when already logged out. --agents accepts codex, claude-code and cursor, as --agents claude-code codex cursor, --agents claude-code,codex or repeated flags, for skills install and skills doctor. Node 22 or newer is required.

Credentials are stored as JSON {"token", "workspace"} (mode 0600); the single-line file written by 1.0.x is still read. A ds_user_ session belongs to you and works in every workspace you are a member of. Pick the workspace with --workspace <id|slug> (accepted by every command), then DREAMSTATE_WORKSPACE, then the stored default, in that order; the choice is sent as the X-Dreamstate-Workspace header. login stores the workspace you approved as the default. workspaces list shows your workspaces and marks the active one (--json returns the raw whoami envelope), and workspaces use <id|slug> verifies membership with whoami and stores the default. A ds_live_ machine key is bound to one workspace: workspaces use refuses it, so run dreamstate login for a user session that can switch. whoami prints the active workspace on stderr.

login prints approval URL plus confirmation code. Approval page shows same code, then CLI stores granted credential with mode 0600 and prints whoami. Default API is https://api.trydreamstate.com/api/v1; DREAMSTATE_API_URL overrides it. whoami and auth whoami are aliases. auth whoami prints API registry_hash unchanged. packs list, packs get, and commands search read authenticated API catalog at request time.

--json is output alias for --json-output when used without a value. tools run --json <body>, runs list --json <query>, and runs cancel --json <body> keep JSON input meaning. tools run --mode smoke_test|dry_run|live sends canonical execution mode; --dry-run aliases --mode dry_run. --max-live-sends <n> sends capability parameter params.max_live_sends; never top-level tools-run field. Consent text and limits come only from apps/backend/src/services/mcp/consentRule.json; generated plugin guidance reads that file. tools search --limit <n> and --toolset <pack_id> send canonical discovery query fields.

Stream contract and exit codes

Every invocation writes one JSON envelope to stdout. Pipe stdout to jq; progress, warnings, confirmation codes, and version-skew notices use stderr. Error envelopes have canonical ToolEnvelope shape: ok: false, error (code, message, and the server's retryable, repair, details unchanged) and meta. The server's own message is never reworded; guidance the CLI adds itself rides in error.details.cli_hint. meta keeps server fields (trace_id, server_version, minimum_cli_version, release_sha, registry_hash) plus request receipts (retry_after, idempotency_key). Process exit status stays outside JSON. Usage errors use the same envelope.

CLI_EXIT in src/errors.ts is sole exit-code table. dreamstate --help prints its stable meanings. Exit 7 means the error's repair.kind is ask_user (a person must decide). Exit 9 covers other refusals. request_timeout stays exit 11 and network_error stays exit 10 even though those local repairs use ask_user.

CLI-local error codes (raised by the CLI itself, never by the server): network_error, request_timeout, invalid_response, invalid_web_url, web_url_unavailable, plugin_install_failed, skills_authentication_required. Every other code in a CLI envelope is a server code.

Release skew and updates

The CLI sends X-Dreamstate-Client-Version on every request. The server stamps server_version, minimum_cli_version, release_sha and registry_hash on every response, in meta (whoami also puts registry_hash on data) and in X-Dreamstate-Server-Version / -Minimum-Cli-Version / -Release-Sha / -Registry-Hash headers; the CLI reads both, on success and on error. A changed registry_hash drops the cached capability postures. A server that refuses this CLI as too old answers HTTP 426 cli_update_required before running anything; the CLI exits 8 and prints npm install -g @trydreamstate/cli@latest. A CLI that is only behind the server still runs and prints a warning on stderr. dreamstate status reports cli_version, server_version (envelope meta only, never health.data.version), registry_hash, release_sha, minimum_cli_version and skew (compatible, cli_behind_server, cli_below_minimum, or unknown when the server publishes nothing), and exits 8 when below the minimum.

Idempotency

A live write gets a random key for one attempt. CLI persists that key by request digest in its config directory only while result is unknown or transient; retrying that pending request reuses it. Success or a definitive refusal clears it, so a later identical command gets a new key instead of replaying an old result. It is printed as meta.idempotency_key. After a timeout, read target back first; only if effect is absent repeat identical call once with first key. --idempotency-key <key> supplies a key explicitly and is used unchanged. A key longer than 255 characters is a usage error. Dry runs carry no key. runs cancel follows same attempt rule.

Sequences and workflows

sequences <verb> and workflows <verb> run through the same gate as tools run: same --dry-run/--live/--mode, --approved, --approval-id, --quote-hash, --max-credits, --max-live-sends, --approved-effect-unknown, --turn-token, --idempotency-key, turn cache, quote retry. --max-live-sends becomes params.max_live_sends only for capabilities that declare it, such as one-contact workflow execution. Sequence lifecycle and enrollment calls do not accept this flag or impose a lifetime send ceiling. Verb sends no mode unless given one; server answers mode_required with its repair classification. Flag values convert to capability live-input-schema types, so --max-new-enrollments-per-day 40 sends number 40. commands search <term> returns real CLI commands (and capability each runs) from CLI tables, plus matching catalog capabilities when signed in. tools run refuses capability contract does not publish for CLI (unsupported_capability, exit 9). CLI has no --agent-session-id: field selects in-app Architect surface; request body carrying agent_session_id rejected locally (exit 2).

Tables import

dreamstate tables import --table-id <uuid> --file <path> uploads the file: it opens an upload (tables.table_sources.csv_upload_create), chooses the column mapping, stages rows in chunks of at most 5,000, attaches the source and lands rows until done, the same lifecycle the web app runs. CSV, JSON, JSONL and XLSX are read locally; nothing is uploaded by --preview. Pick the identity column with --upsert-key <header> (otherwise the strongest mapped field: email, linkedin_url, external_id; domain for --row-kind company). Every step is replay-safe: re-running the same command resumes where it stopped. The import always runs to completion in the command's own process; there is no background mode. --background, which servers before 1.3.3 added to the command text they generate, is refused with a usage error (exit 2) that says to run the command without it.

runs resume was removed: the server has no generic run resume. A table run checkpoint resumes with dreamstate tools run tables.table_runs.resume.

Skills

skills install writes every hosted skill with its supporting pages (--copy copies the whole skill directory, not only SKILL.md), and skips an agent that already loads Dreamstate skills from the plugin. skills doctor compares each installed skill's content stamp with the live skill (text, revision and supporting pages), reports missing, extra and stale, and prints the command that refreshes them; age alone no longer decides.

Build and test:

npm run build --workspace=packages/cli
npm test --workspace=packages/cli
npm run pack:smoke --workspace=packages/cli