CLI reference

Nothing in the CLI changes a verdict. The only write is an operator's decision on an escalation.

Install and remove

npx @trustcoco/guardrails claude-code                    # install, observe mode
npx @trustcoco/guardrails claude-code --mode enforce
npx @trustcoco/guardrails uninstall
npx @trustcoco/guardrails uninstall --purge
npx @trustcoco/guardrails uninstall --purge --purge-ledger

Flag	Applies to	Effect
`--mode`	install	`observe`, `assist` or `enforce`. Default `observe`
`--on_error`	install	`block`, `ask` or `allow`. Default `block`
`--mandate`	install	Seed a different mandate
`--purge`	uninstall	Remove the gate and contracts under `~/.coco`
`--purge-ledger`	uninstall	Remove the ledger as well

Work the decisions

coco status                        # mandate, mode, contracts, hook, decision counts
coco report                        # what enforce would have stopped, grouped by rule
coco ledger                        # recent decisions
coco ledger --limit 200            # further back than the default 40
coco ledger --verdict BLOCK        # ALLOW, BLOCK or ESCALATE
coco ledger --json                 # every field, for anything downstream
coco escalations                   # the queue waiting on you
coco escalations --json
coco approve <id> --comment "..."  # record an operator decision
coco deny <id> --comment "..."
coco verify                        # walk the receipt chain

Contracts

coco compile                       # rebuild the compiled contracts from YAML
coco author --from policy.md --action approve_customer
coco author --describe "nobody force-pushes to main"

coco compile reads ~/.coco/packs if it is there and the repository's own packs/ otherwise. It refuses rather than warns, and the installer runs it before writing the hook.

Exit codes

Command	Non-zero when
`coco status`	Coco is not installed
`coco verify`	The chain is broken
`coco approve` `coco deny`	No such receipt, or it already carries a decision
`coco compile`	A contract does not compile

Those are the four worth wiring into a check. coco verify returning non-zero is the one to alert on.

Getting the command on your PATH

npx runs the package once and puts nothing on your PATH.

npm install -g @trustcoco/guardrails    # then: coco status
npx @trustcoco/guardrails status        # or go through npx every time

Both reach the same commands.

Environment

Variable	What it does
`COCO_HOME`	Where the gate, contracts and ledger live. Default `~/.coco`
`COCO_CLAUDE_DIR`	Where the settings file lives. Default `~/.claude`
`COCO_PYTHON`	Force a particular interpreter for the gate
`COCO_API_KEY`	The authoring key, and the gate's bearer token when served over HTTP
`DASHSCOPE_API_KEY`	An alternative authoring key

COCO_HOME is the useful one. Point it somewhere else and you can install a second configuration without touching the one you are running.

Testing a payload directly

echo '{"session_id":"t1","cwd":"/tmp","permission_mode":"default",
       "tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' \
  | python3 ~/.coco/gate/coco_gate.py

The gate reads a payload on stdin and answers on stdout. A BLOCK exits 2, an ESCALATE and an ALLOW both exit 0, and an ALLOW says nothing at all.

Tests and the bench

From a clone of the repository.

python3 -m pytest tests -q          # the test suite
bash tests/enforcement_probe.sh     # does a permission mode defeat the hook
python3 tests/bench_gate.py         # what one complete check costs on this machine

The gate runs on the standard library. The bench and the compiler need a YAML parser, so run those in an environment that has PyYAML installed.

CLI reference

On this page