Earnie CLI - SCANOSS documentation

The earnie CLI (command-line interface) lets pipelines, scripts, developers, and coding agents work with Earnie without opening the web app. Use it to:

run a scan from a CI pipeline and fail the build when a policy blocks
check your staged changes before you commit
read a project’s policies, or a scan’s verdict, from a script
export an SBOM
scan an AI model file that doesn’t live in a repository
connect a coding agent such as Claude Code or Cursor to Earnie

Every command follows two rules:

It never picks a project for you. You say which project a command applies to, or the CLI works it out from your Git repository. See Choosing the Project.
Its JSON output is versioned. Automation built on version 1 keeps working when the CLI adds fields. See JSON Output.

Before You Start

You need three things:

Your Earnie API URL: the address of your organisation’s Earnie, for example https://your-company.earnie.dev. It’s the address you open the web app at.
An API key: the credential the CLI uses to act for you. An Admin or Operator creates it in Settings, on the API Keys tab. Pick the preset for the job: CI pipeline for a pipeline, or Coding agent (MCP) for an agent. See API keys.
A project in Earnie for the code you want to check. Most projects come from connecting a repository.

Earnie shows a new key only once, so store it straight away, for example in your pipeline’s secrets.

Installing

Choose one of four ways to install the CLI. Homebrew (macOS or Linux)

brew install scanoss/dist/earnie

Install script (Linux or macOS)

curl -fsSL https://github.com/scanoss/earnie-cli/releases/latest/download/install.sh | sh

The script installs the latest release for amd64 or arm64. It checks the download against the release’s SHA-256 checksums before installing.

Where it installs. ~/.local/bin by default. Set EARNIE_INSTALL_DIR to install somewhere else. The script never uses sudo: if the directory isn’t writable, it stops and asks you to choose another.
A specific version. Set EARNIE_VERSION to a version number without the v, for example EARNIE_VERSION=0.3.1.
Signature check. If cosign is on your PATH, the script also verifies the release’s signature on checksums.txt, and stops if it’s bad. Without cosign, it prints that it skipped the signature check, with the exact cosign verify-blob command to run yourself.

Release archive (Linux, macOS, or Windows) Each release on the Earnie CLI releases page has prebuilt archives and a checksums.txt file of SHA-256 sums:

Linux and macOS, for amd64 and arm64, as .tar.gz archives
Windows, for amd64, as a .zip archive

Download the archive for your platform, check it against checksums.txt, and put the earnie binary (earnie.exe on Windows) in a directory on your PATH. Container image The image is ghcr.io/scanoss/earnie-cli:X.Y.Z, where X.Y.Z is a release number such as 0.3.1. Its entry point is earnie, so the container’s arguments are the command, such as scan path .. The container has no system keychain, so pass the API URL and key as the EARNIE_API_URL and EARNIE_API_KEY environment variables at run time. Don’t build credentials into an image.

Checking the Version

earnie version

This prints the CLI’s version and the source commit it was built from. Once an API URL is set, it also asks your Earnie, without an API key, for:

the version of Earnie’s API
the oldest CLI version it supports
the JSON schema versions it accepts

earnie --json version returns the same data as JSON. If your CLI is older than the oldest version your Earnie supports, every command that talks to Earnie stops with exit 8 and tells you which version to install.

A released CLI may print an update notice on standard error after a successful command. The check is best effort: it never changes the exit code, and never installs anything. Turn it off for one command with --no-update-check, or set EARNIE_NO_UPDATE_CHECK=1 in automation.

Signing In

The CLI needs to know which Earnie to talk to and which API key to use. On your own machine, sign in interactively. The CLI asks for the key and hides it as you type:

earnie auth login --api-url https://your-company.earnie.dev

In CI, where no one can answer a prompt, pass the key on standard input. Never put the key on the command line, where it can end up in logs:

printf %s "$EARNIE_API_KEY" | earnie --api-url https://your-company.earnie.dev auth login --api-key-stdin

When it succeeds, the CLI prints Signed in to and the URL. It stores:

the API URL in ~/.config/earnie/config.toml
the API key in your operating system’s keychain, or in ~/.config/earnie/credentials.json, readable only by you, where no keychain is available

auth login doesn’t check the key with Earnie. The first command that calls Earnie does, and exits 4 if the key is invalid or expired. Instead of signing in, you can set the EARNIE_API_URL and EARNIE_API_KEY environment variables. EARNIE_API_KEY overrides a stored key and is never saved. This suits CI and containers. See Options and Environment Variables.

