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:
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)
~/.iris/credentials for later commands.3
Scan the current directory
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 theAGENTS.mdrules 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--verifyto 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 removeremoves 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 aseval, 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.jsonfrom 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 withgit 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 exits1only when it finds an advisory at or above the severity you choose.iris todos: list everyTODO,FIXMEandHACKcomment in the project.iris gate: the CI gate. It exits1when the project missesminHealthScoreor any configuredgateMax*limit (see gate rules).iris graphwithout--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 exits0.
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.