CLI Reference: mergen
One binary operates the local runtime, the policy gate, and every recovery
path. Commands are grouped under nouns, the way gh and kubectl are:
mergen insights story, mergen config rbac, mergen runtime service.
The primary binary is mergen; mergen-server remains a compatibility alias.
Run mergen help, mergen help --all, or mergen <command> --help (help
always prints help and never runs the command).
Older names still work. Every command that moved under a noun
(mergen story, mergen rbac, mergen policies, ...) runs exactly as before;
in a terminal it prints a one-line pointer to its new form. Scripts, hooks, and
pipes never see that line.
Get started
| Command | What it does |
|---|---|
mergen |
Once set up: status, then the Mergen prompt. Before that: a short first-run walkthrough of PASS / HOLD / BLOCK |
mergen setup |
Installs Mergen, connects every AI agent and editor it detects, and starts the local runtime. Use Mergen from the terminal, the editor panel, or both |
mergen setup --terminal |
Also protects commands you type in this terminal (offers the shell gate). Does not change which agents are connected |
mergen setup --no-ide |
Does not touch editor configuration: connects only agents without an editor (Claude Code, Copilot CLI, Codex); use mergen run -- <command> to gate commands explicitly |
mergen setup --full |
The same, plus guided Slack, PagerDuty, GitHub, and git-hook connection |
mergen setup --ide cursor |
Connect one agent or editor only (cursor | vscode | claude-code | windsurf | copilot | codex) |
mergen login |
Browser sign-in, required to use the CLI (Free included). Never gates enforcement: the gate runs offline either way |
mergen dashboard |
Opens My Machine in your browser: this machine's gate activity across every connected IDE |
mergen governance |
Opens My Organization on mergen.app: org-wide policies, members, and billing (human-only; no agent can reach this) |
Daily use
| Command | What it does |
|---|---|
mergen status |
Protection, IDE coverage, account, pending approvals. The badge reads Degraded - protection gap when a surface your agent uses is set up but not gating |
mergen run -- <cmd> |
Runs a command through the full gate, then executes it (alias: exec) |
mergen check -- <cmd> |
Evaluates a command without executing it; prints the verdict |
mergen approvals |
Interactive approve / deny / cancel for pending holds in this workspace. Also lists what is currently passing without a prompt (task-scoped approvals, and any command a rule was told to stop asking about for 7 days); mergen approvals revoke <id> ends either one |
mergen events [--follow] |
Recent or live PASS/BLOCK/HOLD stream (alias: logs) |
mergen events table |
Recent decisions as a filterable table (--git, --cloud, --blocked, --held, --today, --json) |
mergen events blocked |
Recent blocks with the rule that fired and the recourse for each |
mergen monitor |
Live stream where a HOLD opens an inline Approve/Deny prompt |
mergen insights |
7-day totals, top-firing rule, most active AI (--days N) |
mergen insights story | scorecard | impact | risk | timeline | postmortem | shadow |
Today's narration, coverage scorecard, Day-30 metrics, CISO risk report, causal timeline, postmortem, shadow-mode record |
mergen report fp --last |
Record the most recent block as a false positive (file-edit blocks: mergen events blocked) |
mergen trust |
Current scrutiny tier and why a routine command might be held (mergen trust reset to clear it) |
mergen panic on --minutes 15 --reason "..." |
Operator escape hatch: passes everything unenforced for a bounded window (max 4h), fully audited |
Recover
These exact forms are recognized directly by the Claude Code hook, with no network round-trip, so they work even when the gate is wedged or a hold is pending. They are the forms HOLD banners print.
| Command | What it does |
|---|---|
mergen-server approve --last --yes |
Approve the most recent hold from this session |
mergen-server deny --last --yes |
Deny it |
mergen-server cancel --last --yes |
Retire it as no longer needed (recorded as superseded, not denied) |
mergen-server trust-reset |
Reset this session's scrutiny tier if every command is suddenly being held |
mergen-server stop / start / restart |
Stop, start, or restart this workspace's runtime |
mergen-server doctor |
Health check (below) |
Health
| Command | What it does |
|---|---|
mergen doctor |
Warnings and failures only. Optional hardening is one line pointing at --security |
mergen doctor --verbose |
Every check, including passing and hardening rows |
mergen doctor --live |
Per-IDE coverage plus a live synthetic BLOCK through the real gate |
mergen doctor --fix |
Repairs what it finds: stale records, confirmed orphans, the hook, a clean instance |
mergen doctor --security |
Hardening checklist: what an agent with filesystem access could forge on this install, and how to close it |
mergen doctor --integrations |
Also validates optional external integrations |
Runtime
| Command | What it does |
|---|---|
mergen runtime |
pid, port, uptime (never starts anything) |
mergen runtime start [--background] | stop | restart |
Lifecycle (short forms mergen start / stop / restart still work) |
mergen runtime info | reload | benchmark |
Process detail, re-read the policy file, gate latency |
mergen runtime service install [--with-guard] [--system] |
Supervise the server with your OS: starts at login, restarts on crash |
mergen runtime interception install | status | repair | deploy |
Lock the hook into the IDE's root-owned managed config |
mergen runtime gated allow | deny | status | shadow |
Privileged enforcement daemon peer-auth allowlist (Linux) |
Policy
| Command | What it does |
|---|---|
mergen policy list |
Active rules with action and trigger counts |
mergen policy explain <ruleId> |
What one rule matches and why |
mergen policy publish / pull / diff |
Save the live policy to .mergen/policy.json for git, apply it back, or diff the two |
mergen policy simulate <file> |
Replay a candidate policy against historical traffic |
mergen policy test [file.json] |
Run {input, expectedVerdict} cases, no server required, CI-usable |
mergen policy versions / rollback <id> |
Restorable snapshots (immutable rules always survive a rollback) |
mergen policy allow "<pattern>" |
Append a pass rule for a command pattern (--file "<glob>" for files) |
mergen policy promote |
Promote observation-window findings into active enforcement |
mergen policy new "<intent>" |
Turn a plain-language intent into a rule (--apply to add it) |
mergen policy selftest |
Run the adversarial bypass suite against your live gate |
mergen policy native --target <t> |
Compile the live policy into a native IDE/tool config |
mergen scan <url> |
Scan an MCP server for injection vectors before you connect it |
See Policies for the rule format and condition fields.
Configure
| Command | What it does |
|---|---|
mergen config |
Every effective setting: value, source, and any ACTIVE settings that weaken enforcement |
mergen config set K V |
Write a setting to the signed config file (guarded keys need --acknowledge-risk) |
mergen config profile team |
Materialize a whole profile (solo | team | enterprise | fintech) |
mergen config secrets |
Ready-to-paste export block of fresh env-only hardening secrets (never written to disk) |
mergen config rotate-secret |
Rotate the local shared secret; live servers pick it up within seconds |
mergen config rbac list | add | set-role | remove | enable | disable |
Who may resolve holds (opt-in) |
mergen config routing list | add | rm | test |
Route holds to a team or role by path, repo, command, or resource |
mergen config notify [holds-only|all|off] |
Which gate events raise a desktop notification |
mergen connect <name> |
Guided integration setup: slack | pagerduty | github | email | sync-plane |
mergen agent register <id> / mergen agent list |
Signed identity tokens for agent profiles |
mergen org / org invite / org join <url> |
Your organization in the terminal; team invites |
mergen completion <bash|zsh|fish> |
Shell-completion script for the noun tree |
Full environment-variable reference (generated, always current): Configuration Reference.
Audit
| Command | What it does |
|---|---|
mergen audit |
Per-client rollup (claude-code / cursor / windsurf / vscode / ci) from the action ledger |
mergen audit verify [--json] |
Verify every tamper-evident audit chain; exits 1 on a broken chain, so it can run on a schedule |
mergen audit export [--format ndjson|csv|soc2|siem] [--days N] [--out file] |
Export the blunder log + HTTP compliance ledger (up to 50,000 entries; format needs your plan's audit-export entitlement) |
mergen trace-replay <traceId> |
Reconstruct the gate-event + blunder-log timeline for one cross-process trace |
Scripting
JSON. These print one JSON object on stdout, always with ok first:
status, doctor, runtime, approvals, trust, insights (and
insights story / insights scorecard), audit, audit verify, version.
events --json and events table --json print events, and monitor --json
prints one object per line. Logs and warnings go to stderr, never stdout, so
mergen doctor --json | jq .counts is safe.
Exit codes.
| Code | Meaning |
|---|---|
0 |
Success. For runtime --json this includes "not running": running is the answer |
1 |
The command failed. doctor and doctor --json exit 1 when a check fails (warnings and optional hardening do not) |
2 |
The gate did not permit it: check / gate-check on a BLOCK or HOLD, and run when a HOLD cannot be resolved inline |
130 |
Cancelled with Ctrl+C at an interactive prompt |
mergen run -- <cmd> exits with <cmd>'s own code once the gate lets it run.
Output. Color is off when stdout is not a terminal, when NO_COLOR is set,
or with --no-color. Informational log lines are suppressed for every command
except the ones that host a long-running process (start, runtime, router,
gated, guard, watch); set
LOG_LEVEL=info to get them back.
Run mergen help --all for every command a person runs from a terminal, and
mergen help --full for the complete reference, including older names.