CLI Reference

The CLI is the first implementation surface for Workspace Intelligence.

Use the complete command catalog for one page per command, including its canonical invocation, architecture role, produced artifacts, and governing contracts. Use the contract catalog to follow those relationships back to their field-level schemas.

Install it:

npm install -g workspai

Or run it without a global install:

npx workspai --help

Canonical learning loop

npx workspai my-workspace --yes --profile polyglot
cd ~/.workspai/workspaces/my-workspace

npx workspai workspace intelligence run --for-agent generic --json

The command executes the complete versioned chain in contract order and writes .workspai/reports/workspace-intelligence-run-last-run.json. For an enterprise CI or release gate, enable strict verdict handling:

npx workspai workspace intelligence run --for-agent generic --strict --json

generic is the portable default. The versioned workspace-context contract also accepts codex, claude, cursor, and orca when the context should be labelled for a specific agent. Tool-specific files are generated separately by workspace agent-sync --target ..., whose contract includes VS Code, Copilot, Cursor, Claude, Codex, Orca, and portable agent surfaces.

In plain terms, a strict run succeeds only when its required evidence is ready. Automation can inspect the structured result when it needs the lower-level status and process semantics.

Workspace discovery baseline

The CLI treats workspace discovery as part of the Workspace Intelligence contract. A workspace is not just a folder; it is a named boundary that can be found consistently by the terminal, CI, IDEs, and agent surfaces.

For the default managed flow, Workspai creates workspaces under:

~/.workspai/workspaces/<workspace-name>

Commands such as workspace list, workspace sync, create, adopt, and import use that shared discovery layer so each consumer can resolve the same workspace without inventing a separate source of truth. An adopted or imported project also receives a machine-local workspace link and portable project lens, so workspace-aware commands can be launched from the project directory.

New workspaces also receive a concise creation receipt and a profile-aware README.md. The README's managed section is refreshed after project creation, adoption, import, connection, and workspace sync, while user-authored content outside that section is preserved. See Create and Adopt for the complete entry behavior.

Inspect change artifacts

The canonical runner is the normal decision path. The commands below are for inspecting a baseline and tracing its current artifacts; they are not an alternative chain and verify still requires coherent current evidence.

npx workspai workspace snapshot --json
npx workspai workspace diff --from git --json --write
npx workspai workspace impact --from .workspai/reports/workspace-model-diff-last-run.json --json
npx workspai workspace verify --strict --json
npx workspai workspace trace --from .workspai/reports/workspace-model-diff-last-run.json --json --write

Give an engineering request a measurable finish line

Use a Verified Engineering Goal when the request is larger than one command:

npx workspai workspace goal plan release-readiness --json
npx workspai workspace goal plan dependency-security --scope project:api --json
npx workspai workspace goal plan test-coverage --scope project:web --target 75 --json

Planning records the scope, baseline, safety constraints, required checks, and evidence paths under .workspai/goals/<goal-id>/. Verify the same goal after the work is complete:

npx workspai workspace goal status <goal-id> --json
npx workspai workspace goal verify <goal-id> --json

The latest governed verdict is written to .workspai/reports/verified-goal-last-run.json. This lets a user say “prepare this workspace for release” or “raise project coverage to 75%” without asking an agent to invent its own definition of done. See Verified Engineering Goals for the complete workflow and safety boundaries.

Diagnose and repair through the CLI-owned protocol

Doctor can return a bounded summary, force live evidence, or expose the versioned capability registry:

npx workspai doctor workspace --fresh --json=summary
npx workspai doctor capabilities --runtime rust --json

Governed mutations use durable repair transactions:

npx workspai workspace repair capabilities --json
npx workspai workspace repair plan --card doctor --project api --json
npx workspai workspace repair approve --transaction repair_123 --approved-by local-user --json
npx workspai workspace repair execute --transaction repair_123 --json

The plan hash, approval, checkpoint, stages, decisions, verification, rollback, and receipt remain inspectable. Models and IDEs may propose or authorize work; only the CLI closes the transaction.

