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

Minimal learning loop

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

npx workspai workspace model --json --write
npx workspai workspace context --for-agent --json --write
npx workspai workspace agent-sync --write --refresh-context --preset enterprise
npx workspai workspace verify --strict --json

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.

Change loop

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

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

Adopt existing projects:

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

Workspace Intelligence is not limited to native project generation. Existing projects in other languages and frameworks can enter through adopt/import. 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.

Command families

Release gate examples

npx workspai readiness --workspace ~/.workspai/workspaces/my-workspace --json --strict
npx workspai pipeline --json --strict --no-agent-sync

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 or workspace graph explain <project> --json when a structured JSON boundary is required. The media types are published on the workspace graph command page.

Rule of thumb

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