cli.md

title	CLI reference
sidebar_label	CLI commands

CLI reference

Invocation	Behavior
workstation, help, --help	Help without configuration loading
workstation --version	Package version
workstation init	Create starter without overwriting
workstation build	Resolve pins and reconcile
workstation upgrade [IDs...]	Refresh package pins and reconcile, including declared npm tools
workstation plan	Preview without Workstation persistence writes
workstation status	Inspect recorded pins and drift
workstation doctor	Check executables and explain backend limits
workstation history	List configuration-scoped snapshots
workstation rollback RUN	Preview supported restoration
workstation rollback RUN --apply	Apply supported restoration
workstation lock update [IDs...]	Refresh all or selected package pins
workstation update	Self-update native or global npm installation
workstation --list-tasks	List tasks and aliases
workstation TASK -- ARGS...	Run task with literal arguments

Put global options before task-style commands: for example, workstation --config /project/setup.ts rollback RUN --apply. After a task name, remaining arguments belong to the task. Build/plan accept --config, --machine, --verbose, and --frozen-lockfile. build --no-remove rejects remove actions, not ownership-only forget actions. Self-update rejects configuration/build options.

Status returns 1 for drift, errors, changed or untracked declarations. Doctor returns 1 for missing commands. Task exit status is preserved. Other failures return 1; successful commands return 0. Plans with proposed changes still succeed. JSON output is not yet implemented. Use --verbose for command traces and detailed inspections.

See architecture for implementation boundaries and environment tasks for Docker and sandbox integrations.

upgrade includes npm tools declared with tools.mise, such as "npm:@example/cli": "latest" or "npm:t3[allow_builds=node-pty]": "nightly". It resolves npm tags against the registry, updates their concrete lock versions, and installs the new versions through mise. A plain build retains existing pins. To upgrade just one npm tool:

workstation upgrade package:mise:npm:@example/cli

Only declared packages are managed; unrelated global npm installations and project package.json dependencies are outside this command's scope.

Option placement examples

workstation build --config /path/setup.ts --machine studio --no-remove
workstation plan --config /path/setup.ts --frozen-lockfile
workstation --config /path/setup.ts --machine studio status
workstation --config /path/setup.ts --verbose doctor
workstation --config /path/setup.ts lock update package:mise:node
workstation --config /path/setup.ts history
workstation --config /path/setup.ts rollback RUN --apply
workstation --config /path/setup.ts --list-tasks
workstation --config /path/setup.ts test -- --watch

Replace paths, task names, and RUN with your actual configuration values. build, plan, and upgrade parse global options alongside the command. The other command names use task-style parsing: flags after their name become command arguments and may be rejected. Put global flags before those names consistently. --config=PATH is not supported; use separate arguments.

Choosing a read-only command

Command	Resolves new versions?	Runs resource inspections?	Writes Workstation data?
--help, --version	No	No configuration loading	No
--list-tasks	No	No; loads configuration	No
doctor	No	Package command availability and state validation	No
status	No	Recorded declarations and live state	No
plan	If needed, unless frozen	Yes	No
history	No	Reads recovery identifiers	No
rollback RUN	May query exact mise availability	Restoration preconditions	No
lock update	Yes	Version queries	Lock only

Executable configuration can perform its own side effects during loading. Read-only provision checks must really be read-only, and native metadata queries may maintain their own caches. Planning does not install missing managers or repositories.

Output and failures

Builds show loading, version resolution, inspections, planned changes, and results. --verbose/-v includes command traces, per-resource inspection detail, query output, and exit timings. Mutations and CLI tasks stream output. Machine-readable JSON output is not implemented; use the embedded API for structured results.

--no-remove rejects actual removal actions during build/upgrade, but permits ownership-only forget actions. Although the parser accepts it for plan, it does not filter or reject that plan's output. It is not a general no-mutation switch. A failed build can have completed earlier actions; inspect the failure and rerun after fixing its cause. See recovery.