commands-reference.md

Commands Reference

Human-readable CLI syntax for the Workspai CLI. The machine-complete command, argument, option, alias, ownership, and integrity inventory is available through workspai commands --json and runtime-command-surface.v1.json. For behavior and workflows, see workspace-operations.md and OPEN_SOURCE_USER_SCENARIOS.md.

Start with the outcome-oriented root help when you do not yet know a command:

npx workspai --help
npx workspai <command> --help
npx workspai commands --json

Root help presents the canonical Understand → Impact → Act → Verify path, common human workflows, interactive official-kit discovery through create project, and a complete ownership-grouped command map. Scoped help carries exact flags and examples. commands --json remains the machine-complete inventory used to prevent the human map from drifting.

Start with the core loop

npx workspai adopt .
npx workspai workspace intelligence run --for-agent generic --strict --json
npx workspai goal "Describe the required outcome" --for-agent generic
npx workspai agent bootstrap --for-agent generic --strict --json

For source-changing work, continue through change begin, bounded authorization, effect receipts, independent verification, and capsule validation. For exact syntax, see the lifecycle section below.

Live cross-terminal activity

workspai live [target]
workspai live --global [--max-scopes <count>]
workspai live --run <run-id>
workspai live --once --json --projection monitor|board
workspai live --ascii|--accessible|--classic
workspai live --capture <file.svg> [--capture-preset github|linkedin|x|square|wide]
workspai live --replay <run-id> [--replay-speed <0.25..64>]

workspai live observes versioned activity emitted by CLI and Studio without changing command outcomes or upgrading telemetry into verification proof. The default TTY is an interactive Flow Board; the board JSON projection is the shared renderer-neutral surface for IDE, web, replay, and capture consumers. Use --accessible for stable screen-reader output and --classic for the compatibility view. See Workspai Live Activity.

Workspace lifecycle

npx workspai create # Guided create or existing-software ingestion
npx workspai create workspace <name> [--profile <profile>] [--yes] [--here|--output <parent-dir>] [--skip-python-engine] [--skip-git] [--dry-run] [--json] [--install-method <poetry|venv|pipx>]
npx workspai bootstrap [--profile <profile>] [--ci] [--json] [--compliance-only]
npx workspai setup <python|node|go|java|dotnet|rust|php> [--warm-deps]
npx workspai pipeline [--json] [--strict] [--skip-verify] [--skip-analyze] [--skip-autopilot] [--autopilot-mode <audit|safe-fix|enforce>] [--agent-sync|--no-agent-sync]
npx workspai analyze [--workspace <path>] [--json] [--strict] [--output <file>]
npx workspai readiness [--workspace <path>] [--json] [--strict] [--skip-verify]
npx workspai autopilot release [--mode <audit|safe-fix|enforce>] [--json] [--output <file>] [--since <ref>] [--parallel] [--max-workers <n>]
npx workspai goal <intent> [--workspace <path>] [--scope <workspace|project:name|projects:a,b>] [--runtime <runtime>] [--for-agent <generic|claude|codex>] [--max-attempts <1-25>] [--refresh] [--dry-run] [--json]
npx workspai goal <--status [goal-id]|--list|--activate <goal-id>|--cancel <goal-id>|--prepare <goal-id>|--verify <goal-id>> [--workspace <path>] [--no-run] [--json]
npx workspai change begin [--goal <goal-id>] [--workspace <path>] [--json]
npx workspai change list [--workspace <path>] [--json]
npx workspai change predict --change <change-id> --file <prediction.json> [--workspace <path>] [--json]
npx workspai change authorize --change <change-id> --effects <classes> [--granted-by <identity>] [--workspace <path>] [--json]
npx workspai change effect record --change <change-id> --file <effect-receipt.json> [--workspace <path>] [--json]
npx workspai change verify --change <change-id> [--strict] [--no-refresh] [--workspace <path>] [--json]
npx workspai change verification record --change <change-id> --file <verification-receipt.json> [--workspace <path>] [--json]
npx workspai change status --change <change-id> [--workspace <path>] [--json]
npx workspai change explain --change <change-id> [--workspace <path>] [--json]
npx workspai change resume --change <change-id> --to <authorized|executing|verifying> --reason <text> [--actor <identity>] [--json]
npx workspai change abort --change <change-id> --reason <text> [--actor <identity>] [--json]
npx workspai change capsule validate --change <change-id> [--workspace <path>] [--json]
npx workspai change capsule export --change <change-id> --output <path> [--workspace <path>] [--json]
npx workspai create project agent.microsoft.python <name> [--agent-name <name>] [--skip-git]
npx workspai create project agent.microsoft.dotnet <name> [--agent-name <name>] [--skip-git]
npx workspai create project gateway.openrouter.typescript <name> [--skip-git] [--json]
npx workspai create project gateway.openrouter.python <name> [--skip-git] [--json]
npx workspai agent bootstrap [--project <path>] [--for-agent <host>] [--no-live-inputs] [--strict] [--json]
npx workspai agent framework list [--json]
npx workspai agent framework plan --project <name> --runtime <python|dotnet|node> [--framework <id>] --name <agent> [--goal <goal-id>] [--workspace <path>] [--json]
npx workspai agent framework attach --project <name> --runtime <python|dotnet|node> [--framework <id>] --name <agent> [-y] [--granted-by <identity>] [--workspace <path>] [--json]
npx workspai agent framework apply --change <change-id> --project <name> --runtime <python|dotnet|node> [--framework <id>] [--workspace <path>] [--json]

