CLI reference

Every command and subcommand

Each command and subcommand has its own page, generated from the engine's argument parsers at the pinned commit. An alias says which command it stands for.

chock exits 2 for a command it does not have, as its dispatcher says: src/chock/cli.py

Everyday

chock init

Scaffold a consumer repo (wiring only -- no policies)

usage: __main__.py [-h] [--agents [AGENTS ...]] [--agent-agnostic] [--skip-hooks] [--force] [repo]

Initialize a consumer repo with Chock

positional arguments:
  repo                  Target repo root

options:
  -h, --help            show this help message and exit
  --agents [AGENTS ...]
                        Agents to generate wrappers for (comma- or space-separated)
  --agent-agnostic      Generate wrappers for all supported agents
  --skip-hooks          Skip git hook installation
  --force               Overwrite scaffolded files that have local edits (destructive)

chock add

Install a policy or skill from a catalog and compile it

usage: chock add [-h] [--repo REPO] [--from SOURCE] [--ref REF] [--force] [--skip-compile]
                 [--verify-sha SHA256]
                 artifact_id

Install a policy or skill from a catalog and compile it

positional arguments:
  artifact_id          Policy or skill id, e.g. protect-main-branch

options:
  -h, --help           show this help message and exit
  --repo REPO          Target repo root
  --from SOURCE        Catalog URL or local path
  --ref REF            Full 40-hex commit SHA (recommended), or a branch/tag (mutable)
  --force              Replace an artifact that is already installed
  --skip-compile       Copy only; do not compile or install hooks
  --verify-sha SHA256  Refuse to install unless the fetched artifact hashes to this value

chock install

Build a chock.sh selection into one plugin for one agent (install --selection <file> [--client C])

usage: chock install [-h] --selection SELECTION
                     [--client {claude-code,copilot,codex,cursor,devin,goose,grok,antigravity,openhands,kimi-code,factory-droid}]
                     [--dest DEST] [--marketplace-name NAME] [--apply] [--allow-source SOURCE]
                     [--trust-local ID=SHA256]

Build a chock selection into one plugin for one agent

