Command reference
Every command accepts the same global flags. Command-specific flags are noted in the table.
Global flags
| flag | effect |
|---|---|
--json | machine-readable output |
--no-color | disable ANSI color |
--cwd <path> | run as if invoked from <path> |
--store <id> | operate against a registered OpenSpec store instead of the local repo — see Stores |
-h, --help | show help for the command |
-V, --version (top-level only) | print the installed cospec version |
Commands
| command | synopsis | key flags | see |
|---|---|---|---|
cospec init [path] | Scaffold openspec/, the eleven typed schemas, and harness files. Idempotent. | --yes, --force, --harness <list>, --gate / --no-gate, --remove-opsx | Installation |
cospec update | Regenerate managed files (schemas, harness files) from canon. | --check (drift gate, exits nonzero on drift, changes nothing), --force | Installation |
cospec doctor | Read-only health check: wrapped-OpenSpec version, schema/harness drift, dangling slash/skill refs, config.yaml validity, changes stuck on an old schemaVersion, and — for a store-backed or references:-declaring root — delegated root/store relationship health (openspec-* findings). | — | How it relates to OpenSpec, Stores |
cospec new <type> <slug> | Create a typed change and print its artifact plan. Also accepts cospec new "<type>: <description>". | --description <text> | Types and artifacts |
cospec migrate <slug> | Opt-in: stamp a change created under an older schemaVersion to the current one, scaffolding a fully-deferred verification.md where the type requires it. Never runs automatically. | — | Verification |
cospec validate [name] | Validate one or all changes and specs against cospec's rules. | --strict (promote warnings to errors), --all, --changes, --specs, --fast, --no-interactive | Types and artifacts |
cospec status --change <slug> | Per-artifact completion, the blocker gate state, and archive-readiness for one change. | --change <slug> | Apply and archive |
cospec list | List active changes with type, gate state, task progress, and archive-readiness columns. --specs instead lists living specs by requirement count. | --blocked (only changes with a non-clear gate), --specs | Apply and archive |
cospec instructions <artifact> --change <slug> | Print the authoring instructions for one artifact of a change (e.g. proposal, verification, tasks). | --change <slug>, --allow-soft | Workflow |
cospec apply <slug> | The gate: check blockers and required artifacts before you implement. | --allow-soft (proceed past a soft block) | Apply and archive |
cospec archive <slug> | Validate, gate on tasks and verification, archive via OpenSpec, verify the move on disk, and fan out blocker sync. | --skip-specs, --force-incomplete | Apply and archive |
cospec sync-blockers | Check off blocking-changes entries whose target has shipped, across all active changes. | --check (report only, no writes), --change <slug> | Blocking changes |
cospec store <sub> | First-class wrap of the store lifecycle: setup/register/unregister/remove/list (ls)/doctor. setup/register auto-run cospec init --harness none on success. | --no-cospec-init (setup/register only) | Stores |
cospec context | Read-only cross-repo working-set brief across a repo and its references: stores. | --json, --code-workspace <path>, --force | Stores |
cospec workset create|list|remove|open | Personal, local working views. open hands the terminal over to the workset's editor/agent session and never accepts --json or --store. | — | Stores |
cospec show <item> | Show a single change or spec, text or JSON. | --type, --deltas-only, --requirements-only, -r/--requirement, --no-scenarios | Read-only and personal commands, OpenSpec's show |
cospec view | Summary dashboard for the operating root. Accepts neither --json nor --store. | — | Read-only and personal commands, OpenSpec's view |
cospec schemas | List every resolvable schema — the eleven cospec types plus any project-local (forked) schema — with its artifact chain. | — | Configuration |
cospec schema which|validate|fork|init | Inspect which schema a change resolves to, validate a schema's own structure, or create a project-local schema (fork <type> [name], init <name>). Refuses a destination name that collides with one of the eleven cospec types. | — | Configuration |
cospec templates | List resolved per-artifact template paths for a schema. | --schema <name> (default spec-driven) | Configuration |
cospec check-commit is a hidden commit-msg hook entrypoint (advisory only, never blocks a commit) and isn't part of the everyday command surface.
Exit codes apply and archive use the same four-code contract
(0/1/2/3) across every gated command. The full table lives on Apply and archive — read it once, not per command. :::
Read-only and personal commands
store, context, workset, show, view, schemas, schema which/ validate/fork/init, templates, and list --specs/validate --all/ --specs carry no cospec gate — none of them block a change lifecycle, require an artifact, or touch the verification ledger. Most of them (everything except store, which is a first-class wrap with its own filesystem-verified post-conditions) are disciplined passthroughs: cospec forwards the call to the wrapped OpenSpec binary under the same rigor as every gated command — a version-asserted spawn, a declared set of acceptable exit codes, a stdout deny-list, and stdout/stderr relayed verbatim — and, when you pass --json, guarantees exactly one JSON document on stdout (never a stack trace, even on failure) so a script or agent reading the output can always parse it. None of this changes what the commands do — show, view, schemas, schema, and templates in particular are genuinely OpenSpec's own job, and their full semantics live on OpenSpec's command reference — it only guarantees they fail predictably instead of silently.
For anything that's the wrapped binary's own job — the delta format, OpenSpec's glossary, or its own commands — see OpenSpec's command reference.