Running a Scan

A scan uploads source code to Earnie, which checks it against the project’s policies and returns a gate: Earnie’s decision for the scan, which is pass, warn, require (needs an approval), block, or none when no policy applies. Three commands choose what to scan:

Command	What it scans
`earnie scan path [path]`	Everything under the path you give it, or the current directory.
`earnie scan staged`	The changes you’ve staged in Git, exactly as they’ll be committed.
`earnie scan diff --base <ref>`	The changes on your branch since it diverged from `<ref>`, such as `origin/main`.

For example, to scan the current directory and see why the gate is what it is, replacing my-project with your project’s slug:

earnie scan path . --project my-project --details

Inside a repository that Earnie already has a project for, you can leave out --project. earnie scan staged creates a Self-check, a quick check that creates no findings and doesn’t change the project. The other two create a scan, listed in the project’s Scan history. A scan never sends symlinks or special files such as sockets, and the CLI never follows a link. If a link’s target is inside the scanned tree, the CLI scans the target at its own path. It reads nothing outside the scanned path, and refuses a scan path that is itself a symlink. scan staged and scan diff also leave out Git submodules. When earnie scan staged finds nothing staged, or earnie scan diff finds no changed source files, there’s nothing to check. The command sends nothing to Earnie, prints nothing to check: and the reason on standard error, and exits 0.

Choosing the Project

The CLI works out which project to use from the first of these that’s set:

the --project flag, with the project’s slug or ID
the EARNIE_PROJECT environment variable
the Git remote origin of the repository you’re in, when Earnie has a project for that repository

If none of them identifies a project, the command stops with exit 8. It never falls back to a default project. The Git remote works only for github.com and gitlab.com. On GitHub Enterprise Server or a self-managed GitLab, set --project or EARNIE_PROJECT.

Choosing Scanners

By default, a scan runs every scanner your organisation has enabled that your key may use. Pass --scanners to run only some of them for this one scan, as a comma-separated list from oss, crypto, and ai:

earnie scan path . --scanners oss,crypto

A policy that reads only a scanner the scan didn’t run, such as an AI policy on an OSS-only scan, is reported as not_applicable and doesn’t decide the gate. If a scanner the scan did run fails, the command exits 3.

Output

Option	Effect
`--details`	Lists the policies and findings behind the gate.
`--format json` (or `--json`)	Prints a single machine-readable result. See JSON Output.
`--quiet`	Hides progress messages. Errors are always shown.
`--color`	Coloured output: `auto` (the default), `always`, or `never`.

Progress and diagnostics go to standard error, so they never mix with the result on standard output. When the output isn’t a terminal, for example in a CI log, the CLI writes plain lines.

Exit Codes

By default, a scan command waits for the scan and its policy check to finish, then exits with a code based on the gate. A pipeline can use the code to pass or fail a build:

Exit	Meaning
`0`	`pass`, `warn`, or `none`. With `none`, no policy applied, and the CLI says the scan completed without enforcement.
`1`	`block`.
`2`	`require`. A policy needs an approval. The CLI returns at once with a link to the scan, instead of waiting for someone to decide.
`3`	The scan, the policy check, or the gate failed, was cancelled, or has no known result.
`4`	No API key, or the key is invalid or expired.
`5`	The key lacks a scope the command needs, or the project or scanner is outside what the key may use.
`6`	Earnie couldn’t be reached, or stayed unavailable after the CLI retried.
`7`	The CLI stopped waiting: the local timeout (95 minutes by default) ran out. Change it with `--timeout`, for example `--timeout 2h`.
`8`	Invalid usage or configuration, such as a missing required flag, a project that can’t be found, or a CLI too old for your Earnie.
`9`	Only from `earnie mcp doctor` and `earnie mcp setup --check`, when they find a problem.
`130`	Interrupted, for example with Ctrl+C.

Exits 6, 7, and 130 stop the CLI waiting, but never cancel the scan. It keeps running on Earnie, and the CLI prints its ID and the command to pick it up again: earnie scan wait <id>. If Earnie is unreachable or answers with a server error, the CLI waits out the outage instead of failing at once. Its compatibility check and each poll for a result retry up to 8 times, waiting 1 second and doubling up to 30 seconds, about 90 seconds in all. A client error, such as a missing project, fails at once. When Earnie answers with a server error, the message includes a request ID, for example Quote request ID <id> when you report this. Give that ID to your administrator, who can find the cause in Earnie’s logs.

