CLI
Use the dreamstate CLI to authenticate, select workspaces, and discover capabilities.
The Dreamstate CLI is the dreamstate binary from the @trydreamstate/cli package. Use it when terminal work needs the same workspace identity, pack routing, skill discovery, capability contracts, and run records available in Architect and the MCP server. It is a client of the shared contract, not a separate catalog of terminal-only actions.
The normal terminal flow is identity, discovery, contract read, then execution. This keeps a script or agent from constructing a request from a remembered identifier. For every available subcommand and flag, use CLI reference. For the protocol fields behind the capability controls, see MCP reference.
Sign in and choose a workspace
Install Node.js 22 or newer, then install @trydreamstate/cli and run dreamstate login. The CLI opens browser sign-in. For an SSH or remote machine, create a session in the app and run dreamstate login --token <token>.
Successful login installs every hosted Dreamstate skill for each detected Claude Code, Codex, and Cursor installation. Use dreamstate login --no-skills to skip that installation. If no supported agent is detected, or skill installation fails, login still succeeds and prints Run dreamstate skills install to install Dreamstate skills.
Tell me which workspace I am operating in, then route my request to the right pack before we make any changes.A workspace belongs to a particular actor and has its own scopes and spend policy. Selecting a workspace makes later terminal requests explicit rather than accidental. If the identity output does not match the intended workspace, stop before discovery. Logging out deletes the stored credentials file, which is useful on a shared or temporary machine after terminal work is complete.
Discover the work before running it
Packs route a goal to a domain such as tables, knowledge, workflow, or workspace. They are metadata, not authority. Start with packs list to see pack definitions, packs get for one exact pack, or packs route --goal for a plain-language outcome. A pack scope on tool search narrows discovery, but it does not make a result runnable without its contract.
Skills teach an agent or operator how to approach the work. The CLI lists skills with an optional query and numeric limit, reads a skill by identifier, searches skill text, installs selected skill files, and runs a doctor check for local installations. A skill may guide a workbook-building task, but the capability catalog remains the authority for the callable input, output, mode, cost policy, and effect policy.
Route a workbook-building goal, show the matching skill, then search the catalog for the actual capability contract.Tool search requires a goal, query terms, or JSON query fields. It can accept terms, a numeric limit, and a toolset pack. The response can include tool_turn_token and contracts already marked runnable. Preserve that token for the current turn. For a search result whose contract was not returned, call dreamstate tools get with the exact capability id before a run.
Run and inspect work
The CLI separates search, get, and run because a capability's exact schema is selected at runtime. tools get returns the contract to verify before creating a request. tools run takes either --params for a parameter object or --json for the complete request. The parser refuses attempts to supply both forms together.
A mutating execution must name a mode: smoke_test, dry_run, or live. The server owns the mode refusal, so the CLI lets a request through and the service can return its structured repair. The CLI validates conflicting mode flags locally. Its default run wait is 120 seconds, while --no-wait returns the immediate response and --wait-timeout selects a non-negative wait length.
Find the capability for a workbook named Trial accounts, inspect its exact contract, run a dry run, and show the run result.The command supports JSON output where the usage text says --json-output or --json. Use structured output in an automation that must carry a run identifier to a later command. Run commands list records, get one record, stream or page events, and cancel. A state version protects a cancellation from acting on a run that changed after it was read. Generic run resume is retired. A table run checkpoint uses dreamstate tools run tables.table_runs.resume.
Install skills and import a worksheet file
Login installs skills automatically for detected Claude Code, Codex, and Cursor agents. To install them later or for chosen agents, run dreamstate skills install --agents claude-code codex cursor --skill '*'. The onboarding skill installs as dreamstate-first-win, with skill id first-win.
The CLI also imports a local worksheet file with tables import. It requires a worksheet identifier and a file path. It accepts csv, json, jsonl, or xlsx as an explicit format, although an omitted format is derived from the file. Preview, upsert key, row kind, and keep-unmapped-columns are optional controls. This command is specific to importing a file, so use catalog search for other workbook actions.
Inspect the local skill installation for Codex and Cursor. Then show me the contract for importing trial accounts into a worksheet.Use the CLI reference before scripting specialized sequence or workflow verbs. Those command groups pass a verb, arguments, and flags through to their domain operation, so their exact accepted fields vary. The shared discovery flow still applies to ordinary catalog capabilities and remains the safest way to learn a current schema.
When it goes wrong
If sign-in or discovery fails, check the selected identity with dreamstate whoami. Machine keys are only for CI and clients without OAuth. Do not add a machine key to shell history, a prompt, or checked-in configuration. Use logout to remove stored CLI credentials when a machine should no longer retain them.
If search fails, provide --goal, --terms, or a JSON query containing a goal or query terms. If a run returns capability_not_fetched, search again in the current turn and get the missing contract before retrying. If it returns mode_required, add exactly one mode flag or mode field. If it returns quote_required, use the returned quote with unchanged parameters and a credit ceiling.
If the parser reports a usage error, read the usage shown by the command rather than adding guessed flags. Numeric skill limits must be non-negative integers. The importer rejects an unsupported format, and a tool run rejects both --params and --json together. For a stale cancellation, read the run again, take its current state version, then retry the cancellation.