CLI reference (nodrail)
nodrail is Nodrail's one command line. It has three parts:
- Project commands, offline:
nodrail add,nodrail policy lockandnodrail policy export --frozenmanage a repository's policy from catalog modules and your own files. See Playbooks. - Policy commands, offline:
nodrail policy init,validate,compile,eval,test,check,exec,hookandrunscheck and apply a rules file on your machine. - Cloud commands, with a personal token:
login,approvals,approve,reject,activity,runs,run,insightsandrules pullorrules pushwork with your Nodrail Cloud workspace.
The project and policy commands need no account and send nothing anywhere.
Install
Use Node.js 22 or later.
npm i -g @nodrail/cli
nodrail --help
With pnpm, run pnpm setup once so pnpm has a folder for global commands, then pnpm add --global @nodrail/cli.
nodrail --version prints the version. nodrail --help lists every command.
Project commands
Run these in the folder that holds nodrail.yaml, usually the root of your repository. Playbooks explains the project files, the lock and the review output.
| Command | What it does | Exit code |
|---|---|---|
add <@nodrail/module | ./file> | Adds a catalog module or a local file, and updates the lock | 0 done, 1 refused |
policy lock | Shows the permission changes since the last lock, records them | 0 done or up to date, 1 refused |
policy export --frozen | Prints the locked policy as one APF file | 0 printed, 1 anything differs from the lock |
plan (preview) | Shows what nodrail apply would set up for the team | 0 could apply, 1 something blocks it |
apply (preview) | Sets the team up on its host, after showing the plan | 0 done or nothing to do, 1 refused |
Usage mistakes exit with 2, such as policy export without --frozen.
add
nodrail add @nodrail/open-reviewed-pr
nodrail add @nodrail/open-reviewed-pr@1.0.0
nodrail add ./policies/team.yaml
add writes nodrail.yaml, creating it when it is missing, and nodrail.lock.yaml. It works offline: the catalog ships inside the package. A module is added once, under its own name, even if you add it again or by another name. Comments, entries and their order in nodrail.yaml are kept.
A module that needs values is added with them empty and is reported as configuration required. Give them under with: in nodrail.yaml, then run nodrail policy lock.
@nodrail/x@1.0.0 asks for that exact version. A version the catalog doesn't have is refused, and nothing changes.
A local import is a .yaml file inside the project, written as ./ or ../ and a path. A file outside the project, including through a link, is refused. So are an import cycle and a set of files that doesn't compile. When add refuses, both files stay as they were.
add changes the project's files only. It installs no hook and runs nothing.
policy lock
nodrail policy lock
lock compiles the project, prints who gains or loses which actions since the last lock, then the lines of the effective policy that changed, and records the result in nodrail.lock.yaml. When nothing changed it prints nodrail.lock.yaml is up to date. and writes nothing.
It refuses when a catalog module's files don't match the hashes in the lock at the same version, when a value isn't valid, such as a wildcard where a module needs one exact repository, or when the project doesn't compile.
policy export --frozen
nodrail policy export --frozen > effective.apf.yaml
export --frozen checks every file against the lock, offline, and prints one ordinary APF file on stdout. It refuses, printing nothing on stdout and the reason on stderr, when:
nodrail.yamlor a local file changed since it was locked, or a locked file is no longer imported;- a catalog module's files don't match the lock;
- a module still needs a value;
- the lock was made by a newer engine level than this
nodrailhas; - a change to the project was interrupted.
Each message says what to run next, usually nodrail policy lock.
A shell redirect empties the target file before nodrail runs. In CI, export to a temporary file and replace the deployed file only on success:
nodrail policy export --frozen > effective.apf.yaml.tmp && mv effective.apf.yaml.tmp effective.apf.yaml
plan (preview)
nodrail plan
nodrail plan --json
plan reads the team's resources and shows what nodrail apply would set up for the host runtime names. It only reads: it writes no file and installs nothing. For runtime: claude-code it plans:
| File | What it holds |
|---|---|
.claude/agents/<name>.md | Each team member: its description, model, skills to preload, and its instructions as the body |
.claude/skills/<skill>/ | Each member's skill folders, copied |
.nodrail/effective.apf.yaml | The locked policy, exactly what policy export --frozen prints |
.claude/settings.json | "agent" set to the team's entry agent, and a PreToolUse hook running nodrail policy hook on that policy with onFailure: "block". Other settings and hooks stay as they are. |
Each file is marked + to create, ~ to update, - to remove, = unchanged, or ! when apply would refuse. apply updates or removes only files it wrote, as recorded in .nodrail/setup-state.json, and only while they still hold what it wrote. A file already there that nodrail didn't write, one edited since, a path through a link, and an "agent" setting someone else chose are all !.
It also checks that the policy matches the lock, that claude 2.1.295 or later and nodrail are on PATH (the hook runs nodrail; with onFailure: "block", a missing one blocks every tool call), and that skills hold no links. plan exits with 1 when anything is marked !. Codex isn't set up yet.
apply (preview)
nodrail apply
nodrail apply --yes
apply shows the same plan, asks before changing anything, and makes exactly those changes. It refuses while anything is marked !, and changes nothing then. Without a terminal it needs --yes, which you give once you have read nodrail plan; --json needs --yes too.
It runs as the project's only writer, like add and lock: a second nodrail waits its turn and names the one at work. Inside, it plans again, and if anything differs from what you were shown, it stops without changing anything. Every change is staged first in a journal in your home folder, then made one file at a time, with .nodrail/setup-state.json last. If it stops partway, the next nodrail apply or nodrail policy lock finishes it. A file someone changes while it runs is left alone and named.
Run it again after changing a resource, a skill or a binding, and lock the policy first: it updates only the files that changed and removes the ones no longer needed, such as a member who left the team. With nothing to change it writes nothing.
With start: true in nodrail.yaml and a terminal, it then opens Claude Code. Otherwise run claude in the folder: the settings start it as the entry agent, behind the policy hook. A Claude Code session that is already open reads agent files and settings when it starts, so restart it to pick up the changes.
Policy commands
nodrail policy <command> is nodrail-policy <command>, the command line of the open-source engine: the same commands, flags, output and exit codes. It uses no token.
| Command | Reference |
|---|---|
policy init <pack> | Commands and exit codes |
policy validate, compile <rules> | Commands and exit codes |
policy eval <rules> | eval |
policy test <rules> --cases <file> | test |
policy check, exec <rules> -- <program> | check and exec |
policy hook <rules> | hook |
policy runs [list | show <run> | report] | runs |
nodrail policy init repo-work > rules.yaml
nodrail policy validate rules.yaml
nodrail policy eval rules.yaml --command "git status"
nodrail policy check rules.yaml -- git status
nodrail policy --help
nodrail-policy keeps working. Hooks and plugins that run it by name need no change, and both answer Claude Code byte for byte alike. Installing @nodrail/cli doesn't put nodrail-policy on your path: install @nodrail/policy-engine too if something on your machine calls it.
To use nodrail in the Claude Code hook, write nodrail policy hook where the quickstart writes nodrail-policy hook.
Cloud commands
These work with your Nodrail Cloud workspace and need a personal API token, which starts with ndp_. They are part of the Personal API (preview).
Never give a token that can decide or publish to an agent Nodrail governs. An agent holding a
decidetoken could approve its own requests; one holdingrules:writecould rewrite the rules that hold it back. Agents and assistants getreadtokens.
| Command | What it does |
|---|---|
login | Saves a personal token; --token-stdin to pipe it |
logout | Forgets the saved token |
whoami | The person, workspace, role and scopes behind the token |
approvals | Requests waiting for a person; --agent <key>, --watch |
approve <id> | Approves a request once, after showing it and asking |
reject <id> | Rejects a request, after showing it and asking |
activity | Events; --q, --agent, --outcome, --kind, --range, --run |
runs | Runs; --q, --agent, --outcome, --range |
run <id> | One run and its timeline |
insights | Approval and rule numbers; --days 7, 30 or 90 |
rules pull [file] | The rules file, to stdout without a file |
rules push <file> | Previews, shows the difference, asks and publishes |
nodrail login
nodrail approvals --watch
nodrail approve 6d1c2f0a-…
nodrail activity --outcome denied --range 24h
nodrail rules pull rules.yaml
<id> is the UUID that nodrail approvals lists, not the APR- reference. The token comes from NODRAIL_TOKEN when it is set, else from nodrail login. Tokens, scopes and what each command sends are described in the Personal API (preview).
Options
| Option | Meaning |
|---|---|
--json | Machine-readable output on stdout; notes and questions go to stderr |
-e, --environment | An environment's slug; the workspace's default otherwise |
--url, NODRAIL_URL | Nodrail's address, for self-hosting |
-y, --yes | Don't ask before deciding or publishing |
--limit, --cursor | Page size, from 1 to 100, and the next page's cursor |
Exit codes: 0 done, 1 failed, with the error's code and request ID, 2 the command line was wrong.