Non-Blocking and Follow-Up Commands

To keep a pipeline step from waiting, start the scan without waiting and check on it later:

Command	What it does
`--no-wait`, on `scan path`, `scan staged`, or `scan diff`	Exits `0` as soon as Earnie accepts the scan, and prints its ID. Can’t be combined with `--format hook`.
`earnie scan wait <id>`	Waits for that scan, then exits with the exit codes above.
`earnie scan status <id>`	Shows the scan’s current state, without waiting.
`earnie scan list`	Lists the project’s scans, 50 at a time. Filter with `--status` (`pending`, `receiving`, `extracting`, `scanning`, `importing`, `completed`, `failed`, or `cancelled`), and page with `--limit` (1–200) and `--offset`.
`earnie verdict <id>`	Reads the gate a completed scan was given, and the policy revisions that produced it, with any Policy Approvals applied. It never re-checks the scan. After someone decides an approval, run it again to see the updated gate.
`earnie scan audit <id>`	Prints the scan’s audit trail, oldest first: submission, gate, approvals, and publications, one line per event, with when, what, and who.

scan status, scan list, and scan audit only report. They exit 0 whenever the query succeeds, whatever the scan’s state or gate.

JSON Output

With --format json, the CLI prints one JSON document with schema_version: "1". Its main members are:

project: the project, and how the CLI found it (resolution)
scan: the scan, with its status, coverage, and where it came from
effective: what the scan actually ran, including its scanners, enrichments, and policy snapshot
gate and gate_reason: the decision, and why
policies: one entry for each policy revision that was checked
findings: a summary of the findings
links: links to the scan, project, findings, and approval in the web app
error: on failure, a typed error whose code, category, retryable, and request_id fields are stable for automation

By default, findings are summarised, not listed: included: false, a total (null when the key can’t read findings), and a findings_url. Add --include-findings to fetch every finding, with its verdicts and evidence. If the CLI can’t fetch them all, the command fails rather than return a partial list. An AI model finding also carries a model member, with its status, purl, name, match method, and confidence band. --details shows the same in the human output. earnie model scan --format json adds a model member. See Scanning an AI Model. earnie scan audit <id> --format json adds an audit member. Each event carries its type, its time, the actor as recorded at the time, and a fixed set of payload keys. Version 1 may gain new optional fields. No field is removed or renamed without a new version.

Running in a Pipeline

In GitHub Actions and GitLab CI, earnie scan path and earnie scan diff read details of the pipeline they run in, and send them with the scan: the repository, the pull or merge request, the commit, the branch, and a link to the run. The project’s Scan history then shows the run as CI, with its pull or merge request.

Only a pull request pipeline names a pull request. On GitHub, that’s the pull_request event. On GitLab, it’s a merge request pipeline. Any other pipeline, including pull_request_target, is a branch pipeline.
A scan that names a pull or merge request has partial coverage. It checks the change, and never changes the project’s findings.
The job’s exit code comes from the gate. See Exit Codes.
Keep the API key secret. Store it as a repository secret or a masked CI/CD variable, never in the pipeline file.

GitHub Actions

Add a repository secret named EARNIE_API_KEY, holding a key with the CI pipeline preset.

Add a workflow file, such as .github/workflows/earnie.yml, that checks out the code and runs the Earnie action, pinned to a CLI release. Replace vX.Y.Z with the release tag, such as v0.3.1, and the URL with your Earnie’s:

name: Earnie
on:
  pull_request:
  push:
    branches: [main]
jobs:
  earnie:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
      - uses: scanoss/earnie-cli@vX.Y.Z
        with:
          api-key: ${{ secrets.EARNIE_API_KEY }}
          api-url: https://your-company.earnie.dev

On a pull request, this checks out the pull request’s own commit, so Earnie scans the change. On a push to main, it scans the branch.

The action installs the CLI version matching its tag and runs earnie scan with its args input. Its inputs are:

Input	Required	What it sets
`api-key`	Yes	The API key.
`api-url`	Yes	Your Earnie API URL.
`project`	No	The project’s slug or ID. By default, the CLI finds it from the Git remote.
`args`	No	The arguments to `earnie scan`. The default is `path .`.