Recommended CI:

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

Run the broader governance and release orchestrators as separate gates; they do not extend or redefine the canonical Workspace Intelligence chain:

npx workspai pipeline --json --strict
npx workspai autopilot release --mode enforce --json --output .workspai/reports/autopilot-release.json

bootstrap --ci --json --compliance-only runs deterministic compliance checks only (skips init). Default bootstrap --ci --json still runs init after compliance checks.

create workspace --skip-python-engine keeps Python-aware profiles such as python-only, polyglot, and enterprise available for Workspace Intelligence while skipping the immediate rapidkit-core install. Use it when you want model/context/verify/adopt/import governance first. To add the workspace-local Python engine later for RapidKit Core module-enabled kits, create or register the Workspai-owned project first and then run npx workspai workspace run init from the workspace root. Empty skipped workspaces and arbitrary adopted/imported Python projects keep the Python engine skipped; use npx workspai bootstrap --profile <profile> only when you need to change or realign the workspace profile.

npx workspai workspace sync [--json]
npx workspai workspace registry [--json]
npx workspai workspace policy show
npx workspai workspace policy set <key> <value>
npx workspai doctor
npx workspai doctor workspace [--json] [--strict] [--ci] [--fix] [--plan] [--apply]
npx workspai doctor project [--json] [--strict] [--ci] [--fix] [--plan] [--apply]
npx workspai project coverage [--project <path>] [--target <0-100>] [--run] [--strict] [--json]
npx workspai project agent-entry [verify] [--project <path>] [--for-agent <host|all>] [--no-live-inputs] [--strict] [--json]
npx workspai workspace list
npx workspai workspace foundation ensure [--force] [--json]
npx workspai workspace share [--output <file>] [--include-paths] [--no-doctor]
npx workspai workspace contract init [--force] [--json]
npx workspai workspace contract inspect [--json]
npx workspai workspace contract verify [--strict] [--json]
npx workspai workspace contract graph [--output <graph.json>] [--json]
npx workspai workspace intelligence run [--workspace <path>] [--for-agent <agent>] [--strict] [--json]
npx workspai workspace goal plan <release-readiness|dependency-security|test-coverage> [--scope <workspace|project:name|projects:a,b>] [--runtime <runtime>] [--target <0-100>] [--allow-breaking] [--allow-force] [--no-build] [--no-tests] [--json]
npx workspai workspace goal status <goal-id> [--json]
npx workspai workspace goal verify <goal-id> [--no-run] [--reuse-intelligence] [--json]
npx workspai workspace model [--workspace <path>] [--json] [--write] [--strict] [--cache] [--incremental] [--include-paths] [--include-evidence] [--scan-depth <count>]
npx workspai workspace context --for-agent [generic|codex|claude|gemini|qwen|kimi|grok|copilot|cursor|windsurf|amazon-q] [--workspace <path>] [--scope project:<name>] [--json] [--write] [--agent-sync|--no-agent-sync] [--target <targets>] [--preset minimal|enterprise] [--project-grounding managed|local|off] [--include-evidence] [--scan-depth <count>] [--strict]
npx workspai workspace agent-sync [--workspace <path>] [--write] [--refresh-context] [--strict] [--json] [--preset minimal|enterprise] [--target all|vscode|agents,copilot,cursor,claude,codex,gemini,qwen,kimi,grok,windsurf,amazon-q] [--project-grounding managed|local|off] [--experimental-hooks] [--hydrate-prompts]
npx workspai workspace remediation-plan [--json] [--write] [--ci] [--include-paths]
npx workspai workspace repair <capabilities|plan|propose|approve|decide|execute|resume|status|list|rollback|cancel> [--workspace <path>] [--card <id>] [--action-id <id>] [--project <name>] [--proposal <file>] [--transaction <id>] [--approved-by <actor>] [--decision <choice>] [--max-risk safe|guarded|invasive] [--allow-breaking] [--allow-force] [--no-auto-rollback] [--json]
npx workspai workspace snapshot [--workspace <path>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
npx workspai workspace diff --from <snapshot-or-model|git[:ref]> [--workspace <path>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>] [--strict]
npx workspai workspace impact --from <workspace-diff-report> [--workspace <path>] [--scope project:<name>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>] [--strict]
npx workspai workspace verify [--from-impact <file>] [--workspace <path>] [--scope project:<name>] [--strict] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
npx workspai workspace graph [emit|explain|search|benchmark|benchmark-suite|entities|evidence|path|overlay|dot|mermaid|jsonld|graphml|gexf] [key] [value] [--from <graph.json>] [--output <file>] [--limit <1..100>] [--kind <entity-kind>] [--workspace <path>] [--scope project:<name>] [--refresh-graph] [--graph-inventory-limit <count>] [--graph-semantic-budget <count>] [--graph-deep-budget <count>] [--graph-source-budget <count>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
npx workspai workspace eval [init <task> [strategy]|record|status|report|compare --from <report>] [--workspace <path>] [--output <file>] [--json]
npx workspai workspace watch [--workspace <path>] [--json] [--graph-stream] [--once] [--scan-depth <count>]
npx workspai workspace explain <target> [--workspace <path>] [--json] [--write]
npx workspai workspace why <target> [--workspace <path>] [--json] [--write]
npx workspai workspace trace --from <workspace-diff-report> [--workspace <path>] [--json] [--write]
printf '%s\n' '{"actionId":"fix-api","summary":"API tests passed","outcome":"ok"}' | npx workspai workspace feedback record [--workspace <path>] --json
npx workspai workspace mcp serve [--workspace <path>] [--json]
npx workspai workspace export --output team-workspace.workspai-archive.zip [--archive-compression store|deflate]
npx workspai workspace archive inspect team-workspace.workspai-archive.zip [--max-download-size <size>] [--max-expanded-size <size>] [--download-timeout-ms <ms>] [--allow-private-network] [--json]
npx workspai workspace archive verify team-workspace.workspai-archive.zip [--max-download-size <size>] [--max-expanded-size <size>] [--download-timeout-ms <ms>] [--allow-private-network] [--strict] [--json]
npx workspai workspace archive doctor team-workspace.workspai-archive.zip [--max-download-size <size>] [--max-expanded-size <size>] [--download-timeout-ms <ms>] [--allow-private-network] [--strict] [--json]
npx workspai workspace hydrate team-workspace.workspai-archive.zip --output ./team-workspace [--max-download-size <size>] [--max-expanded-size <size>] [--download-timeout-ms <ms>] [--allow-private-network]
npx workspai workspace import team-workspace.workspai-archive.zip --output ./team-workspace [--project-grounding managed|local|off] [--dry-run] [--strict] [--json]
npx workspai workspace connect [directory] [--project-grounding managed|local|off] [--dry-run] [--json]
npx workspai import <path|git-url> [--workspace <path>] [--name <project-name>] [--git] [--enable-modules] [--project-grounding managed|local|off] [--json]
npx workspai adopt [path] [--workspace <path>] [--name <project-name>] [--enable-modules] [--project-grounding managed|local|off] [--dry-run] [--json]
npx workspai snapshot create [name] [--include-projects] [--reason <text>] [--json]
npx workspai snapshot list [--json]
npx workspai snapshot inspect <name> [--json]
npx workspai snapshot restore <name> [--dry-run] [--force] [--json]
npx workspai project archive <name> [--reason <text>] [--dry-run] [--json]
npx workspai project archives [--json]
npx workspai project restore <archive> [--name <project-name>] [--force] [--dry-run] [--json]
npx workspai project delete <name> [--permanent --confirm <name>] [--dry-run] [--json]
npx workspai project workspace [status|relink] [--workspace <path>] [--project <path>] [--json]
npx workspai workspace init
npx workspai workspace run <init|test|build|start|custom-stage> [--workspace <path>] [--scope project:<name>] [--plan] [--runtime <runtime>] [--affected] [--blast-radius] [--since <ref>] [--parallel] [--max-workers <n>] [--continue-on-error] [--reuse-passed] [--strict] [--no-gates] [--json]
npx workspai infra plan [--workspace <path>] [--json] [--dry-run] [--verbose]
npx workspai infra up [--workspace <path>] [--no-plan] [--build]
npx workspai infra down [--workspace <path>] [--volumes]
npx workspai infra status [--workspace <path>] [--json] [--strict]

For adopt, an explicit --workspace must identify either an existing valid workspace or an existing empty directory that Workspai can bootstrap safely. Interactive adoption may also offer the direct parent when it contains exactly the project being adopted. Non-interactive callers continue to use the managed default when no workspace is specified.

Every workspace action has action-scoped help generated from the same contract that governs its accepted flags. For example:

npx workspai workspace impact --help
npx workspai workspace graph search --help

This avoids guessing whether an option such as --write, --from, or --output belongs to a particular action.

The contract graph includes its backward-compatible service projection, the canonical workspace-dependency-graph.v1 project topology, and the portable workspace-knowledge-graph.v1 evidence graph. The knowledge projection covers workspace/project structure, packages and dependencies, source files, modules, symbols, HTTP endpoints, OpenAPI/GraphQL/Protocol Buffers/AsyncAPI contracts, Compose/Kubernetes/Dockerfile/Terraform/Helm infrastructure, CI workflows, documentation, ADRs, tests, owners, environments, databases, and queues. Every entity and relation has stable identity and portable proof paths; proof taxonomy separates authored, extracted, and inferred facts and records trust, confidence, and freshness. Environment and secret values are never emitted.

workspace intelligence run writes .workspai/reports/workspace-intelligence-run-last-run.json. Its preflight contains exactly sync and baseline, while stages contains exactly the 11 ordered canonical chain steps. Exit 0 is passed, 1 is a hard execution failure, and 2 is a completed but evidence-blocked run. With --strict, warning-grade Analyze and Readiness verdicts can block the run without becoming execution failures. See Unified Workspace Intelligence Runner for baseline creation/reuse, JSON fields, artifact invariants, skip propagation, and CI handling.

workspace goal turns a user outcome into a durable success contract. Plan a release-readiness, dependency-security, or test-coverage goal once; Studio or another agent can then work toward it and ask the CLI to verify current evidence. Goal definitions live under .workspai/goals/, while the latest portable verdict is written to .workspai/reports/verified-goal-last-run.json. See Verified engineering goals for the supported scopes, safety constraints, and verification boundary.

Top-level goal <intent> is the plain-language planning front door. It binds the intent to the current canonical Model and Graph, resolves project/workspace scope, runs capability/retrieval preflight, and atomically writes a Goal Pack, portable agent handoff, and active-goal index. Use goal --status, --list, --activate, or --cancel for discovery/lifecycle; deterministic goals may use --prepare and --verify. It does not silently mutate source or let an agent claim verification. Lifecycle operations are mutually exclusive, cannot be combined with an intent or planning-only flags, and --no-run is valid only with --verify. See Goal Packs.

change turns an active Goal into a Proof-Carrying Change. list is the versioned discovery surface for open, blocked, sealed, aborted, and invalid capsules. begin pins the exact Model, Graph, and live-input generation. predict is explicitly noncanonical and never counts as proof. A human uses authorize to grant bounded effect classes; agents and tools then append typed, idempotent effect receipts. Removed paths use deletedArtifacts: [{ "artifact": "..." }]; the CLI emits a governed tombstone only after proving the path is absent and contained by the workspace or linked-project contract. verify re-observes the canonical Graph, derives the actual overlay, reports prediction surprises, and records Workspace Verify against the exact post-effect generation. Additional Goal-domain receipts enter through verification record. Only complete, passing criteria can seal a capsule. See Proof-Carrying Change.

Coverage Goals are runtime-bound. Interactive terminals select from the canonical Workspace Model when the chosen scope has multiple runtimes; non-interactive consumers receive needs-confirmation and rerun with --runtime <runtime> or a runtime named in the intent. From a multi-project workspace root, scope follows the same rule: interactive selection, or an explicit --scope for JSON/CI/agent runs. No second runtime detector is used. The emitted deterministic command uses workspace goal plan test-coverage --runtime <runtime> --target <percent>; the same runtime remains part of baseline and verification identity.

agent bootstrap is the project-local canonical-first preflight. It validates the host discovery route, project/workspace binding, public artifact schemas, integrity hashes, Model/Graph freshness, live source inputs, and active Goal handoff before broad repository discovery. It also proves that the local project graph is the exact current projection of the canonical workspace aggregate; a missing, stale, foreign, or tampered shard blocks architecture claims. project agent-entry verify uses the same receipt and can audit every supported host with --for-agent all. Blocked receipts exit 2; strict mode also maps degraded evidence to exit 2. See Canonical-first agent entry.

agent framework is the governed bridge between Workspai evidence and an agent runtime. list exposes every built-in adapter and its release-admission state. In this CLI version Microsoft Python 1.19.0 and .NET 1.22.0 remain preview. OpenAI Agents SDK Python 0.22.3 and TypeScript 0.18.0 are labeled stable. Google ADK Python 2.10.0 and TypeScript 2.1.0 remain labeled preview. All six current baselines are admitted by the complete Linux, macOS, and Windows evidence from Agent Framework Adapter Matrix run 88. Create and Attach require the reviewed v2 release inventory, whose manifest, framework baseline, runtime, and platform claims were promoted from the Linux, macOS, and Windows release matrix. Semantic implementation digests remain audit provenance rather than runtime authorization. plan creates or reuses a scoped Goal, begins a Proof-Carrying Change, and attaches a hash-bound file plan without writing project files. --runtime selects python, dotnet, or node. --framework selects the independent framework id when more than one admitted adapter shares that runtime. attach shows that plan and requires an interactive confirmation or explicit --yes before granting the filesystem effect and writing an isolated agents/<name> directory. When its selected baseline is admitted, create project agent.microsoft.python|dotnet uses the same governed lifecycle for a new project: it registers the project, plans against a Model baseline, writes the nested runtime, then re-observes Model/Graph before it claims Intelligence is sealed. The OpenAI and Google ADK Create kits use the same admission-governed lifecycle. Dependency installation, credentials, generated-code execution, and model provider calls are never implied by that approval. apply is the automation counterpart for a plan that was separately authorized with change authorize. Any adapter, version, manifest, runtime, or platform drift invalidates its bundled release admission until the complete conformance matrix passes again. The generated Change remains open until change verify.

workspace feedback record is a non-interactive machine interface. It requires exactly one JSON object on stdin and --json; an empty stdin or interactive TTY is rejected. Required fields are actionId, summary, and outcome. The accepted outcome values and optional scope/evidence fields are governed by contracts/workspace-intelligence/agent-action-outcome.v1.json. Successful records are appended to .workspai/reports/workspace-intelligence-history.json; no separate feedback artifact is created.

workspace graph emit --json returns both the compatibility project graph and the knowledge graph. Use workspace graph entities [kind], workspace graph evidence <id-or-unique-label>, and workspace graph path <from> <to> for indexed queries. workspace graph overlay --from <prior-graph.json> produces a portable change/PR overlay with additions, removals, changed fields, proof artifacts, proof additions/removals/content changes, bounded one-hop impact, and a risk summary. Observation timestamps and freshness alone do not create false change noise. Query indexes are cached per immutable graph object and invalidated automatically when a new graph is built. dot and mermaid intentionally remain project-topology renderers. workspace graph entities --kind <kind> --scope project:<name> --limit <n> is equivalent to the positional kind form and applies all three bounds before serializing JSON; count, totalMatches, and truncated make omissions explicit. Without --output they emit raw text for direct piping. With --output they write a durable file; adding --json returns a structured operation receipt with the format, node and edge counts, and resolved output path.

Every integrated workspace graph Knowledge Graph is derived from the canonical Workspace Model. Its contract fixes the source artifact to .workspai/reports/workspace-model.json and binds the graph to the model's stable structural SHA-256. Graph providers enrich that model-owned inventory; they never write facts back into the authorizing model during the same run.

workspace graph search <query> --limit <n> --json returns bounded entities, one-hop relations, related entity summaries, and portable proofs instead of the complete graph. New responses also expose graphSourceHash, allowing IDE and agent activity consumers to correlate returned entity/proof IDs only with the exact Graph revision that authored them. Ranking is deterministic and offline: it removes natural-language stopwords, weights rarer graph terms more strongly, and prefers exact labels and identities. Authored source ranks ahead of compiled, generated, vendored, fixture, and test-data matches unless the query explicitly names one of those surfaces. workspace graph benchmark <query> --limit <n> --json compares that retrieval payload with the readable proof-indexed corpus using a labelled characters / 4 estimate. It measures payload reduction only; it does not assert equivalent answer quality or model-specific billing savings.

workspace graph benchmark-suite agent-core.v1 --write --json runs five fixed, repository-neutral scenarios covering architecture, ownership, interfaces, change safety, and delivery. It reads the proof corpus once, reports median and p95 bounded retrieval sizes, and writes .workspai/reports/workspace-intelligence-benchmark-last-run.json. If a finalized workspace eval report exists, its usage and verified outcome are attached under a separate provenance classification. Pass --from <baseline-evaluation> only for a task-aligned comparison. A measured reduction is emitted only when both runs use measured token sources and have comparable verified outcomes. See Workspace Intelligence Benchmark.

Add --scope project:<name> to retrieve project-owned facts plus workspace-level shared entities proven to be connected to that project. The same scope constrains exact entity aliases used by graph evidence and graph path; a matching alias in another project cannot make a scoped target ambiguous. The search mode also accepts --kind <entity-kind> so agents can retrieve a precise semantic surface such as runtime-unit, endpoint, or owner. The agent projection reports explicit omission budgets for relations, related entities, proofs, aliases, attributes, and proof references. Read-oriented search, entities, evidence, path, benchmark, and benchmark-suite modes reuse the persisted graph only when its model binding, proofs, project scopes, and live Git/Merkle input fingerprint still match. --refresh-graph bypasses that compatible snapshot and rebuilds from current sources.

workspace graph jsonld|graphml|gexf exports the current derived, evidence-backed Knowledge Graph for semantic, graph-analysis, and interactive 2D/3D consumers. All five export modes accept --output <file>; Mermaid and DOT remain compact documentation-oriented project-topology renderings.

workspace eval records provider/tokenizer/estimate provenance, tool activity, cost, latency, and verified task outcome. eval record accepts a model-usage-event.v1 JSON document on stdin. The live and finalized artifacts are suitable for IDE dashboards and conform to workspace-intelligence-evaluation.v1.

workspace model --write also materializes the derived, contract-validated knowledge graph once at <workspace>/.workspai/reports/workspace-knowledge-graph.json. Every registered project receives a compact, integrity-bound .workspai/reports/project-knowledge-graph-reference.json that names the exact project projection and canonical workspace: URI. The unified intelligence runner publishes the aggregate and references as one atomic Model-stage revision, so CI, IDE adapters, agent grounding, and MCP cannot observe a partial set. Bounded graph search remains the default retrieval path. MCP exposes getWorkspaceKnowledgeGraph, searchWorkspaceGraph, queryWorkspaceEntities, getWorkspaceGraphEvidence, and findWorkspaceGraphPath.

Source extraction is bounded and language-neutral by contract. It recognizes the primary source formats for TypeScript/JavaScript, Python, Go, Java/Kotlin, .NET/F#, Rust, Ruby, PHP, Swift, Dart, Elixir, Scala, Clojure, Lua, R, C/C++, Vue, and Svelte. Package baselines also recognize npm/Deno, Python, Go, Cargo, Maven/Gradle, NuGet, Composer, Ruby, Elixir, Dart, SwiftPM, CMake, Bazel, and SBT. Regex-backed source facts are marked observed with medium confidence; authored manifests and interface/infrastructure specifications remain authoritative. This avoids presenting heuristic symbol discovery as compiler-grade truth while keeping the current CLI useful until deeper language providers move into the standalone graph package.

See workspace-run.md for fleet orchestration semantics.

After cloning or moving an existing workspace, workspace sync repairs its machine-local global registry entry before project discovery. For workspaces that only have legacy .rapidkit-workspace metadata, run workspace foundation ensure to add the canonical marker and foundation without deleting legacy compatibility inputs.

Workspace profile compatibility is enforced consistently across create project, import, adopt, and bootstrap compliance. In default warn policy mode, cross-runtime additions are allowed with a recommendation such as npx workspai bootstrap --profile polyglot; in strict mode, mismatches are blocked before the project is registered. Rust is an extended runtime with Axum/Tauri scaffolding and Cargo lifecycle support. PHP is extended through Laravel and Composer lifecycle support. Observed runtimes such as C and C++ are counted in the workspace runtime mix even when Workspai does not own a native scaffold for them. Existing CMake and Meson projects can also expose discovered lifecycle units to workspace run; inspect them without execution using workspace run <stage> --plan, and select one runtime family with --runtime <runtime>.

For npm, pnpm, and Cargo monorepos, the owning workspace manifest represents its matching members as one dependency-materialization boundary. Explicitly registered nested projects remain independent, while aggregate parents do not execute them a second time. Embedded eval, benchmark, integration, test-data, and fixture manifests are excluded unless they expose real lifecycle evidence.

Core module/template commands are intentionally narrower than runtime detection. RapidKit Core modules are guaranteed only for RapidKit Core module-enabled kits: fastapi.standard, fastapi.ddd, and nestjs.standard. They are not enabled for every project that happens to use a first-class framework. For example, an arbitrary existing FastAPI application can be adopted and modeled as a Python/FastAPI project, but module mutation remains disabled unless its RapidKit project metadata identifies one of those module-enabled kits. --enable-modules preserves module commands only when existing RapidKit metadata already identifies a module-enabled kit; it does not enable Core module mutation for an arbitrary detected framework.

Project lifecycle

npx workspai create project <kit> <name> [--yes] [--skip-install] [--skip-git] [--dry-run] [--output <dir>] [--create-workspace|--no-workspace]
npx workspai project commands [--json]
npx workspai commands --scope project [--json]
npx workspai init
npx workspai dev
npx workspai test
npx workspai build
npx workspai start

Examples:

npx workspai create project fastapi.standard my-api --yes
npx workspai create project nextjs my-web --yes
npx workspai create project rust.axum my-rust-api --yes
npx workspai create project desktop.tauri my-desktop-app --yes
npx workspai create project extension.vscode my-extension --yes
npx workspai create project php.laravel my-laravel-api --yes

Generator-specific options include --port, Spring Boot --java-version/--spring-version/--package-name/--group-id/--artifact-id, and .NET --dotnet-version/--target-framework/--nullable. Use npx workspai create project --help for the live option inventory.

create frontend <id> <name> is still accepted and routes to the same generators.

project commands shows the effective command contract for the current project. Core-backed FastAPI/NestJS projects can use module commands such as add and modules. Frontend, desktop, extension, Go, Spring Boot, .NET, Rust, PHP, and adopted/imported projects use runtime lifecycle commands and workspace governance while Core module mutation remains disabled.

Operations

npx workspai cache <status|clear|prune|repair>
npx workspai mirror <status|sync|verify|rotate>
npx workspai infra <plan|up|down|status>
npx workspai ai <info|recommend|generate-embeddings|update-embeddings>
npx workspai config <show|ai|set-api-key|remove-api-key>
npx workspai product <manifest|plan>
npx workspai shell

These groups are part of the public CLI surface, but availability of an operation can still depend on project runtime, optional provider configuration, or product metadata. Use the action's --help and workspai commands --json instead of inferring support from this compact synopsis.

See workspace-operations.md for infra discovery rules.

Profiles

• minimal — baseline workspace scaffolding
• java-only — Java-focused workspace
• python-only — Python-focused workspace
• node-only — Node.js-focused workspace
• go-only — Go-focused workspace
• dotnet-only — .NET-focused workspace
• polyglot — Python + Node.js + Go + Java + .NET
• enterprise — polyglot + governance-oriented checks

Policy modes

mode in .workspai/policies.yml:

• warn (default): report violations, continue
• strict: block incompatible operations

npx workspai workspace policy show
npx workspai workspace policy set mode strict
npx workspai workspace policy set dependency_sharing_mode shared-runtime-caches
npx workspai workspace policy set rules.enforce_toolchain_lock true

Supported keys: mode, dependency_sharing_mode, rules.enforce_workspace_marker, rules.enforce_toolchain_lock, rules.disallow_untrusted_tool_sources, rules.enforce_compatibility_matrix, rules.require_mirror_lock_for_offline.

Setup and warm dependencies

setup <runtime> validates an already installed host runtime and updates .workspai/toolchain.lock. It does not install system runtimes. When the executable is missing, the remediation plan emits an external prerequisite and blocks setup/bootstrap until fresh environment evidence is available.

--warm-deps adds optional dependency warm-up (Node lock/deps, Go modules). Warm-deps is non-fatal and reports completed / failed / skipped.

See also

• Documentation index
• workspace-operations.md
• workspace-run.md
• contracts/COMMAND_OWNERSHIP_MATRIX.md