earnie CLI is how pipelines, scripts, and coding agents talk to Earnie without the console. It never selects a default Project, and its JSON output is versioned so automation can rely on it.
Signing In
For interactive use:Running a Scan
--project, EARNIE_PROJECT, or the connected Git remote, in that order — it never picks a default Project. Use --format json (or --json) for a single machine-readable result; progress and diagnostics go to standard error, where --quiet silences progress but never errors, and --color auto|always|never controls styling. Outside a terminal the output is plain lines.
Exit Codes
A blocking scan waits for scanning and policy evaluation, then exits from the gate:
Exhaustion, timeout, and interruption leave the server-side Scan running and print its ID — they never cancel it.
Non-Blocking and Follow-Up Commands
earnie scan --no-waitexits0as soon as the Scan is accepted, returning its ID with anullgate.earnie scan wait <id>waits for it and applies the gate exit codes above.earnie scan status <id>andearnie scan listare observational — they exit0whenever the query succeeds, whatever the Scan’s own state is.earnie verdict <id>reads the gate a completed Scan was given and the policy revisions that produced it, with the current Policy Approval overlay applied. It never re-evaluates; after an Approval decision, running it again shows the updated gate.earnie scan audit <id>prints the Scan’s Audit trail — submission, gate, approvals, and publications, oldest first, one line per event with when, what, and who. It’s observational too, exiting0whatever the gate says.
JSON Output
The JSON document carriesschema_version: "1": the Project and how it was resolved, the Scan, its effective scanners, enrichments and policy snapshot, the evaluation, the gate and its reason, one entry per policy revision, a findings summary, links, and a typed error whose code, category, retryable, and request_id are stable for automation.
By default, findings are summarised with included: false, a total (null when the key can’t read findings), and a findings_url. --include-findings fetches every page with each finding’s verdicts and evidence, and fails rather than silently truncate when it can’t. New optional fields may be added under version 1; nothing is removed or renamed without a new version.
earnie scan audit <id> also has a --format json form: the trail is an optional audit member, each event carrying its type, time, the actor as recorded at the time, and a frozen set of payload keys a script can branch on.Policies (Read-Only)
Three read-only commands answer for the policies of one Project, resolved the same wayscan resolves it:
earnie policy list— the policies attached to the Project (the set that gates its next scan), one line each with slug, action, whether it’s enabled, its latest state, and its revision.earnie policy show <slug>— one policy in full: name, source, module, action, the sentence given to an agent (flagged when stale), the CEL expression, each parameter’s effective value, and the Project’s latest result for it.earnie policy violations <slug>— the findings currently violating that policy, one line each with finding ID, verdict, the status of any Policy Approval, component, and file. Paged locally with--limit(1–200, default 50) and--offset.
revision, the sha256: digest of what the gate does — the same value a Scan’s policy snapshot and earnie verdict report, so you can tell whether the policy that blocked a scan is the one in force now. All three commands exit 0 whenever the query succeeds, whatever the policies say; an unknown slug exits 8 with the typed error policy_not_found.
Connecting a Coding Agent (MCP)
A coding agent — Claude Code, Cursor, VS Code, Codex — can talk to Earnie directly over MCP, with one API key. What it can ask for depends on the Earnie tools your deployment offers and the permissions on that key; the agent lists its granted tools when it connects. Create the key with the Coding agent (MCP) preset, which grants read access to projects, policies, findings, and scans, plus the ability to submit a scan — the same permission a CI key holds, so the same key can start a full scan that records findings and moves the project’s posture. Triage stays off unless allow agents to triage findings is enabled; the audit log attributes each decision to the key.Setup
EARNIE_API_KEY for Claude Code, Cursor, VS Code, or Codex — setup writes the stored key into each client’s user-level configuration. Earnie detects installed clients from their executables, application paths, and native configuration files, and preselects what it finds. Use --client detected or an explicit list (--client claude,codex) in scripts and redirected runs — without --client, a non-interactive setup stops rather than guessing.
Repository setup resolves the Project the same way scan does (--project, EARNIE_PROJECT, or the Git remote) and needs policies:read to fetch the Project’s managed policy block before changing any file. Useful flags:
Setup validates the complete change first, then applies identity, policy instructions, and hooks as one transaction — a write failure restores the previous files.
Earnie owns only the text between its own markers (for example
<!-- earnie:policies:start --> … <!-- earnie:policies:end -->) and, in Cursor’s dedicated earnie.mdc, the front matter that makes the rule apply to every chat. It leaves every other byte and the file’s permissions alone, and stops rather than guessing if it finds duplicate, nested, incomplete, or hand-edited markers.Codex project hooks don’t run until you review and trust their exact definition with
/hooks inside Codex — setup never bypasses that trust control.Review Hooks and Self-Checks
On first repository installation, setup enables project-local end-of-turn review hooks for Claude Code, Cursor, and Codex (VS Code has none yet). When the agent reaches a turn’s end, any files it changed during that turn — including documentation-only changes — are sent once to Earnie for review. This is a Self-check, not a Scan: it creates no findings and doesn’t move the project’s posture. Every Self-check is listed under the project’s Self-Checks page for 30 days, and the agent gets a deep link to the result. A blocking result gives the agent one correction turn before the next end-of-turn review always ends, reporting whatever findings remain. For a manual check outside the hook flow:EARNIE_SKIP_REVIEW=1 to record a visible, user-requested skip instead of making a review call.
Doctor and Uninstall
EARNIE_API_KEY or a stored key is valid, the effective Project, and user-level identity. It calls the server’s live MCP tools/list to report each tool’s visibility, required scope, and absence reason — it never grants a hidden tool. --global checks connection and authentication only. Doctor never mutates config, rules, hooks, or credentials.
--client selection as setup. It does not remove the user-level API URL and key, so other checkouts keep working. --dry-run previews every removal, and repeated runs are safe.