GitLab CI

Add EARNIE_API_KEY (masked) and EARNIE_API_URL as CI/CD variables. Then include the Earnie template in .gitlab-ci.yml, replacing vX.Y.Z with the release tag:

include:
  - remote: https://raw.githubusercontent.com/scanoss/earnie-cli/vX.Y.Z/gitlab/earnie-scan.yml

The template runs in the ghcr.io/scanoss/earnie-cli image. It runs on merge request pipelines, and on branch pipelines of branches with no open merge request. Its args input changes the arguments to earnie scan (path . by default), and its stage input sets the stage (test by default).

Self-hosted Git. The CLI can’t work out the project from a GitHub Enterprise Server or self-managed GitLab remote, so set EARNIE_PROJECT, or the action’s project input. On GitHub Enterprise Server, uses: scanoss/earnie-cli@vX.Y.Z works once your administrator has enabled GitHub Connect or synced the action with actions-sync. On a GitLab instance that can’t reach the internet, copy earnie-scan.yml into a project of your own, include it from there with include: project, and mirror the ghcr.io/scanoss/earnie-cli image it names.

The CLI refuses a pipeline it can’t read with exit 8, before uploading anything: ci_ambiguous when both GitHub Actions and GitLab CI variables are set, and ci_event_unreadable when a pull or merge request pipeline doesn’t name its pull or merge request. earnie scan staged ignores the pipeline and always runs a Self-check.

Checking Before You Commit

A pre-commit hook is a script Git runs before each commit. Earnie’s hook checks your staged changes against the project’s policies, so you find a problem before you push, not when the pull request is checked.

Installing the Hook

The hook uses your stored sign-in, and finds the project the same way scan does, so set those up first. Then run this once, from inside the repository:

earnie hook install

The installed hook runs exactly earnie scan staged --format hook, so it runs every scanner your organisation has enabled. To run only some, add --scanners to that command in your own hook.

It uses Git’s own hooks directory, including a configured core.hooksPath and linked worktrees.
You can run it again safely: if Earnie’s hook is already there, it says so and changes nothing.
If another tool or a hand-written hook already owns pre-commit, Earnie leaves it untouched, exits 8, and tells you to add earnie scan staged --format hook to that hook instead.

What the Hook Checks

The hook reads the Git index, what you’ve staged, not your working files:

It scans added, copied, modified, and renamed files exactly as they’ll be committed.
For a deleted file, and the old name of a renamed one, it tells Earnie the file is gone, so the check knows what was removed.
It ignores changes you haven’t staged.

Reading the Result

The hook prints plain text in a fixed format, with no colour or progress animation:

the project
how many files were submitted and included
the verdict
any scanners the check didn’t run, and why
up to 20 findings, as path:line
a link to the Self-check in the web app

Verdict	Commit	Exit
`pass`, `warn`, or `none`	Allowed	`0`
`block`	Stopped	`1`
`require`	Allowed, with a notice that an approval is required. The pull request check still decides.	`0`

If your Earnie can’t run a scanner your organisation has enabled, the check runs the others and lists the missing one under the scanners it didn’t run. A policy whose scanner didn’t run is recorded as not evaluated, not as passing. Each run creates a Self-check, listed with Pre-commit hook as its source. It’s the same page a coding agent’s review lands on. If you run earnie scan staged yourself, its Self-check is listed as CLI self-check instead.

When the Check Can’t Run

The whole hook run has a 60-second limit, from finding the project and credentials through to the result. If the check can’t finish, for example because of a key, network, or timeout problem, the hook shows the error. By default it is fail-open: it says the Self-check was unavailable, and lets the commit continue. To make these errors stop the commit instead (fail-closed):

For a whole project, an Operator or Admin turns on Pre-commit technical failures in the project’s Scan Configuration.
For your own checkout only, set EARNIE_HOOK_FAIL_CLOSED=1. Only the value 1 counts.

The environment variable can only make the hook stricter. Leaving it unset, or setting any other value, never weakens a project that’s set to fail-closed. When fail-closed stops a commit, the hook exits with the CLI’s error code, for example 4 for a key problem, or 6 for a network problem or a timeout.

Keep the Earnie check required on your pull requests. The local hook gives early feedback, and the pull request check decides what merges. See Merge gate.

Policies (Read-Only)

