CDAL CLI Reference (`cdal`)

Note: This documentation is generated deterministically from CLI command definitions. All commands are packaged in pure ESM and execute with zero runtime dependencies in @cdal/core.

Quick Command Matrix

Command	Summary	Key Options
`cdal init`	Initialize CDAL in an existing or new project	`--preset`, `--runtime`, `-y,`
`cdal validate`	Validate contract invariants and integrity	`--strict`, `--json`, `--contracts`
`cdal codegen`	Generate deterministic TypeScript types and architecture diagrams	`--check`, `--out`
`cdal window`	Manage contract window for protected path mutations	`open`, `close`, `status`
`cdal trace`	Verify requirement-to-test traceability matrix	`--enforce`, `--markdown`, `--json`
`cdal phase`	Enforce CDAL loop phase gates from git diff	`--base`
`cdal selftest`	Execute mutation testing on quality gates themselves	`--kinds`, `--verbose`
`cdal sync`	Regenerate agent runtime configs from cdal.config.mjs	`--check`
`cdal verify`	Run full deterministic verification pipeline	`--fast`, `--clean`
`cdal hook`	PreToolUse entrypoint for agent runtime hook routing	`--runtime`, `--config`
`cdal audit`	Scan repository for AI hygiene and export offline HTML report	`--html`, `--json`, `--lang`
`cdal doctor`	Diagnose CDAL installation and environment health	—
[`cdal pro install`](#cdal-pro install)	Install CDAL Pro content into the project	`--from`, `--team`, `--force`, `--dryRun`, `--cwd`

`cdal init`

Initialize CDAL in an existing or new project

npx cdalkit init [options]

Scaffolds cdal.config.mjs, contracts directory, agent runtime adapters (.claude, .agents, AGENTS.md), and adds verification scripts to package.json.

Options

--preset <name>: Preset to include (typescript-strict, nextjs, node-service)
--runtime <name>: Agent runtime to configure (claude-code, agents-md, antigravity)
-y, --yes: Non-interactive mode with safe defaults

Example

npx cdalkit init --preset typescript-strict --yes

`cdal validate`

Validate contract invariants and integrity

npx cdalkit validate [options]

Executes static semantic invariant rules across all registered contract kinds (requirements, state-machine, policies, and custom kinds).

Options

--strict: Fail if any warnings are emitted
--json: Output findings in structured findings.v1 JSON schema
--contracts <dir>: Override default contracts directory

Example

npx cdalkit validate --strict

`cdal codegen`

Generate deterministic TypeScript types and architecture diagrams

npx cdalkit codegen [options]

Emits immutable TypeScript interfaces, constants, and mermaid markdown diagrams directly from contracts as single source of truth.

Options

--check: Drift detector: exits with code 1 if generated code is out of sync byte-for-byte
--out <dir>: Override target output directory

Example

npx cdalkit codegen --check

`cdal window`

Manage contract window for protected path mutations

npx cdalkit window <open|close|status> [ticket]

Enforces controlled mutation windows for contracts and generated files. Protected paths can only be edited when the contract window is open.

Options

open <ticket>: Open window referencing a specific work order or ticket
close: Close window and lock protected paths
status: Check current window state (open / closed)

Example

npx cdalkit window open WO-104
# edit contracts/*.contract.mjs
npx cdalkit window close

`cdal trace`

Verify requirement-to-test traceability matrix

npx cdalkit trace [options]

Scans test suites for // @REQ: markers and validates 100% coverage of active contract requirements.

Options

--enforce: Exits with code 1 if any requirement lacks automated test coverage
--markdown: Outputs markdown table suitable for PR descriptions
--json: Outputs trace coverage matrix as JSON

Example

npx cdalkit trace --enforce

`cdal phase`

Enforce CDAL loop phase gates from git diff

npx cdalkit phase <contract|red|green> [options]

Enforces phase boundaries across IDEs and CI: CONTRACT (only contracts modified), RED (only test files modified), GREEN (production code modified, zero test modifications).

Options

--base <ref>: Git reference or commit to diff against (default: origin/main or HEAD~1)

Example

npx cdalkit phase green --base origin/main

`cdal selftest`

Execute mutation testing on quality gates themselves

npx cdalkit selftest [options]

Tests whether validator invariants and guardrails actually fire red when violated. Proves gates are non-decorative.

Options

--kinds <list>: Filter specific kinds to probe
--verbose: Show detailed mutation failure logs

Example

npx cdalkit selftest

`cdal sync`

Regenerate agent runtime configs from cdal.config.mjs

npx cdalkit sync [options]

Keeps .claude/settings.json, .agents/, and AGENTS.md synchronized with role definitions in cdal.config.mjs.

Options

--check: Drift detector: exits with code 1 if runtime files are out of sync

Example

npx cdalkit sync --check

`cdal verify`

Run full deterministic verification pipeline

npx cdalkit verify [options]

Executes the complete verification suite defined in cdal.config.mjs (validate, codegen --check, typecheck, lint, test, trace, selftest).

Options

--fast: Run essential fast checks only
--clean: Clear build and test caches before verifying

Example

npx cdalkit verify

`cdal hook`

PreToolUse entrypoint for agent runtime hook routing

npx cdalkit hook <guard-paths|guard-forbidden|guard-bash|session-context|log-subagent> [role] [options]

Reads tool execution payload from stdin. Validates write scopes (denyTests), forbidden patterns, and bash commands. Exits with code 2 to block tool execution.

Options

--runtime <adapter>: Runtime format: claude-code, antigravity, or generic
--config <path>: Path to cdal.config.mjs

Example

echo '{"tool_name":"Edit","tool_input":{"file_path":"test.ts"}}' | npx cdalkit hook guard-paths implementer

`cdal audit`

Scan repository for AI hygiene and export offline HTML report

npx cdalkit audit [path] [options]

Runs 8 static checks (< 20s) evaluating agent configuration, type silencing density, skipped tests, role separation, traceability, and secrets. Pure local execution, zero network requests.

Options

--html <file>: Path to write standalone offline HTML report (default: cdal-audit-report.html)
--json: Output audit report in audit.v1 JSON schema
--lang <en|pl>: Report language (default: en)

Example

npx cdalkit audit --html ./report.html

`cdal doctor`

Diagnose CDAL installation and environment health

npx cdalkit doctor

Verifies Node.js version (>=20.9), git repository state, config validity, hook bindings, and detects configuration drift.

Example

npx cdalkit doctor

`cdal pro install`

Install CDAL Pro content into the project

npx cdalkit pro install [options]

Clones the private cdal-pro repository (access comes with a Pro license) and copies its agent roles, templates and presets into the project as listed in its pro.manifest.json. With --team it installs CDAL Pro Team (editor guards, Next.js presets, rollout playbook) from cdal-pro-team. Existing files are kept unless --force is passed; the installed version is recorded in .cdal/pro.json (.cdal/pro-team.json for Pro Team).

Options

--from <path|git url>: Local copy or git URL of the Pro repository (default: the private GitHub repository)
--team: Install CDAL Pro Team from the private cdal-pro-team repository
--force: Overwrite files that already exist in the project
--dryRun: Show what would be installed without writing anything
--cwd <dir>: Project directory to install into (default: current directory)

Example

npx cdalkit pro install --dryRun

← Quality Gates & Selftest

Agent Runtimes →