CLI guide
Learn and inspect
| Command | Purpose |
|---|---|
nah --help |
See the bounded command overview |
nah <command> --help |
See exact syntax for one command |
nah --version |
Print the installed CLI version |
nah docs [topic] |
List or read built-in documentation |
nah test [--json] <command> |
Evaluate without executing the command; JSON includes the exact exec/v1 custom-guard request |
nah guards |
List built-in and custom guards with their live status |
nah docs guards |
Render built-in behavior and examples, plus the live guard catalog |
nah log [--blocked] [--json] [-n count] |
List recent decisions or only recent blocks; JSON Lines use nah/audit/v1 |
nah why <id> |
Explain one redacted decision |
nah why is redaction-honest: it explains recorded effects and metadata, and
never reconstructs or reveals the raw command.
Configure
| Command | Purpose |
|---|---|
nah tui |
Configure guards, trusted projects, and runtime integrations, and browse recent decisions interactively |
nah guard enable\|disable <name> [--user\|--project root] |
Change a built-in or exact custom guard |
nah trust [root] |
Trust a project root; defaults to the current directory |
nah untrust [root] |
Revoke a trusted root and its enabled project guards |
nah hook <runtime> install\|uninstall |
Change one supported runtime integration |
nah hook <runtime> status |
Report not configured, wiring current, or reinstall required |
nah nap |
Pause self-protection globally for 10 minutes; guards continue |
nah nap --all |
Pause all non-permanent enforcement globally for 10 minutes |
nah wake |
End either nap immediately |
Use nah hook --help for runtime names and nah docs runtimes before
installation.
Starting or extending a nap requires a separate interactive operator terminal
and confirmation; intercepted agents cannot invoke it. Naps are user-global,
expire after 10 minutes, and do not roll back changes. nah wake ends one
sooner. Permanent nap-state protection remains active. See nah docs security
for the boundary.
Extend
| Command | Purpose |
|---|---|
nah guard new <name> [--project root] |
Create a user or project guard template |
Custom guards are unsandboxed programs. Even though nah test does not run the
tested command, matching active custom guards still execute. See nah docs
extending for the manifest, activation states, and exec/v1 contract.
Machine entry point
Runtime adapters call nah decide. It reads one JSON object from standard
input through EOF:
{"v":1,"tool":"Bash","input":{"command":"git status"},"cwd":"/repo"}
cwd must be the absolute call-site directory. Output contains the version,
verdict, reason, policy attributions, decision id, coverage, and duration. Its
schema is nah/decide/v1. Exit codes mirror the verdict: 1 block and 2
delegate. Integrations should use the JSON contract and exit code, not parse
human nah test output.
Observation or built-in evaluation failure produces delegate. A failed custom
guard contributes no finding, so another guard can still block. Live audit
recording is best effort; when a record persists, nah why shows its redacted
failure metadata. nah test --json includes a failures array.
Exit code 3 is reserved for failure before a valid decision can be produced, such as invalid outer tool-call JSON or an outer dispatcher failure. It has no valid decision body. Shipped adapters return control through their documented runtime fallback and use fixed, non-secret feedback where supported.
Exit code 4 means the CLI invocation itself was invalid. nah test is a human
dry run: it exits 0 after printing any completed verdict, including a block or
delegate, and its JSON schema is nah/test/v1.