Iris Code CLI Command Reference

Twenty commands cover setup, code checks, safe fixes, the import graph, dependency audits, CVE gating, SBOM export, project rules, MCP, enforcement, reporting, authentication, and hooks. Anything marked Pro needs a licence; the rest work without an account. Every Pro command shares one extra exit code. If a licence exists but could not be verified - the licence server unreachable, or rate limiting a repeated caller - the command exits 3 and does not run, rather than skipping and reporting success it has not earned. Having no Pro licence is a different case: that is known, so those commands skip and exit 0. The per-command tables below list each command’s own codes. iris init sets a project up. After that, iris check gives a score and iris gate enforces one in CI.

iris init

Sets up a project: asks three short questions, recommends a preset, writes .irisconfig.json, creates or refreshes the AGENTS.md rules block, and installs the pre-push hook where the licence allows it. Free, except the hook step, which is Pro and is reported as skipped rather than failing the run.

Flag	Description
`[path]`	Directory to set up (defaults to current directory)
`--yes`, `-y`	Take the Balanced preset without prompting. Also the behaviour when there is no terminal to ask at

npx -y @iris-code/cli init

The questions cover what kind of project this is, what matters most right now, and whether Iris Code should enforce before push or only report. The answers map to one of the shipped presets, and the recommendation is shown with its reason before anything is written. Choosing another preset from the list is always offered. Each step reports what it did:

Iris Code setup
  config: created .irisconfig.json with the Balanced preset
  git hook: skipped - Pro installs the pre-push gate; run `iris hook git install` after upgrading
  agent rules: created or refreshed Iris Code blocks

Running it again is safe. An existing .irisconfig.json is left alone rather than overwritten, and existing rules files have only their Iris Code block refreshed. A step that cannot complete is reported and skipped; it does not stop the rest or fail the command.

iris fix

Removes findings Iris Code can prove are safe to remove. Free for a single file. Previews by default and never writes without confirmation.

Flag	Description
`--safe <file>`	Required. Restricts the command to deterministic removals
`--apply`	Write the changes. Asks for confirmation first
`--yes`, `-y`	Answer that confirmation in advance. Required when there is no terminal to ask at

# See what would be removed
iris fix --safe src/auth.ts

# Remove it, after confirming
iris fix --safe src/auth.ts --apply

Three cases qualify:

Case	Example
A line holding nothing but a debug statement	`console.log("debug")`
A variable that is unused and assigned a literal	`const unused = 1`
A standalone unused Java import	`import java.util.List;`

Everything else refuses, and refusals are reported per finding rather than per run, so one unfixable finding does not stop the provable ones. A hardcoded secret is never auto-fixed: the value has to move to the environment and the credential has to be rotated, neither of which a fixer can do. A debug statement sharing its line with real code is left alone, because deleting the line would take the code with it. The same three cases are offered as a Quick Fix in VS Code and through iris_fix_safe on the MCP server. All three share one planner, so they agree on what is safe.

iris graph

Prints the import graph that the Code Map draws, as text or JSON. It exists so an agent or a CI job can read the same edges, cycles and unresolved imports you see in the editor, without opening one. Free for one file with --focus; the whole graph requires Pro.

Flag	Description
`--root <dir>`	Project root (defaults to current directory)
`--focus <file>`	One file: what it imports and what imports it (Free). Without it, the whole graph (Pro)
`--format <fmt>`	`text` (default) or `json`
`--include-external`	With `--focus`, also list packages and built-in modules

# One file's imports and importers (free)
iris graph --focus src/app.ts

# The whole graph as JSON, for an agent or CI (Pro)
iris graph --format json

It reads TypeScript, JavaScript, Vue, Svelte, Go, Python, Java, C# and Rust, with the same resolver and the same ignoreFiles as the editor. An import Iris Code cannot resolve is listed with its reason, for example missing-file or ambiguous-target, and is never guessed at. Go and Java packages and C# namespaces appear as their folders, because that is what those imports name. An import graph only shows imports. Files in the same Go or Java package, C# namespace or Rust module can use each other without one, so those uses do not appear, and the text output says so when the project has such files. The JSON carries schemaVersion: 1. The whole graph is { schemaVersion, root, graph }; with --focus it is { schemaVersion, root, focus, view, unresolved }, and unresolved holds only that file’s entries.