A policy is a rule that says what Earnie does when a scan finds something, such as blocking a merge. Three commands read a project’s policies. They find the project the same way scan does. See Choosing the Project.

Command	What it shows
`earnie policy list`	The policies attached to the project, which decide its next scan’s gate. One line each: slug, action, whether it’s enabled, its latest state, and its revision.
`earnie policy show <slug>`	One policy in full: name, source, module and category, action, the rule given to coding agents (flagged when out of date), its expression, each parameter’s effective value, and the project’s latest result for it.
`earnie policy violations <slug>`	The findings that currently break the policy. One line each: finding ID, verdict, the status of any Policy Approval, component, and file. Page with `--limit` (1–200, default 50) and `--offset`.

Take <slug> from earnie policy list. You can’t change a policy from the CLI. Use the web app. See Setting policies. Every policy has a revision, a sha256: digest of what it checks and does. A scan’s policy snapshot and earnie verdict report the same value, 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 error policy_not_found.

Exporting an SBOM

An SBOM (software bill of materials) lists the components in your software. earnie export writes one for the project to a file:

earnie export --include oss --output sbom.json

Flag	What it does
`--include`	The sections to export, comma-separated, from `oss`, `crypto`, and `ai`. `crypto` alone gives a CBOM (cryptography bill of materials), and `ai` alone an AIBOM. An unknown section is refused before any export request.
`--bom-format`	The format: `cyclonedx` (the default) or `spdx`. SPDX needs the `oss` section.
`--output`	The file to write. The file only ever holds a complete document. Without it, the file is named `earnie-<project>-<sections>-<format>.json`.
`--scan`	The scan to export. By default, the project’s newest completed scan.
`--fresh`	Generates a new snapshot instead of reusing the latest one.

An SBOM comes from an SBOM snapshot, a fixed record of the scan at the moment it was made. So earnie export doesn’t make a new snapshot each time. It downloads the scan’s latest snapshot in the format you asked for that holds:

with --include, exactly the sections you named
without --include, the sections Earnie exports by default: open-source components, plus AI models where your plan includes them

It generates a new snapshot only when none matches, when triage decisions changed after the latest one, or with --fresh. When it replaces an out-of-date snapshot, it says so on standard error. Generating a snapshot needs a key with scans:write, which the CI pipeline preset has. A scan that finished before Earnie began keeping SBOM evidence can’t be exported. The command fails with scan_evidence_unavailable: run a new scan, then export again.

Scanning an AI Model

earnie model scan uploads one AI model file to the project and reports what Earnie found out about it. It’s the command-line form of Upload a file on the project’s Models page. See Uploading a Model.

earnie model scan ./llama-3-8b.safetensors --project acme

The file can be model weights, such as .safetensors, .gguf, or .onnx, or a Hugging Face snapshot as a .tar, .tar.gz, or .tgz archive. To scan a snapshot directory, archive it first. The command finds the project the same way scan does. See Choosing the Project. The command needs:

CLI 0.4.0 or later
AI provenance enabled for your organisation
a key with scans:read and scans:write, which the CI pipeline preset has

If the upload stops, for example because the connection drops, run the same command again. Earnie resumes from the bytes it already holds, so a large file isn’t sent twice. By default, the command waits for the model’s scan, then prints the model’s status and one line for each finding: its status, the model it was identified as, its purl, the confidence band, and the licence.

Flag	What it does
`--no-wait`	Exits `0` as soon as the upload is complete, and prints the model’s ID. The scan keeps running on Earnie.
`--timeout`	How long to wait for the scan, 95 minutes by default. When it runs out, the command exits `7` and the scan keeps running.

Its exit codes follow the exit codes above, without a gate:

Exit	Meaning
`0`	The scan finished. This includes a model that Earnie couldn’t identify: its finding says Not identified.
`3`	The model’s scan failed, with the error `model_scan_failed`. Run the command again to retry.
`7`	The local timeout ran out.
`8`	The path is a directory, missing, or empty, or the file is over the model size cap (`model_too_large`). The message names the cap, 3 GB unless your deployment sets another.

4, 5, and 6 mean what they mean for every command. A key whose organisation has no AI provenance gets 5, with the error module_disabled. With --format json, the document has a model member with the upload ID, the model ID, its SHA-256 hash, its status, its scan, and its findings. Like an upload from the web app, the model gets its own scan, appears on the project’s Models page, and Earnie deletes its weights once the scan ends. Models over the size cap can’t be scanned from the CLI yet.

