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; `--tool` and `--source` take tool calls and code; JSON adds the engine plan and `exec/v2` 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 docs guards <name>`	Print one built-in guard's full description
`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\\|reset <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 nap <guard>...`	Pause only the named guards globally for 10 minutes; self-protection and other guards continue
`nah wake`	End the active nap immediately

Use nah hook --help for runtime names and nah docs runtimes before installation.

--fail-closed blocks explicit failures/refusals; --fail-open restores the default. Flagless reinstall preserves a recognized mode, and status reports it. In the TUI, f changes runtime mode and ? opens contextual help.

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. Guard names are those nah guards lists; a name shared by custom guards in several scopes is rejected as ambiguous. Starting a nap replaces the active one and restarts the timer. 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/v2 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 means failure before a valid decision exists, such as invalid outer tool-call JSON or a dispatcher failure. Shipped adapters return control through their documented runtime fallback and use fixed, non-secret feedback where supported.

Exit code 4 means an invalid CLI invocation for every command. 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/v2.