---
title: CLI
description: Install @izri/cli, configure it with three environment variables, and run the four signals from your terminal.
order: 20
---

# 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

```bash
# 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.

```bash
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.

```bash
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`.

```bash
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:

```bash
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](/docs/reference/verdicts-and-exit-codes) for the exact status-to-exit-code mapping.

## Related

- [GitHub Action](/docs/install/github-action) — the same CLI, wired into pull requests.
- [MCP server](/docs/install/mcp) — the same signals, exposed to coding agents.