options:
  -h, --help            show this help message and exit
  --selection SELECTION
                        chock.selection.yaml, a URL with #s=..., or the bare code
  --client {claude-code,copilot,codex,cursor,devin,goose,grok,antigravity,openhands,kimi-code,factory-droid}
                        The agent to build for (default: the selection's client)
  --dest DEST           Install folder (default: the client's own, e.g.
                        ~/.chock/marketplace/<client>)
  --marketplace-name NAME
                        Name the build's local marketplace (default: chock-local), so a team's own
                        build can use its own
  --apply               Also run the client's own install commands, if any
  --allow-source SOURCE
                        Also trust this exact catalog source (the selection itself can never widen
                        trust)
  --trust-local ID=SHA256
                        Accept this local policy at exactly this hash without asking (for scripts,
                        after reading its code)

chock remove

Remove an installed policy and resync

usage: chock remove [-h] [--repo REPO] policy_id

Remove an installed policy and resync

positional arguments:
  policy_id    Policy identifier to remove

options:
  -h, --help   show this help message and exit
  --repo REPO  Repo root

chock sync

Recompile + rewire so the repo matches its policies (--ci/--skills for extras)

usage: chock sync [-h] [--repo REPO] [--agents [AGENTS ...]] [--skip-hooks] [--check] [--ci]
                  [--skills] [--committed]

options:
  -h, --help            show this help message and exit
  --repo REPO           Repo root
  --agents [AGENTS ...]
                        Comma- or space-separated target agents
  --skip-hooks          Skip reinstalling git hooks
  --check               Report drift and exit non-zero; write nothing
  --ci                  Also install the GitHub Actions CI gate workflow
  --skills              Also install bundled authoring skills
  --committed           Arm from what is committed (takes only --repo)

chock check

Run every truth check: validate, verify, evals, matrix (--only to narrow; --history scans past commits)

usage: chock check [-h] [--repo REPO] [--only ONLY] [--mode MODE] [--event EVENT] [--base BASE]
                   [--format {text,sarif}] [--output OUTPUT] [--head-ref HEAD_REF]

options:
  -h, --help            show this help message and exit
  --repo REPO           Repo root
  --only ONLY           Comma-separated subset of: validate, verify, evals, matrix, mechanisms,
                        index, conflicts, baseline
  --mode MODE           Validation mode (passed to validate, e.g. frontier-claude)
  --event EVENT         Hook event context (passed to validate, e.g. commit)
  --base BASE           Git ref the policy set may not be weaker than (baseline)
  --format {text,sarif}
                        sarif: run the compiled ci gates (needs --event ci and --base) and print
                        their findings as SARIF 2.1.0
  --output OUTPUT       With --format sarif: write the log to this file, not stdout
  --head-ref HEAD_REF   With --format sarif: the branch under test ($GITHUB_HEAD_REF)

With --history, scan past commits instead: chock check --history -h

chock status

Policy states and coverage (--only registry,log for more)

usage: chock status [-h] [--repo REPO] [--only ONLY] [--summary] [--verify-log]
                    [--head SEQ:SHA256] [--policy POLICY] [--since DAYS] [--json]
                    [--by {policy,rule,agent,event}] [--format {text,md}] [--route {sync,plugin}]
                    [--level {info,debug}] [--verdict {allow,block,ask,warn,off}]
                    [--plugin PLUGIN] [--follow]

options:
  -h, --help            show this help message and exit
  --repo REPO           Repo root
  --only ONLY           Comma-separated subset of: policies, registry, log
  --summary             Log summary: rates, latency vs timeout, faults
  --verify-log          Walk each decision log's hash chain; exit 1 at its first break
  --head SEQ:SHA256     With --verify-log: confirm a head kept earlier is still there

log section:
  --policy POLICY       Log: restrict to one policy id
  --since DAYS          Log: only records from the last N days
  --json                Log: machine-readable output
  --by {policy,rule,agent,event}
                        Log: group by policy, rule, agent or event
  --format {text,md}    Log: md prints a markdown summary
  --route {sync,plugin}
                        Log: only the sync route (this repo) or the plugin route
  --level {info,debug}  Log: info shows policy decisions only; debug adds allows
  --verdict {allow,block,ask,warn,off}
                        Log: only records with this verdict
  --plugin PLUGIN       Log: only records from this plugin (plugin route)
  --follow              Log: print new records as they are written

chock stop

Refuse every agent tool call, commit and push here until resume (--agent C for one client)

usage: chock stop [-h] [--repo REPO]
                  [--agent {antigravity,claude_code,codex_cli,cursor,devin,factory_droid,gemini_cli,goose,grok,mistral_vibe,openhands,tabnine,vscode_copilot,windsurf}]
                  [--reason REASON] [--everywhere]

Write `.chock/stop.json`: every tool call, commit and push by an agent in scope is refused until
resume.

options:
  -h, --help            show this help message and exit
  --repo REPO           Repo root (default: cwd)
  --agent {antigravity,claude_code,codex_cli,cursor,devin,factory_droid,gemini_cli,goose,grok,mistral_vibe,openhands,tabnine,vscode_copilot,windsurf}
                        Stop this one client only (default: every agent)
  --reason REASON       Why: the agent is told `stopped: <reason>`
  --everywhere          Stop every agent on this machine, in every repo

chock resume

Lift a stop: agents are judged by the policies again

usage: chock resume [-h] [--repo REPO] [--everywhere]

Remove `.chock/stop.json`: agents' tool calls, commits and pushes are judged by the policies
again.

options:
  -h, --help    show this help message and exit
  --repo REPO   Repo root (default: cwd)
  --everywhere  Lift the machine-wide stop only

chock doctor

Check each client's hooks on each route: present, current, and seen running (--client X)

usage: chock doctor [-h] [--repo REPO] [--client CLIENT] [--client-version CLIENT_VERSION]
                    [--sessions SESSIONS] [--json]

`chock doctor [--client X] [--repo .]`: each client's hooks on each route, PASS/WARN/FAIL with a
fix.

options:
  -h, --help            show this help message and exit
  --repo REPO           the repository whose `chock sync` hooks to check
  --client CLIENT       one client: an install client id (claude-code) or agent id (claude_code)
  --client-version CLIENT_VERSION
                        the client's version, compared with what agentseam witnessed
  --sessions SESSIONS   sessions the heartbeat check covers
  --json                one JSON object per target

chock incident

An ordered, redacted timeline from the local decision log (incident --since T [--until T] [--share])

usage: chock incident [-h] --since SINCE [--until UNTIL] [--format {text,md,json}] [--share]
                      [--repo REPO] [--route {sync,plugin}]

`chock incident`: an ordered, redacted timeline from the local decision log, as evidence. Never
sends anything.

options:
  -h, --help            show this help message and exit
  --since SINCE         Start, included: ISO date/time (UTC if no zone) or 24h, 90m, 3d ago
  --until UNTIL         End, not included (default: now)
  --format {text,md,json}
  --share               Leave out approver and who (a person's git email)
  --repo REPO           Repository root whose sync-route log is read (default: cwd)
  --route {sync,plugin}

chock witness

Export one client's redacted decision log for its agentseam evidence issue (witness export --client C)

usage: chock witness [-h] {export} ...

Evidence from your own decision log

positional arguments:
  {export}
    export    Write one client's redacted log records to a local file; never uploads

options:
  -h, --help  show this help message and exit

chock enable

Enable a policy by id

usage: chock enable [-h] [--repo REPO] policy_id

positional arguments:
  policy_id    Policy identifier to enable

options:
  -h, --help   show this help message and exit
  --repo REPO  Repo root

chock disable

Disable a policy by id

usage: chock disable [-h] [--repo REPO] policy_id

positional arguments:
  policy_id    Policy identifier to disable

options:
  -h, --help   show this help message and exit
  --repo REPO  Repo root

chock bundle

Switch a member of an installed plugin bundle on or off (bundle on|off <id>, bundle status)

usage: chock bundle [-h] {on,off,status} ...

Switch a member of an installed bundle.

positional arguments:
  {on,off,status}
    on             switch one policy on
    off            switch one policy off
    status         every installed bundle, each member's state and label

options:
  -h, --help       show this help message and exit

Authoring

chock new

Create a deterministic artifact skeleton

usage: __main__.py [-h] [--root ROOT] [--kind {content_regex,guard,script,rule,skill}]
                   {policy,skill,subagent} id

Create a deterministic artifact skeleton

positional arguments:
  {policy,skill,subagent}
                        Artifact type
  id                    Artifact id

options:
  -h, --help            show this help message and exit
  --root ROOT, --repo ROOT
                        Repo root
  --kind {content_regex,guard,script,rule,skill}
                        policy only: start from a tested template of this kind (outside a catalog
                        the id gains `my-`)

chock compile

Low-level single-policy compile

usage: __main__.py [-h] [--targets [TARGETS ...]] [--agents [AGENTS ...]] [--repo REPO]
                   [--policy-dir POLICY_DIR] [--output-root OUTPUT_ROOT]
                   policy_id

Compile a Chock policy into target-surface artifacts

positional arguments:
  policy_id             Policy directory name under .agents/policies/

options:
  -h, --help            show this help message and exit
  --targets [TARGETS ...]
                        Surfaces to emit (default: all)
  --agents [AGENTS ...]
                        Agents to include in coverage report (comma- or space-separated; default:
                        the repo's supported_agents, else all)
  --repo REPO           Repo root
  --policy-dir POLICY_DIR
                        Path to policy directory (default: <repo>/.agents/policies/<policy_id>)
  --output-root OUTPUT_ROOT
                        Compiled output root (default: <repo>/.chock/compiled)

chock install-skills

Install bundled authoring skills into agent skill dirs (write mode; check via CI)

usage: __main__.py [-h] [--skills [SKILLS ...]] [--check] [repo]

Install bundled authoring skills into .agents/skills

positional arguments:
  repo                  Target repo root

options:
  -h, --help            show this help message and exit
  --skills [SKILLS ...]
                        Specific skills to install (default: all authoring skills)
  --check               Report drift and exit non-zero; write nothing

chock registry

Scan/list/resolve the artifact registry

usage: __main__.py [-h] [--root ROOT] {init,scan,list,get,resolve} ...

Chock local JSON registry

positional arguments:
  {init,scan,list,get,resolve}
    init                Create an empty registry
    scan                Scan repo and rebuild registry
    list                List registered artifacts
    get                 Get registry metadata for an ID
    resolve             Resolve ID to manifest path

options:
  -h, --help            show this help message and exit
  --root ROOT, --repo ROOT
                        Repo root (default: cwd)

chock plugin

Package policies as installable plugins (plugin build [--format claude] [--check])

usage: chock plugin [-h] [--repo REPO] [--policies-dir POLICIES_DIR]
                    [--format {agent-plugins,claude,copilot,cursor,codex,devin,goose,grok,antigravity,openhands,kimi,droid,all}]
                    [--out-dir OUT_DIR] [--policy ID] [--out OUT] [--check]
                    {build}

Package policies as installable plugin directories

positional arguments:
  {build}               build: render each policy's plugin files

options:
  -h, --help            show this help message and exit
  --repo REPO           Repo root
  --policies-dir POLICIES_DIR
                        Directory of policy folders relative to --repo (default: discover
                        .agents/policies)
  --format {agent-plugins,claude,copilot,cursor,codex,devin,goose,grok,antigravity,openhands,kimi,droid,all}
                        Plugin format to emit (default: agent-plugins)
  --out-dir OUT_DIR     Distribution root: plugins are written to <out-dir>/<format>/<id>/
                        (required for every hook-carrying format)
  --policy ID           Package only this policy (manifest id or directory name); repeat for more
                        than one
  --out OUT             Write the selected policy's plugin directly to this path, instead of <out-
                        dir>/<format>/<id>/. Requires exactly one --policy.
  --check               Report policies whose packaged output is missing or stale, and exit non-
                        zero. Writes nothing.

chock marketplace

Emit marketplace index files over a built plugin tree (marketplace build --dist <dir>)

usage: chock marketplace [-h] [--dist DIST] [--name NAME] [--tree {claude,codex,cursor,devin}]
                         [--check] [--url URL]
                         {build}

Emit marketplace index files over a plugin tree built by `chock plugin build`

positional arguments:
  {build}               build: write the index files

options:
  -h, --help            show this help message and exit
  --dist DIST           Distribution root containing plugins/<id>/ directories
  --name NAME           Marketplace name clients address plugins with
  --tree {claude,codex,cursor,devin}
                        Which format tree to index; each vendor repo indexes only its own
                        (default: claude)
  --check               Report index files that are missing or stale, and exit non-zero. Writes
                        nothing.
  --url URL             Git URL of this marketplace's own repo. Required for --tree devin's root
                        meta-plugin; chock does not read `git remote` for this.

chock gateway

Run the MCP gateway proxy (gateway run --repo . -- <server command>)

usage: chock gateway [-h] {run} ...

Run the MCP gateway proxy: wraps ONE downstream MCP server and refuses tools/call requests that
match the repo's compiled gateway gates. Configure your MCP client to launch this command instead
of the server; put the real server command after `--`.

positional arguments:
  {run}
    run       serve stdio between the MCP client and the wrapped server

options:
  -h, --help  show this help message and exit

chock mcp

Serve the read-only chock_guidance MCP tool over stdio (mcp --repo .)

usage: chock mcp [-h] [--repo REPO]

Serve one read-only MCP tool, chock_guidance(plan, paths), over stdio: the installed rules a plan
touches, filtered to the repo's deny/ask selection. No network, no writes.

options:
  -h, --help   show this help message and exit
  --repo REPO  Repo root holding .agents/policies (default: .)

chock review

Produce or check reviewer evidence (review emit | review verify <file> | review require)

usage: chock review [-h] {emit,verify,require} ...

Produce and check reviewer evidence

positional arguments:
  {emit,verify,require}
    emit                Run the checks and write evidence
    verify              Re-derive every verified claim
    require             CI gate: is this PR merge-ready?

options:
  -h, --help            show this help message and exit

chock compliance

Generate a compliance coverage report (compliance report --framework owasp_asi)

Usage: chock compliance report [--repo .] [--framework owasp_asi] [--json]

Pre-launch aliases

chock validate

Alias of: check --only validate

usage: __main__.py [-h]
                   [--mode {agnostic,frontier-agentskills,frontier-claude,frontier-openai,frontier-devin,frontier-cursor,frontier-copilot,frontier-codex}]
                   [--json] [--include INCLUDE] [--exclude EXCLUDE] [--no-registry-check]
                   [--event {commit}]
                   [path]

Chock deterministic artifact validator

positional arguments:
  path                  Root path to validate

options:
  -h, --help            show this help message and exit
  --mode {agnostic,frontier-agentskills,frontier-claude,frontier-openai,frontier-devin,frontier-cursor,frontier-copilot,frontier-codex}
  --json                Emit JSON report
  --include INCLUDE     Limit to artifact type (repeatable)
  --exclude EXCLUDE     Skip artifact directories whose path contains this substring (repeatable)
  --no-registry-check   Disable registry freshness check
  --event {commit}      Context this run happens in. 'commit' scopes drift severity to the staged
                        diff.

chock verify

Alias of: check --only verify

usage: __main__.py verify [-h] [--root ROOT]

options:
  -h, --help            show this help message and exit
  --root ROOT, --repo ROOT
                        Repo root

chock eval

Alias of: check --only evals

usage: chock check --only evals [-h] [--repo REPO] [--mode {deterministic,agent}] [--json]
                                [--verbose]
                                [policy_id]

Run policy eval suites

positional arguments:
  policy_id             Policy to evaluate. Default: every policy in the repo.

options:
  -h, --help            show this help message and exit
  --repo REPO           Repository root (default: cwd)
  --mode {deterministic,agent}
  --json                Emit machine-readable results
  --verbose             Include skipped cases in the table

chock check-matrix

Alias of: check --only matrix

usage: chock check --only matrix

Verify that every spec invariant ID appears in spec/enforcement-matrix.md, and that no matrix
row is missing its Check column. Takes no options; reads spec/ from the current directory.

For work on Chock itself. Anywhere without spec/enforcement-matrix.md it exits non-zero.

chock recompile

Alias of: sync

usage: chock sync [-h] [--repo REPO] [--agents [AGENTS ...]] [--skip-hooks] [--check]

options:
  -h, --help            show this help message and exit
  --repo REPO           Repo root
  --agents [AGENTS ...]
                        Comma- or space-separated target agents (default: supported_agents from
                        config)
  --skip-hooks          Skip reinstalling git hooks
  --check               Report compiled artifacts that no longer match their manifests, and exit
                        non-zero. Writes nothing.

chock refresh

Alias of: sync / check --only index

usage: __main__.py [-h] [--repo REPO] [--check]

Regenerate .agents/policies/INDEX.md and the AGENTS.md pointer

options:
  -h, --help   show this help message and exit
  --repo REPO  Repo root
  --check      Exit non-zero if the on-disk files differ from generated; do not write

chock install-hooks

Alias of: sync (hooks part)

usage: __main__.py [-h] [repo_root]

Install Chock git hooks

positional arguments:
  repo_root   Repository root (default: current git top-level)

options:
  -h, --help  show this help message and exit

chock install-ci

Alias of: sync --ci

usage: __main__.py [-h] [--path PATH] [repo_root]

Install the Chock CI gate workflow

positional arguments:
  repo_root    Repository root (default: .)

options:
  -h, --help   show this help message and exit
  --path PATH  Workflow file to write, relative to repo_root

chock policies

Alias of: status

usage: chock status [-h] [--repo REPO]

options:
  -h, --help   show this help message and exit
  --repo REPO  Repo root

chock gate-log

Alias of: status --only log

usage: chock status --only log [-h] [--repo REPO] [--policy POLICY] [--since DAYS]
                               [--route {sync,plugin}] [--level {info,debug}]
                               [--verdict {allow,block,ask,warn,off}] [--plugin PLUGIN] [--follow]
                               [--json] [--by {policy,rule,agent,event}] [--format {text,md}]

Read the decision log, both routes

options:
  -h, --help            show this help message and exit
  --repo REPO           Repository root (default: cwd)
  --policy POLICY       Restrict the report to one policy id
  --since DAYS          Only records from the last N days
  --route {sync,plugin}
                        Only the sync route (this repo) or the plugin route (~/.chock)
  --level {info,debug}  info: only decisions a policy made; debug: allows too
  --verdict {allow,block,ask,warn,off}
                        Only records with this verdict
  --plugin PLUGIN       Only records from this plugin (plugin route)
  --follow              Print new records as they are written (Ctrl-C stops)
  --json                Emit machine-readable results
  --by {policy,rule,agent,event}
                        Group counts by policy, rule, agent or event
  --format {text,md}    md prints a paste-able markdown summary