> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iriscode.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Iris Code CLI: Code Health Enforcement from the Terminal

> The @iris-code/cli package brings Iris Code health analysis to any terminal, build script, or CI pipeline. Thirteen commands cover scanning, gating, secrets, security smells, dependencies, CVEs, SBOMs, Slack notifications, and hooks.

The same analysis, without an editor. Install it, point it at a file or a directory, and you get the scores and findings the sidebar would show you.

## When to use which

The extension is interactive. It scores files as you work and puts findings next to the code you are writing.

The CLI is not. It scans, prints a result, and exits with a status code another tool can act on. That makes it the right choice for hooks, build scripts and CI pipelines, where no one is watching a sidebar and the only meaningful output is whether to continue.

## Installing

Install the CLI globally with npm:

```bash theme={null}
npm install -g @iris-code/cli
```

<Note>
  Node 18 or later is required. Run `iris --version` after installation to confirm the package is on your PATH.
</Note>

## Updating

`npm install -g` does not auto-update. If a command you expect is missing (`iris: unknown command: sbom`) or the CLI crashes on exit, you are almost certainly running an old global install - a new npm publish never touches whatever version is already on your PATH. Update it explicitly:

```bash theme={null}
npm install -g @iris-code/cli@latest
iris --version
```

Confirm the printed version matches the [latest CLI release](https://www.iriscode.co/changelog). If you have multiple Node versions or package managers installed, `which iris` (macOS/Linux) or `Get-Command iris` (PowerShell) shows exactly which install is on your PATH.

## Quick start

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    npm install -g @iris-code/cli
    ```
  </Step>

  <Step title="Authenticate (opens browser)">
    ```bash theme={null}
    iris auth login
    ```

    A browser window opens for OAuth sign-in. Your credentials are saved to `~/.iris/credentials` for subsequent commands.
  </Step>

  <Step title="Scan the current directory">
    ```bash theme={null}
    iris check .
    ```

    Iris Code scores every source file in the working directory and prints a summary to stdout, then exits with code `0` (all pass) or `1` (one or more files below threshold).
  </Step>
</Steps>

## Free commands

These commands are available without an Iris Code Pro licence:

* **`iris check <file>`** - single-file health scan; scores and prints findings for one source file
* **`iris secrets`** - scans the whole project for hardcoded secrets, API keys, and tokens; no authentication required
* **`iris security`** - scans the whole project for security smells (eval usage, SQL injection, insecure RNG, weak hashing, and more); no authentication required
* **`iris report`** - export a standalone HTML health report for the workspace
* **`iris config init` / `iris config validate`** - interactively generate `.irisconfig.json` from a preset, or validate an existing one
* **`iris hook status`** - show whether the git pre-push hook and build hook are currently installed

## Pro commands

These commands require an active Iris Code Pro licence:

* **`iris check <dir>`** - scan an entire directory tree and score every source file
* **`iris check --staged`** - scan only files currently staged in git
* **`iris check --changed`** - scan only files changed since the last commit
* **`iris deps`** - audit `package.json`, `go.mod`, `requirements.txt`, or `pyproject.toml` for outdated versions and known CVEs, with installed versions resolved from your lockfile
* **`iris cve`** - CVE severity gate for CI; exits `1` only when an advisory at or above a chosen severity is found
* **`iris sbom`** - export a CycloneDX 1.5 software bill of materials, fully offline
* **`iris todos`** - list every `TODO`, `FIXME`, and `HACK` comment across the project
* **`iris gate`** - CI quality gate; exits `1` if any configured rule fails (`minHealthScore`, `gateMaxSecrets`, `gateMaxComplexity`, `gateMaxFileLength`, `gateMaxSmellsPerFile`, `gateMaxSecuritySmells`)
* **`iris slack setup|test|manifest`** - configure and test Slack notifications sent directly from your own CI
* **`iris hook install|uninstall`** - install or remove git pre-push and build hooks

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/cli/auth">
    Sign in via browser OAuth or set up a licence token for non-interactive CI runners.
  </Card>

  <Card title="Commands" icon="terminal" href="/cli/commands">
    Full reference for all thirteen Iris Code CLI commands, flags, and exit codes.
  </Card>

  <Card title="CI Integration" icon="gear" href="/cli/ci">
    Use `iris gate` as a quality gate in GitHub Actions, GitLab CI, or any shell pipeline.
  </Card>

  <Card title="GitHub Actions" icon="github" href="/enforcement/github-actions">
    Full workflow guide including branch protection rules and threshold configuration.
  </Card>
</CardGroup>