Plan and run polyglot lifecycle stages

workspace run is the separate fleet-execution surface. Inspect its runtime units without running them, then execute only the required scope:

npx workspai workspace run build --plan --json
npx workspai workspace run test --runtime rust --scope project:native-api --json

The execution report is .workspai/reports/workspace-run-last.json. This surface produces lifecycle evidence consumed by verification; it does not add or rename a stage in the canonical Workspace Intelligence chain. See Polyglot Lifecycle Orchestration.

Create or adopt

Create a workspace:

npx workspai my-workspace --yes --profile polyglot

Create supported projects:

npx workspai create project nextjs web --yes
npx workspai create project fastapi.standard api --yes
npx workspai create project rust.axum service --yes
npx workspai create project desktop.tauri desktop --yes
npx workspai create project extension.vscode editor-tools --yes

Adopt existing projects:

cd /path/to/project
npx workspai adopt . --json
npx workspai import ../orders-api --workspace /path/to/workspace --json

Workspace Intelligence is not limited to native project generation. Existing projects in other languages and frameworks can enter through adopt/import. Outside an existing workspace, adopt creates or reuses the managed minimal workspace. It also writes a project-native context lens and a gitignored machine-local link, so users and agents can keep working from the project directory while resolving the governing workspace. The depth of runtime detection, doctor checks, lifecycle commands, and module support then follows the synced runtime contract; observed runtimes do not receive the same depth as first-class runtimes.

Workspace creation alone does not install the optional Python engine. Workspai requests that setup only for project or module flows that need it.

Official generator paths follow their latest stable release while respecting the runtime requirements published by the create-planner contract. A generator can be supported by Workspai but unavailable on a machine whose Node.js, PHP, Composer, Rust, or other required toolchain is missing or incompatible.

Command families

Release gate examples

npx workspai workspace intelligence run --for-agent generic --json --strict
npx workspai readiness --workspace ~/.workspai/workspaces/my-workspace --json --strict

The broader release pipeline is a separate gate and a separate invocation:

npx workspai pipeline --json --strict --no-agent-sync

workspace intelligence run is the canonical Workspace Intelligence chain. pipeline is the broader governance/release orchestrator; it is not an alias for the canonical chain and does not redefine its order.

Use --no-agent-sync when CI should evaluate evidence without rewriting agent grounding surfaces during the release gate.

Pipeline warnings are advisory by default. Add --strict when a warning-only report must return a non-zero process exit code; execution failures and failed stages remain blocking in every mode. See the contract-derived pipeline command page for the canonical exit semantics.

Machine interfaces and renderer output

workspace feedback record is a non-interactive machine interface. It requires one JSON object on stdin and validates that object against the agent action outcome contract before appending it to Workspace Intelligence history:

printf '%s\n' '{"actionId":"fix-api","summary":"API tests passed","outcome":"ok"}' \
  | npx workspai workspace feedback record --json

Follow the workspace feedback command page for its input schema and produced history artifact.

Graph renderer modes are intentionally distinct: workspace graph dot emits raw Graphviz text and workspace graph mermaid emits raw Mermaid text. Use workspace graph emit --json for the complete portable graph, workspace graph search <query> --limit <n> --json for bounded agent context, entities for a typed inventory, evidence and path for proof, overlay for revision-aware change analysis, and benchmark for transparent payload measurement. The media types and selectors are published on the workspace graph command page.

Use workspace eval init to create a versioned evaluation suite, workspace eval status to inspect recorded runs, workspace eval report to generate the governed result artifact, and workspace eval compare to compare two report revisions. Evaluation reports distinguish measured values from estimates and never turn payload reduction into an unsupported universal token-savings claim.

Use project coverage when a project needs a measurable test goal:

npx workspai project coverage --run --target 80 --strict --json

The result is stored as governed evidence rather than a UI-only percentage, so Doctor, IDEs, CI, and agent workflows can inspect the same measurement.

Rule of thumb

If a command changes or evaluates the software system, it should leave behind evidence that another consumer can inspect.