Connecting a Coding Agent (MCP)

MCP (Model Context Protocol) is a standard way for AI coding agents to call outside tools. When you connect an agent to Earnie over MCP, it can ask what your policies say and have its changes checked while it works.

This section is the reference for the earnie mcp commands. For a step-by-step guide to connecting an agent, the tools it gets, and troubleshooting, see Earnie MCP.

Claude Code, Cursor, VS Code, and Codex can connect to Earnie with one API key. What the agent can do depends on the Earnie tools your organisation has and the scopes on that key. The agent lists the tools it’s been given when it connects.

Creating the Key

Create the key with the Coding agent (MCP) preset. See API keys. It grants:

read access to projects, policies, findings, and scans (projects:read, policies:read, findings:read, scans:read)
permission to submit a scan (scans:write)

That’s the same scan permission a CI key holds, so the key can start a full scan that records findings and changes the project’s posture, not only Self-checks. The agent can’t triage findings unless Allow agents to triage findings is turned on for the key, which adds findings:write. The audit log attributes each decision the agent makes to the key.

Setting Up an Agent

earnie auth login --api-url https://your-company.earnie.dev

From inside your repository, run setup:
earnie mcp setup
Setup finds the clients you have installed, from their programs and configuration files, and preselects them. Choose the ones to set up.
Restart the agent, then check the setup with earnie mcp doctor. See Checking and Removing the Setup.

Setup writes the stored key into each client’s user-level configuration, so you don’t need to export EARNIE_API_KEY for the agent. Setup finds the project the same way scan does: --project, EARNIE_PROJECT, or the Git remote. It needs policies:read, because it fetches the project’s policy instructions before changing any file. In scripts and other non-interactive runs, pass --client detected or a list such as --client claude,codex. Without --client, a non-interactive setup stops rather than guessing.

Flag	What it does
`--dry-run`	Prints the exact change to each file, without writing anything.
`--client`	The clients to set up: `detected`, or a comma-separated list from `claude`, `cursor`, `vscode`, and `codex`.
`--global`	Sets up only the user-level client configuration: no project, no policy instructions. Can’t be combined with `--project`.
`--no-hooks` / `--hooks`	Skips, or installs or upgrades, the review hooks.
`--json`	Prints one machine-readable result.
`--no-color` (or `NO_COLOR`)	Turns off coloured output.

Setup checks the whole change first, then writes it as one transaction. If a write fails, the previous files are restored.

Where Setup Writes

For each client, setup writes the identity, meaning the API URL and key, to your user-level configuration. It writes a managed policy block, instructions telling the agent what your policies say, into the repository:

Client	Identity	Repository files
Claude Code	`~/.claude.json`	`CLAUDE.md`, and review hooks in `.claude/settings.json`
Cursor	`~/.cursor/mcp.json`	`.cursor/rules/earnie.mdc`, and review hooks in `.cursor/hooks.json`
VS Code	your user profile’s `mcp.json`	`.github/copilot-instructions.md`, with no review hook, because VS Code’s hook support is in preview
Codex	`~/.codex/config.toml`	`AGENTS.md`, and review hooks in `.codex/hooks.json`

The identity holds your API key, so never commit it. The repository files hold no secrets, and you can commit them.

Earnie changes only the text between its own markers, which start with . In Cursor’s earnie.mdc, it also owns the front matter that makes the rule apply to every chat. It leaves the rest of each file alone. If it finds duplicate, nested, incomplete, or hand-edited markers, it stops rather than guessing.

Codex project hooks don’t run until you review and trust them with /hooks inside Codex. Setup never bypasses that check.

Windows and WSL use different home directories. The Windows build of earnie writes to your Windows profile, such as %USERPROFILE%\.claude.json, even when you run it from Git Bash or against an Earnie served from WSL. A build running inside WSL writes to the Linux home directory. If an agent doesn’t pick up the setup, check which earnie binary ran.

Review Hooks and Self-Checks

A review hook asks Earnie to check an agent’s work at the end of each turn, before anything is committed. The first time you set up a repository, setup turns on end-of-turn review hooks for Claude Code, Cursor, and Codex. VS Code doesn’t have one yet. At the end of each turn:

