nodrail

CLI reference (nodrail-policy)

nodrail policy <command> from @nodrail/cli is the same command, with the same flags, output and exit codes.

Use nodrail-policy to validate a file, inspect a decision, test expected outcomes or apply a policy before a command runs.

nodrail-policy <command> <rules file or folder>...

Files load in the order given. A folder loads its .yaml and .yml files by name. Use nodrail-policy --help and nodrail-policy --version.

CommandWhat it doesExit code
init <pack>Prints a starter file: read-only or repo-work0, or 2 for an unknown pack
validate <rules>Reports every problem by file and line0 valid, 1 invalid
compile <rules>Prints the compiled policy as JSON0, or 1 if invalid
eval <rules>Evaluates one call and prints the result0 whatever the outcome
test <rules> --cases <file>Checks expected outcomes0 all passed, 1 otherwise
check <rules> -- <program> [args]Answers whether this may run0 allowed, 1 otherwise
exec <rules> -- <program> [args]Runs it only if allowedThe program's own, 126 blocked, 127 not found
hook <rules>Claude Code PreToolUse hook, reading the event from stdin0 answered, 2 if rules can't load
runs [list | show <run> | report]What the run ledger recorded. Takes no rules0, 1 for a run that isn't there

Usage mistakes exit with 2.

eval

Give a command line, or describe the call:

nodrail-policy eval rules.yaml --command "git status"

nodrail-policy eval rules.yaml \
  --tool stripe --operation refunds.create \
  --kind invoice --resource INV-1 \
  --params '{"amount": 5000}'

--agent, --installation and --now set the caller and the clock for eval, check, exec and hook. test uses --now, and takes the caller from each case.

Level 3 preview. A matching gate needs run history. To test a gate or budget with recorded steps, see Testing gates (preview).

hook

--unmatched ask asks a person when no rule covers a call. The default blocks it. --agent and --installation set who the rules see.

When Claude Code or Codex says which agent made a call, its subagent's type or the session's claude --agent, the rules see that agent instead: the host sets it from the agent definition it started, and the model can't change it. --agent then names the entry agent, for calls the host doesn't label. So rules with agent: apply per subagent, and a rule on tool: claude-code, operation: agent decides which agents another may start.

The rule files and folders given to hook are protected: a file tool that would write, edit, patch or delete one of them, or a file inside one of the folders, is denied before the rules are read.

Level 3 preview. The run-aware Claude Code integration also records subagent starts and finishes. See Run history in Claude Code (preview).

runs

Preview command. runs needs version 0.2.0 or later. Check nodrail-policy --help for the commands in your installation.

runs (or runs list) lists the runs in the ledger, runs show <run> prints one step by step, and runs report counts steps, verdicts and held actions per agent. It needs no rules file. It reads the ledger of the repository you are in, or the folder NODRAIL_LEDGER names. Runs on a branch are named <repo>/<branch>, such as github.com/acme/app/feature/login: see Claude Code run history (preview).

check and exec

Arguments after -- are run directly with no shell, so ; and | in them are plain text. Anything other than an allow is blocked, including require_approval, because nobody is there to answer.

test

A cases file is a list of a name, a call and an expect of allow, deny, require_approval or none. A call is { command } or { tool, operation, kind, resource, params }, plus optional agent and installation. A hand-written call has only the params you give it: deny and review rules with conditions on a missing field still match, so give file calls path and path_parts as the hook would. See examples/cases.yaml.

Level 3 preview. Run-history test cases can also supply run and step. run is the history a case is decided in, and step is the agent taking the action: see Testing gates (preview).