Skip to main content
The command-line interface (CLI) is a set of commands you type in a terminal. It runs the same checks as the Iris Code editor extension: it can scan code, check packages before you install them and decide whether a project meets its standards, all without opening an editor. That makes it the right tool for anything automated, such as a check before every push or a step in your build pipeline, and for developers who prefer the terminal.

When to use which

The extension is interactive. It scores files as you work and shows findings next to the code you are writing. The CLI scans, prints a result and returns a number called an exit code. Other tools read that number to decide what to do next: a Git hook, a build script or an automated pipeline can stop when the check fails and carry on when it passes.

Installing

Install the CLI globally with npm:
Node 18 or later is required. Run iris --version after installation to confirm the package is on your PATH.

Updating

npm install -g does not update itself. Publishing a new version to npm never changes the copy already installed on your machine, so you keep running the old one until you update it. An old install is the usual cause when a command you expect is missing (iris: unknown command: sbom) or the CLI crashes on exit. Update it explicitly:
Confirm the printed version matches the latest CLI release. If you have several 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

1

Install the CLI

2

Authenticate (opens browser)

A browser window opens so you can sign in. Your credentials are saved to ~/.iris/credentials for later commands.
3

Scan the current directory

Checking a single file is Free.To scan the whole project once, run iris check . --inspect. This uses your project allowance and saves the result so you can open it again.A directory check that blocks, or a gate in CI, needs paid enforcement access.

Free commands

These commands work without an Iris Code Pro licence:
  • iris init: set a project up. It asks three short questions, recommends a preset, writes .irisconfig.json, offers the package guard, creates or refreshes the AGENTS.md rules block, and installs the pre-push hook where the licence allows.
  • iris fix --safe <file>: remove findings Iris Code can prove are safe to remove, in a single file. It previews by default and never writes without confirmation.
  • iris refactor <file>: a refactor plan for one file, with --verify to compare the result with your last commit (git HEAD). See the refactor playbook.
  • iris check <file>: score one source file and print its findings.
  • iris graph --focus <file>: what one file imports and what imports it, read the same way as the Code Map.
  • iris install / iris remove: check packages with the package guard before installing them, or check a whole cloned project before its install runs. iris remove removes packages with the project’s package manager.
  • iris secrets: scan the whole project for hardcoded secrets, API keys and tokens. No sign-in needed.
  • iris security: scan the whole project for risky security patterns, such as eval, SQL built from strings, insecure random numbers and weak hashing. No sign-in needed.
  • iris schema: show your database structure, or how the code uses one table. Use --evidence <evidence-id> to read usage from a saved result.
  • iris sbom: export a CycloneDX 1.5 software bill of materials, a list of every package the project uses, without looking anything up online.
  • iris report: export an HTML health report, a PNG or SVG card, or a PDF with --format.
  • iris config init / iris config validate: create .irisconfig.json from a preset by answering questions, or check an existing one.
  • iris hook git status / iris hook build status: show whether the Git pre-push hook and the build hook are installed.
  • iris hook agent install|uninstall|status: add the package guard hook for Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI or Windsurf.
  • iris slack setup|test|manifest: set up and test Slack notifications sent directly from your own CI.
  • iris rules: write this project’s thresholds, taken from .irisconfig.json, into the file your coding agent already reads.
  • iris mcp: let a coding agent call Iris Code tools over MCP. Basic tools are Free, project scans and saved results use your project access, and fresh enforcement needs paid access.
  • iris auth login|status|logout: sign in, check your sign-in or sign out.

Project inspection and enforcement

Some commands look at a whole project. An inspection scans and reports; it can use your Free allowance, the monthly amount of project scans your account can run. Enforcement fails a check so a push, build or pipeline stops, and it needs paid access. The commands below include both kinds. Choose an inspection, or read a saved result, when you do not want to start enforcement:
  • iris check <dir> --inspect: scan a directory using your project access, without running paid enforcement.
  • iris check --staged --inspect: inspect only the files you have staged with git add.
  • iris check --changed --inspect: inspect the files changed since the last commit.
  • iris deps: check npm, Go, Python, RubyGems, NuGet, Cargo and Maven or Gradle dependencies for outdated versions and known CVEs (published security advisories), using the installed versions in your lockfile.
  • iris cve: a CVE check for CI. It exits 1 only when it finds an advisory at or above the severity you choose.
  • iris todos: list every TODO, FIXME and HACK comment in the project.
  • iris gate: the CI gate. It exits 1 when the project misses minHealthScore or any configured gateMax* limit (see gate rules).
  • iris graph without --focus: the whole import graph as text or JSON.
  • iris hook git|build install|uninstall: install or remove the Git pre-push and build hooks.
  • iris hook verify: in CI, warn when a pushed commit has no pre-push hook record for a Team project. It always exits 0.

Next steps

Authentication

Sign in through your browser, or set up a licence token for automated CI runners.

Commands

Full reference for Iris Code CLI commands, flags and exit codes.

CI Integration

Use iris gate as the gate in GitHub Actions, GitLab CI or any shell pipeline.

GitHub Actions

Full workflow guide, including branch protection rules and threshold configuration.