The hook sends the files the agent changed during the turn to Earnie, once, including documentation-only changes.
Earnie runs a Self-check, not a scan. It creates no findings and doesn’t change the project’s posture.
The agent gets a link to the result. The project’s Self-checks page lists every Self-check for 30 days.
If the result blocks or needs an approval, the agent gets one more turn to correct it. The review after that always ends the loop, and reports whatever findings remain.

To run a check yourself, outside the hook, give earnie mcp review exactly one of these:

earnie mcp review --staged
earnie mcp review --diff <base>
earnie mcp review <file> [<file>...]

--staged checks what you’ve staged, --diff <base> checks your commits since <base>, such as origin/main, and a list of files checks those files. Set EARNIE_SKIP_REVIEW=1 (or true, yes, or on) to record a visible, user-requested skip instead of a review. Any other value doesn’t skip. earnie mcp review exits from the review’s gate, the same way a scan does:

Exit	Meaning
`0`	`pass`, `warn`, or `none`, or the review was skipped
`1`	`block`
`2`	`require`
`3`	The review didn’t finish, for example it’s still running, or it failed or has no known gate
`8`	Invalid usage, such as giving more than one of `--staged`, `--diff`, and files

Keeping the Policy Block Current

earnie mcp setup (and --hooks) also installs a session-start hook for Claude Code, Cursor, and Codex. It refreshes the managed policy block when the project’s policies change:

When a Claude Code or Codex session starts or resumes (not on /clear or compaction), or a Cursor session starts, the hook asks Earnie for the project’s rules.
If their revision differs from the one in the block, it replaces only what’s between the markers. If they match, it changes nothing.
It never adds a block to a file that doesn’t already have one.

The hook never fails a session. An unreachable Earnie adds at most about three seconds. A timeout, a missing key, a missing project, or damaged markers leave the file untouched, and the reason goes to standard error. The agent may already have read the file when the refresh lands, so a new block applies in full from the next session. VS Code has no hook, so run earnie mcp setup again to refresh its block.

Anything you change between the markers is overwritten the next time the revision changes. Put your own instructions outside them. If you edit the markers themselves, the hook stops and leaves the file alone, and earnie mcp setup reports an error until you restore them.

Hooks installed by an earlier CLI don’t include the session-start hook. earnie mcp doctor reports this (policy_refresh in --json), and earnie mcp setup --hooks adds it.

How Long a Self-Check Waits

An Operator or Admin can set how long a Self-check waits for a result before returning. It’s in Settings, on the Scan Configuration tab, under Self-check, as Self-check wait budget.

The value is a whole number of seconds, from 0 to 120. Zero uses the default of 45 seconds.
A positive wait_seconds on a REST API request overrides the setting for that request.

When the wait runs out, the check keeps running and returns its ID for you to check later, instead of a verdict. A running check is not a verdict.

Checking and Removing the Setup

To check an installation without changing anything:

earnie mcp doctor

earnie mcp setup --check does the same. Doctor reports:

whether the CLI is compatible with your Earnie
whether the key, from EARNIE_API_KEY or the one you stored, is valid
the project it would use, and the state of its policy block and hooks
each client’s configuration
the tools the agent would see, from a live request to Earnie. For each tool: whether it’s visible, the scope it needs, and why it’s missing, if it is. Doctor never grants a hidden tool.
each domain, OSS, Crypto, and AI, as visible or hidden, and why: not enabled for your organisation, or not in this key’s scope. The same reasons explain a scanner missing from a scan, or a tool your agent can’t see.

With --global, doctor skips the project and its policy block. It takes the same --client choices as setup, plus configured, to check only clients that already have Earnie set up. Doctor never changes configuration, rules, hooks, or credentials. Doctor exits 0 when everything is healthy, and 9 when it finds a problem. A repository set up for Codex always reports that its hooks need your action, because doctor can’t see whether you’ve trusted them, so doctor exits 9 there even after you have.

Behaviour change for CI scripts (CLI 0.3.0). earnie mcp doctor and earnie mcp setup --check used to exit 2 on a problem. 2 is the gate’s require code, so a script that read doctor’s 2 as “problems found” must now test for 9.

To remove Earnie from a repository:

earnie mcp uninstall

This removes Earnie’s repository MCP entries, its managed policy blocks, and its review and session-start hooks. It uses the same client detection and --client choices as setup. It doesn’t remove the user-level API URL and key, so your other repositories keep working. To remove the user-level configuration instead, without touching any repository, pass --global. --dry-run previews every removal, and running it more than once is safe.

