Failproof AI CLI

Install the local CLI with npm install -g failproofai. Run it with no arguments to open the local policy dashboard. The package requires Node.js 20.9 or newer. Bun 1.3 or newer is supported for development and source installs. failproofai configure and failproofai setup are aliases for failproofai config. failproofai policy, failproofai pack and failproofai p are all spellings of failproofai policies — packs and single policies were three commands for one idea and are now one. The older spellings still work, with two exceptions: pack list <source> is now policies show <source>, and pack build is now publish.

Set up a machine

Install the CLI, then read the machine key into the shell. read -s takes it at a prompt that does not echo, so it never appears in a command:

npm install -g failproofai
read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN

Then set the machine up and choose what it enforces:

failproofai config
failproofai policies add FailproofAI/policies
failproofai config --status

failproofai config is the whole of setup: it installs the failproofaid service (root once, via sudo -n — never an interactive password prompt), wires hooks into every agent CLI it finds, and connects to Cloud when a key is available. With no terminal — CI, a container, an agent driving it — it applies rather than asking, and exits 1 if anything it was asked to do did not happen. It chooses no policies. That is the second command’s job, and without it a freshly configured machine enforces nothing but the always-on guard. Prefer the environment variable over --token: a command-line argument is readable from ps by every user on the box. That is all the variable protects against — a key typed into any command, export included, still lands in shell history, which is why it is read in with read -s above. In CI, set it from the secret store and keep shell tracing (set -x) off, or the trace prints it.

--connect <url> enrols a machine that is already set up. It returns as soon as enrolment succeeds — it does not install the daemon and does not wire any hooks. Use plain failproofai config (or failproofai config --token <key>) on a machine that has not been set up yet, or it will read as connected while collecting and enforcing nothing.

Run failproofai without arguments to open the local policy dashboard.

Command	Outcome
`failproofai config`	Set the machine up: agents, daemon, and Cloud when a key is present
`failproofai config --token <key>`	Set up and connect in one pass, asking nothing. A key that carries `jev:evaluate` also turns on Jev through FailproofAI Cloud in observe mode, unless a `jev.json` already exists or `--no-transcripts` is given
`failproofai config --connect <url>`	Enrol a machine that is already set up — no daemon, no hooks
`failproofai config --status`	Show connection, daemon, delivery, and pause state
`failproofai policies`	List builtin, custom, convention, pack, and Cloud-managed policies
`failproofai policies --install`	Wire hooks into your agent CLIs. Enables no policy on its own
`failproofai policies add <name>`	Enable one policy — a builtin, or `<pack-id>:<name>` from an installed pack
`failproofai policies remove <name>`	Disable one policy, same naming
`failproofai policies --uninstall`	Disable policies or remove harness hooks
`failproofai policies show <owner>/<repo>`	What a pack carries, read from its manifest, before you take it
`failproofai policies show <owner>/<repo> --releases`	Every version it has published, and which one is here
`failproofai policies add <source>`	Install a policy pack from a GitHub release; no tag takes the newest and pins it
`failproofai publish`	Ship your own policies as a pack; `--init` writes one to start from, and `--min-cli-version <version>` sets the oldest CLI that may install it (Jev checks in a pack)
`failproofai policies remove <publisher/name>`	Uninstall a pack
`failproofai audit`	Scan local agent history and open the local audit view
`failproofai audit --schedule [days] --email <address>`	Schedule recurring local scans and email their findings
`failproofai audit --status`	Show the report address, interval, and next scheduled scan
`failproofai audit --no-schedule`	Stop recurring scans without deleting audit history
`failproofai harness list`	List extra capture paths
`failproofai jev --url <url> --key-stdin`	Set Jev up in one step; the provider is taken from the URL’s host
`failproofai jev setup --provider <kind> --key-stdin`	Let Jev judge tool calls through your own endpoint and key
`failproofai jev setup --provider failproofai`	Let Jev judge tool calls through FailproofAI Cloud, with this machine’s Cloud key
`failproofai jev setup --mode <m>`	Switch Jev’s mode: `enforce`, `observe`, or `off` (keeps the config, stops asking Jev)
`failproofai jev status`	Show the Jev config, its permissions and recent fallbacks; never the key
`failproofai jev test`	Send one live Jev request and show its latency and version; exits 1 when the answer is late for hooks or wrong
`failproofai jev models`	List the model ids `GET <base>/models` says an endpoint serves
`failproofai jev remove`	Turn Jev off; hooks run the regex policies exactly as before
`failproofai flush --wait`	Deliver the current event spool
`failproofai backfill --since 30d`	Re-read previously passed history
`failproofai config --pause [duration]`	Pause one local session for 30 minutes by default, up to 8 hours
`failproofai config --resume`	Resume one paused local session; add `--all` to clear all pauses
`failproofai update`	Finish package migrations and update the daemon
`failproofai migrate --dry-run`	Preview or run pending home-layout migrations
`failproofai uninstall`	Remove hooks and the daemon before removing the package
`failproofai --version`	Print the installed package version
`failproofai --help`	Show commands and global usage

Configuration flags

Flag	Use
`--token <key>`	Set up and connect non-interactively; also read from `FAILPROOFAI_CLOUD_TOKEN`
`--url <url>`	Connect somewhere other than `app.befailproof.ai`; also read from `FAILPROOFAI_CLOUD_URL`
`--connect <url>`	Enrol only, on a machine already set up. Skips the daemon and every hook
`--machine-id <id>`	Set the stable machine ID
`--machine-label <name>`	Rename a machine that is already connected. On its own it never runs setup, so give it after `failproofai config`, not during
`--no-transcripts`	Send decisions without transcript content, and do not turn on Cloud Jev, which would send each checked tool call and the recent prompt
`--disconnect`	Stop Cloud policy pulls and event delivery. Also removes the Cloud Jev key and a `jev.json` that names FailproofAI Cloud; your own Jev setup is left in place
`--status`	Show current machine state
`--pause [duration]`	Pause the newest session in the current directory; accepts seconds, minutes, or hours and defaults to 30 minutes
`--resume`	End a matching pause early
`--session <id>`	Target an explicit session for pause or resume
`--all`	With `--resume`, end every active pause

