@czap/cli

@czap/cli

The czap command-line tool: every verb emits one JSON receipt (a structured result line) on stdout and keeps human-readable summaries on stderr, so output pipes cleanly into jq, CI, or an AI agent.

Install this directly when you want the czap verbs in a project or CI. If you're starting a new project, start with liteship instead — it installs this package along with the rest of the stack.

Install

pnpm add -D @czap/cli

30 seconds

npx czap doctor

{"status":"ok","command":"doctor","verdict":"ready","checks":[
  {"id":"node.version","label":"Node.js","status":"ok","detail":"22.22.3"},
  {"id":"pnpm.version","label":"pnpm","status":"ok","detail":"10.32.1"}
]}

You should see one JSON line like the above on stdout (shown wrapped here) and, on a terminal, a colored per-check summary on stderr. Exit code is 0 for an ok receipt, 1 for failed; --ci escalates warnings to 1.

Verbs

Verb	What it does
czap doctor [--fix] [--ci] [--preflight] [--target cloudflare|astro]	Environment preflight: Node, pnpm, install, build artifacts, git hooks, or focused Cloudflare/Astro host probes. --fix applies cheap remediations.
czap help · czap version · czap glossary [term]	Help chart, version receipt, vocabulary lookup.
czap completion <bash|zsh|fish>	Tab-completion script — the one verb that writes a raw script, not JSON, to stdout.
czap describe [--format json|mcp]	Machine-readable description of every verb and schema.
czap mcp [--http :3838]	Start the MCP server (requires @czap/mcp-server installed).
czap astro dev|status|stop	Delegate to Astro 7 background dev-server management and emit a JSON receipt.
czap scene compile|dev|render|verify <path>	Compile, watch, render, or check a scene definition.
czap asset analyze|verify	Analyze (beats, onsets, waveform) or check an asset.
czap capsule list|inspect|verify	Work with capsules — self-describing component packages — from the manifest.
czap audit [--profile <p>] [--consumer] [--findings]	Run the @czap/audit structure/integrity/surface engine; receipt carries the counts (exit 1 on any error finding). --profile <p> audits a custom topology (.json/.js/.mjs/.ts, explicit path, no walk-up); --consumer audits the packages installed under node_modules instead of the repo source; combine them to audit a downstream's OWN topology — the profile becomes the discovery base. --findings adds per-finding detail to the receipt.
czap check [--ir]	Run the gauntlet gate fold in-process (litelaunchGauntlet) — structured findings + a blocking verdict, no subprocess. --ir selects the IR-enriched fold.
czap plumb	Plumb-completeness gate: fail on any tests/generated/ placeholder skip or any published package not classified runtime/tooling/deferred.
czap sbom	Emit the deterministic, content-addressed SBOM (lockfile policy + CycloneDX + completeness) as a reviewable working-tree artifact.
czap lsp [--ir]	Launch the gauntlet rigor language server over stdio (an editor spawns it) — gauntlet findings as live LSP diagnostics.
czap gauntlet · czap ship <pkg> · czap verify	Release gate, npm publish, post-publish verification.

Renders and analyses are cached by a hash of their inputs; pass --force to re-run. Unknown verbs exit 1 with a trailing {"error":"unknown_command"} line on stderr.

Where it sits

@czap/cli is a terminal adapter over @czap/command, the shared command catalog and dispatcher — the MCP server projects the same catalog, and neither imports the other (czap mcp only dynamically loads @czap/mcp-server). Scene and asset verbs execute through @czap/scene and @czap/assets, czap audit wires the @czap/audit engine, and shared types come from @czap/core. See the package surfaces map for the full layout.

If it does nothing

capsule verbs read a capsule manifest, by default reports/capsule-manifest.json under the current directory; outside a repo that has one they fail with a manifest-missing receipt. Set CZAP_CAPSULE_MANIFEST to point at yours.

Docs

• Getting started
• Architecture
• Glossary — the vocabulary used above
• API reference — generated from source

Part of LiteShip — powered by the CZAP engine (Content-Zoned Adaptive Projection), distributed as @czap/* packages.