Options and Environment Variables

These options work with every command:

Option	What it does
`--api-url`	The Earnie API URL. Overrides `EARNIE_API_URL` and the URL stored by `auth login`.
`--project`	The project’s slug or ID. See Choosing the Project.
`--format`	`human` (the default), `json`, or `hook`. `hook` works only with `scan staged`.
`--json`	The same as `--format json`.
`--quiet`	Hides progress messages. Errors are always shown.
`--color`	`auto`, `always`, or `never`.
`--no-update-check`	Skips the check for a newer release.

The CLI reads these environment variables:

Variable	What it does
`EARNIE_API_URL`	The Earnie API URL, when `--api-url` isn’t given.
`EARNIE_API_KEY`	The API key. Overrides a stored key, and is never saved.
`EARNIE_PROJECT`	The project’s slug or ID, when `--project` isn’t given.
`EARNIE_NO_UPDATE_CHECK`	`1` skips the check for a newer release.
`EARNIE_HOOK_FAIL_CLOSED`	`1` makes the pre-commit hook stop the commit on a technical error.
`EARNIE_SKIP_REVIEW`	`1` skips an agent’s review, and records the skip.
`NO_COLOR`	Turns off coloured output.

Run earnie <command> --help for every flag of a command.

Troubleshooting

What you see	What to do
Exit `8`: no Project selected	Pass `--project` or set `EARNIE_PROJECT`. The Git remote works only for github.com and gitlab.com repositories that Earnie has a project for.
Exit `4`: no API key, or the key is invalid or expired	Run `earnie auth login` again with a valid key, or check `EARNIE_API_KEY`. Keys expire, so an Admin may need to create a new one.
Exit `5`	The key is missing a scope, or can’t use this project or scanner. Ask an Admin to check the key’s preset and projects.
Exit `8`: the CLI version isn’t supported by this server	Install the version the message names. See Installing.
Exit `6` or `7`	The scan is still running on Earnie. Run `earnie scan wait <id>` with the ID the CLI printed.
`earnie hook install` says the hook is not managed by Earnie	Another tool owns `pre-commit`. Add `earnie scan staged --format hook` to that hook.
`earnie mcp doctor` exits `9`	Read its report for the failing check. With Codex, approve the hooks with `/hooks`.

What’s Next

To connect a coding agent step by step, and see every tool it can use, continue to Earnie MCP. The pre-commit hook and an agent’s review hooks both produce Self-checks, covered in Self-checks. Every command on this page authenticates with an API key. See API keys for how to create one, choose its scopes, and pick the right preset for a pipeline or a coding agent. Need help? Contact our AI assistant

​Before You Start

​Installing

​Checking the Version

​Signing In

​Running a Scan

​Choosing the Project

​Choosing Scanners

​Output

​Exit Codes

​Non-Blocking and Follow-Up Commands

​JSON Output

​Running in a Pipeline

​GitHub Actions

​GitLab CI

​Checking Before You Commit

​Installing the Hook

​What the Hook Checks

​Reading the Result

​When the Check Can’t Run

​Policies (Read-Only)

​Exporting an SBOM

​Scanning an AI Model

​Connecting a Coding Agent (MCP)

​Creating the Key

​Setting Up an Agent

​Where Setup Writes

​Review Hooks and Self-Checks

​Keeping the Policy Block Current

​How Long a Self-Check Waits

​Checking and Removing the Setup

​Options and Environment Variables

​Troubleshooting

​What’s Next

Before You Start

Installing

Checking the Version

Signing In

Running a Scan

Choosing the Project

Choosing Scanners

Output

Exit Codes

Non-Blocking and Follow-Up Commands

JSON Output

Running in a Pipeline

GitHub Actions

GitLab CI

Checking Before You Commit

Installing the Hook

What the Hook Checks

Reading the Result

When the Check Can’t Run

Policies (Read-Only)

Exporting an SBOM

Scanning an AI Model

Connecting a Coding Agent (MCP)

Creating the Key

Setting Up an Agent

Where Setup Writes

Review Hooks and Self-Checks

Keeping the Policy Block Current

How Long a Self-Check Waits

Checking and Removing the Setup

Options and Environment Variables

Troubleshooting

What’s Next