Local pauses suspend builtin, custom, convention, and pack policies for one session. They always expire and do not disable Cloud-managed policies. block-failproofai-commands — which is always on and cannot itself be disabled or paused — prevents an instrumented agent from using this escape hatch itself.

Policy flags

Flag	Use
`--install`, `-i`	Install harness hooks. Names after it enable those policies; with none, no policy changes
`--uninstall`, `-u`	Disable policies or remove hooks
`--cli <names...>`	Target one or more supported harnesses
`--scope user\|project\|local\|all`	Choose the configuration scope; `all` is for uninstall
`--beta`	Include beta policies
`--custom`, `-c <path>`	Validate and load a custom policy file; repeatable

Delivery and maintenance flags

Command	Flags
`backfill`	`--since <30d\|6m\|YYYY-MM-DD>`, `--dry-run`
`flush`	`--wait`, `--timeout <seconds>`
`update`	`--no-daemon`
`migrate`	`--dry-run`
`uninstall`	`--purge`, `--dry-run`, `--yes`

failproofai update should be run after npm install -g failproofai@latest; it performs home-layout migrations, installs the matching daemon binary, and restarts the service. It then moves every Hermes profile that already uses FailproofAI to the linked native plugin and prints one line per profile. --no-daemon skips the daemon step. update exits non-zero when the daemon could not be replaced, a migration failed, or a Hermes profile could not be migrated (for example because the running daemon cannot serve the native plugin, in which case its shell hooks are left in place).

Harness paths

failproofai harness list [harness]
failproofai harness add-path <harness> [label=]<path>
failproofai harness remove-path <harness> <path-or-label>

Supported harness names are claude, codex, copilot, cursor, opencode, pi, hermes, openclaw, factory, devin, antigravity, and goose. Labels namespace derived agent IDs when two roots contain copies of the same project. Overlapping roots and duplicate labels are rejected to prevent duplicate collection or cursor corruption. Extra-path configuration reloads without a daemon restart. Container environments can replace file-configured extra paths with a comma-separated variable named FAILPROOFAI_<HARNESS>_EXTRA_PATHS, for example:

export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b"

Environment variables

Use configuration files for persistent machine behavior. Environment variables are most useful for containers, tests, and one process.

Variable	Use
`FAILPROOFAI_CLOUD_TOKEN`	The Cloud key, instead of `--token`. Prefer this: an argument is readable from `ps` by every user. Set it with `read -s` or from a CI secret store, never by typing the key into a command, which lands in shell history either way
`FAILPROOFAI_CLOUD_URL`	The Cloud URL, instead of `--url`. The same variable the daemon reads
`FAILPROOFAI_HOME`	Relocate the complete `~/.failproofai` layout
`FAILPROOFAI_LOG_LEVEL`	Set local logging verbosity
`FAILPROOFAI_HOOK_LOG_FILE`	Write hook diagnostics to a selected file
`FAILPROOFAI_TELEMETRY_DISABLED=1`	Disable anonymous telemetry for this process
`FAILPROOFAI_NO_FIRST_RUN=1`	Skip interactive first-run setup
`FAILPROOFAI_NO_AUTO_AUDIT=1`	Skip the post-setup local audit
`FAILPROOFAI_LLM_BASE_URL`	Override the OpenAI-compatible endpoint used by LLM policies
`FAILPROOFAI_LLM_API_KEY`	Supply the API key used by LLM policies
`FAILPROOFAI_LLM_MODEL`	Select the model used by LLM policies
`FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS`	Bound custom policy module loading
`FAILPROOFAI_NO_DOWNLOAD=1`	Refuse to fetch packs and daemon binaries; what is installed keeps enforcing
`FAILPROOFAI_PACK_BASE_URL`	Fetch packs from a mirror instead of `github.com`
`FAILPROOFAI_<HARNESS>_EXTRA_PATHS`	Replace configured extra capture paths for one harness
`NO_COLOR`	Disable colored terminal output

Agent-specific home variables such as CLAUDE_PROJECTS_PATH, CURSOR_HOME, HERMES_HOME, and OPENCLAW_HOME override where Failproof AI discovers local sessions for that harness.

Pause or remove a machine safely

failproofai config --pause
failproofai config --status
failproofai config --resume

A local session pause does not disable Cloud-managed policies. Restore Cloud deployments through the Cloud enforcement workflow when the rollout itself is the problem. Before removing the npm package, remove installed hooks and the daemon:

failproofai uninstall --dry-run
failproofai uninstall --yes
npm rm -g failproofai

Run failproofai <command> --help for version-specific details.

Run failproofai uninstall before npm rm -g failproofai; npm does not remove installed agent hooks or the daemon service.

Connect your agents

Jev reference

Reference

HTTP API

Set up a machine

Configuration flags

Policy flags

Delivery and maintenance flags

Harness paths

Environment variables

Pause or remove a machine safely

​Set up a machine

​Configuration flags

​Policy flags

​Delivery and maintenance flags

​Harness paths

​Environment variables

​Pause or remove a machine safely

Set up a machine

Configuration flags

Policy flags

Delivery and maintenance flags

Harness paths

Environment variables

Pause or remove a machine safely