Exit code	Meaning
`0`	Graph printed, whether or not some imports were unresolved
`1`	The graph could not be built
`2`	Bad arguments, a `--focus` file outside the root, or a file the graph does not read

iris check

Scores source files and prints health findings. Single-file scans are free; scanning a directory or using --staged / --changed requires Pro.

Flag	Description
`[path]`	File or directory to scan (defaults to current directory)
`--staged`	Scan staged git files only (Pro)
`--changed`	Scan files changed since the last commit (Pro)
`--min-score <n>`	Minimum health score 0–100; overrides `.irisconfig.json`
`--config <path>`	Use a specific `.irisconfig.json`
`--format <fmt>`	Output format: `pretty` (default), `json`, or `github`
`--output <path>`	Write JSON result to file (requires `--format json`)
`--verbose`	Show individual findings per file
`--show-suppressed`	List each finding suppressed by an `iris-ignore` comment, with its reason
`--slack-on <when>`	`failure` (default) or `always`
`--slack-dry-run`	Print the Slack payload instead of posting it

Findings silenced by inline suppressions (// iris-ignore: <ruleId> -- <reason>) do not count against the score, but the suppressed count always appears in the output; --show-suppressed lists each one individually. JSON reports include a per-file suppressed array. Directory checks also find duplicate code blocks across files; JSON file entries carry an additive duplicateBlocks array, and files excluded from duplicate comparison (too large or minified-looking) are disclosed rather than silently skipped.

# Score a single file (free)
iris check src/index.ts

# Score a directory with a custom threshold (Pro)
iris check src/ --min-score 80

# Score staged files only (Pro)
iris check --staged

Exit code	Meaning
`0`	All files at or above threshold
`1`	One or more files below threshold
`2`	Bad arguments or config error

iris secrets

Scans the project for hardcoded credentials, API keys, tokens, and passwords. Free - no authentication required.

Flag	Description
`[path]`	File or directory to scan (defaults to current directory)
`--history`	Scan the git commit history instead of the working tree (Pro)
`--depth <n>`	With `--history`: commits to walk (default `50`; `0` = full history)
`--format <fmt>`	Output format: `pretty` (default) or `json`
`--output <path>`	Write JSON result to file (requires `--format json`)

# Scan the current directory
iris secrets

# Scan a specific path and output JSON
iris secrets ./src --format json

# Scan the last 50 commits of git history (Pro)
iris secrets --history

# Scan the full history
iris secrets --history --depth 0

--history finds secrets that were committed and later removed: every file version introduced by each commit (committed .env files included) runs through the same two-layer detection. Findings are deduplicated per distinct secret, always masked, and show first/last sighting, the commits and files involved, and whether the secret is still in HEAD. Merge-commit content is covered, and coverage limits - depth, size caps, shallow clones - are always disclosed rather than implying a clean full history. Everything runs against local git; nothing leaves the machine. Rotation is the real fix: a secret that reached history should be rotated even if it was removed later.

Exit code	Meaning
`0`	No secrets found
`1`	Secrets found (working tree, or anywhere in the scanned history range)
`2`	Bad arguments

iris security

Scans the project for nine security anti-patterns: eval/exec usage, SQL built by string concatenation, insecure RNG, ReDoS-prone regex, hardcoded localhost URLs, disabled TLS verification, debug flags, weak hashing (MD5/SHA-1), and open redirects. See Security Smells for the full pattern reference. Free - no authentication required.

Flag	Description
`[path]`	File or directory to scan (defaults to current directory)
`--format <fmt>`	Output format: `pretty` (default) or `json`
`--output <path>`	Write JSON result to file (requires `--format json`)

# Scan the current directory
iris security

# Scan a specific path and output JSON
iris security ./src --format json

Exit code	Meaning
`0`	No security smells found
`1`	Security smells found
`2`	Bad arguments

iris deps

Pro. Audits dependencies in package.json, go.mod, requirements.txt, or pyproject.toml for outdated versions and known CVEs via the OSV.dev database. Installed versions are resolved from your lockfile when one is present (package-lock.json v1-v3, pnpm-lock.yaml, yarn.lock classic and Berry, poetry.lock, Pipfile.lock), so the audit reflects what is actually installed rather than the manifest range, and advisories are filtered to that installed version. Monorepo workspace members (npm and yarn workspaces, pnpm-workspace.yaml) are discovered and deduplicated automatically, and internal workspace: / file: / link: dependencies are excluded.

Flag	Description
`[path]`	Directory to scan (defaults to current directory)
`--no-cache`	Skip the 24-hour local cache and re-fetch
`--verbose`	Show individual CVE titles and URLs
`--format <fmt>`	Output format: `pretty` (default) or `json`
`--output <path>`	Write JSON result to file (requires `--format json`)
`--allow-network`	Re-enable network lookups after a revoke
`--revoke-network`	Disable version and advisory lookups

# Audit dependencies in the current project
iris deps

# Bypass the cache and output JSON
iris deps --no-cache --format json

The first network lookup asks for consent and discloses exactly what is sent: package names and versions, nothing else. Your choice is persisted in ~/.iris/preferences.json. Run with --revoke-network to disable lookups later, or --allow-network to re-enable them. When results come from the 24-hour cache, the output prints the age of the cached scan. No token or rate-limit setup is needed - OSV.dev lookups are unauthenticated and only the package name, ecosystem, and version are sent. Each advisory in the output carries a confidence label (fix-available, direct, transitive, or manual-review) plus the fixed-in version where one exists. Advisories without a verifiable id or severity are never shown - they are dropped and the skip count is disclosed in the output. Dependencies whose lookup errored are marked “not checked”, never assumed clean.

Exit code	Meaning
`0`	No vulnerabilities found
`1`	One or more vulnerabilities detected
`2`	Invalid arguments or no manifest found

iris cve

Pro. Runs the same dependency and CVE scan as iris deps (sharing its 24-hour cache and network consent), but exits 1 only when a vulnerability at or above the --severity threshold is found. This is the command to use for CI gates: block merges on high or critical advisories without failing the pipeline on low-severity noise. Each matched advisory row shows its confidence label (fix-available, direct, transitive, or manual-review) and the fixed-in version where one exists.

Flag	Description
`[path]`	Directory to scan (defaults to current directory)
`--severity <lvl>`	Minimum severity that fails the run: `low`, `medium`, `high` (default), or `critical`
`--no-cache`	Skip the 24-hour local cache and re-fetch
`--format <fmt>`	Output format: `pretty` (default) or `json`
`--output <path>`	Write JSON result to file (requires `--format json`)
`--allow-network`	Re-enable network lookups after a revoke
`--revoke-network`	Disable version and advisory lookups

# Fail on high or critical advisories (default threshold)
iris cve

# Gate on critical advisories only
iris cve --severity critical

# Include everything, down to low severity
iris cve --severity low

Exit code	Meaning
`0`	No CVEs at or above the threshold
`1`	One or more CVEs at or above the threshold
`2`	Invalid arguments or no manifest found

A package reported in the OpenSSF malicious-packages feed fails the run at every --severity threshold and is listed under its own MALICIOUS heading. Those reports carry no severity score of their own, so without this rule they ranked below low.

iris install

Free. Checks each package before it is installed, then installs it with the project’s own package manager, found from its lockfile. Known vulnerabilities, malicious-package reports, yanked, deprecated and prerelease versions, and brand-new releases are all checked. See the package guard for what each verdict means. With no package names it checks the whole project first: every package the lockfile would install, and the repository’s own install scripts, which it shows and asks about before running the install. This is the check to run on a repository you have cloned and do not yet trust. See Installing a whole project. iris add and iris i are other names for the same command.

Flag	Description
`<package[@version]...>`	One or more packages, with an optional version, range or tag. Omit to check and install the whole project
`--ignore-scripts`	Whole project: install without running the project’s own install scripts
`--yes`, `-y`	Whole project: run the project’s install scripts without asking
`-r`, `--requirement <file>`	Whole project, pip and uv: the requirements file to install
`--manager <name>`	Use this package manager instead of the detected one
`--check`	Check only; install nothing
`--force`	Install even when a package is blocked, printing what was overridden
`--format json`	Print the verdicts as JSON, with every advisory
`--verbose`	List every known vulnerability, with links. Otherwise the five worst are shown and the rest counted
`--no-cache`	Ignore the local package cache
`--allow-network` / `--revoke-network`	Turn network lookups on or off

iris install lodash@4.17.20
iris install requests --check
iris install                  # the whole project
iris install --check          # the whole project, install nothing

Exit code	Meaning
`0`	Installed, or clean with `--check`
`1`	Blocked; nothing was installed
`2`	Invalid arguments or no package manager found

iris remove

Free. Removes packages with the project’s own package manager: npm uninstall, pip uninstall, cargo remove, bundle remove, dotnet remove package, go get <module>@none and so on. Nothing is checked, because removing a package is never the risk the guard is for. A version is ignored, so the spec you passed to iris install works as it is. iris uninstall and iris rm do the same.

Flag	Description
`<package...>`	One or more packages
`--manager <name>`	Use this package manager instead of the detected one
`--dry-run`	Print the command without running it

iris remove lodash
iris rm requests==2.19.0

The package manager’s own exit code is passed through. If the package manager itself fails, its exit code is passed through.

iris sbom

Pro. Exports a CycloneDX 1.5 software bill of materials covering npm, Go, Python, RubyGems, NuGet, Cargo, and Maven manifests in the project. The command is fully offline: no network requests are made and no consent prompt appears. Each component carries the package name, the exact installed version (lockfile-resolved), a purl, and a required or optional scope depending on whether the dependency is direct or dev-only. If a cached iris deps scan exists, known vulnerabilities are folded in as CycloneDX vulnerabilities entries cross-referenced by purl. Some dependencies have no version to report: a NuGet PackageReference with no version and no Central Package Management entry, or two projects pinning different versions of the same package. Those components are still listed, because an SBOM that quietly omits a dependency is worse than one that admits it does not know the version. They carry a version-less purl such as pkg:nuget/CsvHelper, no version field, and an iris:version-unresolved property naming the reason. A purl with an invented version would be well-formed, so a scanner reading it would fail to match the package without reporting a problem.

Flag	Description
`[path]`	Directory to scan (defaults to current directory)
`--output <path>`	Output file path (default: `./iris-sbom.json`)
`--stdout`	Print the SBOM to stdout instead of writing a file

# Write iris-sbom.json in the current directory
iris sbom

# Print the SBOM to stdout for piping into other tools
iris sbom --stdout

Exit code	Meaning
`0`	SBOM generated successfully
`2`	Invalid arguments or no manifest found

iris todos

Pro. Lists every TODO, FIXME, and HACK comment found across the project. This command is informational - it does not fail the run based on findings.

Flag	Description
`[path]`	File or directory to scan (defaults to current directory)
`--format <fmt>`	Output format: `pretty` (default) or `json`
`--output <path>`	Write JSON result to file (requires `--format json`)

# List all TODO/FIXME/HACK comments in the project
iris todos

# Scan a specific path and output JSON
iris todos ./src --format json

Exit code	Meaning
`0`	Success (regardless of findings)
`2`	Bad arguments

iris gate

Pro. Runs the full enforcement gate - every threshold configured in .irisconfig.json, including gateMaxNamingViolations - and shows each threshold against its actual value, with a PASS or FAIL for each. This is the recommended command for CI. There is no CLI flag to override thresholds; set them in .irisconfig.json. Findings silenced by inline suppressions (// iris-ignore: <ruleId> -- <reason>) do not count against gate rules, but the suppressed count always appears in the output. Set gateMaxSuppressions to cap suppressions per file, or ignoreSuppressions: true to make all directives inert so suppressed findings count as live.

Flag	Description
`[path]`	File or directory to scan (defaults to current directory)
`--config <path>`	Use a specific `.irisconfig.json`
`--format <fmt>`	Output format: `pretty` (default), `json`, or `github`
`--output <path>`	Write JSON result to file (requires `--format json`)
`--show-suppressed`	List each finding suppressed by an `iris-ignore` comment, with its reason
`--slack-on <when>`	`failure` (default) or `always`
`--slack-dry-run`	Print the Slack payload instead of posting it

# Run the gate against the configured thresholds
iris gate

# Emit inline PR annotations in GitHub Actions format
iris gate . --format github

# Post the outcome to a Slack channel from your own CI
IRIS_SLACK_WEBHOOK="$SLACK_WEBHOOK_URL" iris gate .

Exit code	Meaning
`0`	All rules pass
`1`	One or more rules fail
`2`	Bad arguments or config error
`3`	Licence could not be verified, so the gate did not run

iris slack

Sets up and tests Slack notifications for iris check and iris gate. The command is free. Iris Code reads the webhook only from IRIS_SLACK_WEBHOOK and sends messages directly from your machine or CI.

Subcommand	Description
`iris slack setup`	Validate a webhook, send a test message, and show the CI secret configuration
`iris slack test`	Send a test message using `IRIS_SLACK_WEBHOOK`
`iris slack manifest`	Print a link and manifest for creating a pre-configured Slack app

The complete setup, payload contents and credential rules are covered in Slack notifications.

iris rules

Writes this project’s configured thresholds into the file your coding agent reads, generated from .irisconfig.json. Free. Nothing is analysed, nothing is sent anywhere, and no model is involved.

Flag	Description
`--target <name>`	`agents` (default, `AGENTS.md`), `claude`, `cursor`, or `copilot`. May be repeated to write several files
`--all`	Write all four target files
`--refresh`	Update only the target files this repository already has, and create none
`--dry-run`	Print what would be written instead of writing it
`--yes`, `-y`	Do not ask before updating a file that already exists

A project running two agents needs two files: Claude Code reads only CLAUDE.md, while AGENTS.md is what Codex, Cursor and Copilot read. Each file is written independently, so one damaged file is reported and skipped while the rest still update. The block sits between iris-rules markers, so regenerating updates only Iris Code’s own section and never your text. Full behaviour, including what the file contains and what happens to a damaged marker, is in Project rules.

iris mcp

Runs Iris Code as a Model Context Protocol server over standard input and output, so an AI agent can query the project’s real findings, rules and gate status. Free and Pro: single-file iris_check, iris_config and single-file iris_fix_safe are Free; folder and workspace scope, iris_explain, iris_gate and iris_check_dependency are Pro.

Flag	Description
`--root <path>`	Pins the directory the server may read. Every requested path must resolve inside it, symlinks included. Omit it and Iris Code asks your editor which project is open, falling back to the launch directory
`--sdk`	Serve the same tools through the official MCP TypeScript SDK instead of the built-in transport

# Run the server; your editor tells it which project is open
npx -y @iris-code/mcp

# Equivalent, with the CLI already installed
iris mcp

Omit --root unless you specifically need the folder pinned. Passing it stops Iris Code asking your editor, so a single pinned registration shared across several projects answers every one of them about the folder named in the flag. --root . in particular pins nothing: it is the launch directory, which is already the fallback. The server writes only protocol messages to standard output, so it must not be wrapped in a script that prints anything there. Editors bundling the Iris Code language-server binary can use iris-lsp --mcp instead, with no Node.js install. Tool-by-tool behaviour, the preview-token write gate, and the response caps are in MCP server.

iris report

Runs a workspace scan and exports the results as a standalone HTML file. The output mirrors the export produced by the editor extension. Free.

Flag	Description
`[path]`	File or directory to scan (defaults to current directory)
`--output <path>`	Output file path (default: `./iris-report.html`)
`--config <path>`	Use a specific `.irisconfig.json`
`--min-score <n>`	Health score threshold 0–100

# Export a report to the default location
iris report

# Export a report to a custom path
iris report --output ./reports/latest.html

Exit code	Meaning
`0`	Report written successfully
`2`	Bad arguments or could not write the file

iris hook

Installs and removes the git pre-push hook and the build gate hook - equivalent to the VS Code command palette hook commands. The type (git or build) comes before the action. status is free; install and uninstall require Pro.

Subcommand	Description
`iris hook git status [path]`	Show whether the git pre-push hook is installed (free)
`iris hook git install [path]`	Write the Iris Code block to `.git/hooks/pre-push` (Pro)
`iris hook git uninstall [path]`	Remove the Iris Code block from `.git/hooks/pre-push` (Pro)
`iris hook build status [path]`	Show whether the build hook is installed (free)
`iris hook build install [path]`	Wire Iris Code into the project build command (Pro)
`iris hook build uninstall [path]`	Remove the Iris Code build entry (Pro)
`iris hook agent install [path]`	Add the package guard hook for Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI or Windsurf (free)
`iris hook agent uninstall [path]`	Remove the package guard hook (free)
`iris hook agent status [path]`	Show whether the package guard hook is installed (free)

iris hook agent takes --target claude, --target cursor or --target all, --yes to skip the confirmation when a settings file already exists, and --dry-run.

# Check current hook status (free)
iris hook git status

# Install the git pre-push hook
iris hook git install

# Remove the build hook
iris hook build uninstall

Exit code	Meaning
`0`	Success
`2`	Bad arguments, not a git repository, or no project manifest found

iris auth

Manages authentication credentials. Every subcommand is fully interactive - there is no non-interactive flag to pass a token directly on the command line; use the IRIS_LICENCE_TOKEN environment variable instead for CI runners. See the Authentication page for the full guide.

Subcommand	Description
`login`	Interactive prompt: browser-based sign-in or paste a licence token. Requires a TTY.
`status`	Show the current authentication state
`logout`	Remove stored credentials

# Sign in interactively
iris auth login

# Check the current session
iris auth status

iris config

Generates or validates .irisconfig.json.

Subcommand	Flag	Description
`init [path]`	-	Interactively pick a preset (`legacy`, `balanced`, `strict`) and write `.irisconfig.json`. Pro users are also prompted for gate limits. Falls back to a non-interactive `balanced` default when stdin is not a TTY (e.g. in CI).
`validate [path]`	-	Validate an existing `.irisconfig.json` and print any schema or value problems

# Interactively generate a config
iris config init

# Validate an existing config
iris config validate

Exit code	Meaning
`0`	Success / no validation issues
`1`	`validate` found error-severity problems
`2`	Bad arguments, or `init` found an existing file with no TTY to confirm overwrite

Start here

What Iris Code finds

Blocking bad code

Cloud scanning

Teams

Configuration

Working with AI agents

Editors

Reference

Iris Code CLI Command Reference

iris init

iris fix

iris graph

iris check

iris secrets

iris security

iris deps

iris cve

iris install

iris remove

iris sbom

iris todos

iris gate

iris slack

iris rules

iris mcp

iris report

iris hook

iris auth

iris config

​iris init

​iris fix

​iris graph

​iris check

​iris secrets

​iris security

​iris deps

​iris cve

​iris install

​iris remove

​iris sbom

​iris todos

​iris gate

​iris slack

​iris rules

​iris mcp

​iris report

​iris hook

​iris auth

​iris config

iris init

iris fix

iris graph

iris check

iris secrets

iris security

iris deps

iris cve

iris install

iris remove

iris sbom

iris todos

iris gate

iris slack

iris rules

iris mcp

iris report

iris hook

iris auth

iris config