CLI

@izri/cli is the terminal surface for Izri, and the foundation every other integration shells out to — the GitHub Action installs this CLI and calls it.

Install

# One-shot, no install
npx @izri/cli@latest --version

# Global
npm install -g @izri/cli
izri --version

Requires Node.js 18 or newer.

Configure

Three environment variables:

Variable	Required	Example
IZRI_API_URL	yes	https://api.izri.ai
IZRI_API_TOKEN	yes	izri_xxxxxxxxxxxxxxxx
IZRI_PROJECT_ID	no	01HK0... (ULID)

Mint the token from your organization settings. It must start with izri_ — the API short-circuits to bearer validation on that prefix, so a token without it produces an opaque 401 rather than a useful message.

How the project gets resolved

IZRI_PROJECT_ID is optional. Resolution order:

1. --project <id> on the command
2. IZRI_PROJECT_ID
3. auto-match — inside a git checkout with a GitHub origin remote, the CLI matches owner/repo against the projects your token can see

Auto-match uses the same comparison the GitHub App webhook does, so the CLI and your PR checks always agree about which project a repository belongs to.

Commands

izri run

Trigger a test run for the current repository.

izri run                        # fire and forget
izri run --watch                # poll until terminal
izri run --project 01HK...      # explicit project

Flag	Description
-p, --project <id>	Project ULID. Otherwise auto-resolved from the git remote.
--watch	Poll until the run reaches a terminal status.

The current HEAD SHA and branch are sent automatically.

--watch polls every 3 seconds until the run reaches PASSED, FAILED, ERROR, or CANCELLED, with a 30-minute hard cap. It exits non-zero on any terminal status except PASSED, so CI scripts can branch on it directly.

izri check-scope

Run scope analysis on your local diff without triggering a test run. Deterministic and fast.

izri check-scope
izri check-scope --base origin/develop
izri check-scope --semantic
izri check-scope --json

Flag	Default	Description
-p, --project <id>	(auto)	Project ULID.
-b, --base <ref>	origin/main	Base ref to diff against.
--semantic	off	Opt into the LLM semantic layer. Tier-gated server-side.
--json	off	Emit raw JSON instead of the formatted summary.

The default base is origin/main. If your trunk is named anything else, pass --base or the diff will be wrong rather than empty — worth wiring into a shell alias.

--semantic costs AI tokens and is gated by your plan. Without it you still get the full deterministic rule layer: path categorization, commit-vs-files alignment, sensitive-path hints, and scale anomalies.

izri status

Fetch the latest delta report for the current HEAD.

izri status
izri status --json

Flag	Default	Description
-p, --project <id>	(auto)	Project ULID.
--json	off	Emit raw JSON instead of the formatted summary.

Use this after a push to read the verdict without opening GitHub.

Scripting against it

--json plus a non-zero exit on failure is the whole contract:

if ! izri run --watch; then
  echo "Izri verdict is not passing"
  izri status --json > izri-report.json
  exit 1
fi

See verdicts and exit codes for the exact status-to-exit-code mapping.

Related

• GitHub Action — the same CLI, wired into pull requests.
• MCP server — the same signals, exposed to coding agents.