Skip to main content
These are the commands you type in a terminal to use Iris Code. They set a project up, scan code, check packages and decide whether a project meets its standards. Anything marked Pro needs a licence. The other commands are Free: most work without an account, and the ones that scan a whole project use the monthly allowance that comes with a free sign-in. Each command below starts with what it is for and when you would use it, followed by its options and exit codes.

Common tasks

Understanding command results

Every command returns a number when it finishes, called an exit code. A script, Git hook or CI pipeline reads it to decide whether to carry on. Each command’s table below lists its own codes. Any command can also return 3. It means the command did not run because Iris Code could not confirm access: your licence could not be checked (the licence server could not be reached or is limiting repeated requests), you need to sign in, your monthly allowance is used up, or an interrupted operation needs review first. The command stops rather than skipping and reporting a success it has not earned. iris deps and iris cve return 4 when network lookups are turned off or you declined them, so a pipeline can tell “nothing was checked” apart from 1, “problems found”. Having no Pro licence is a different case. That is known, so those commands skip and exit 0. Some commands scan a whole project. On Free, each fresh project scan uses one action from your monthly allowance; Pro removes that monthly limit. This page calls either of these your project access. A scan’s result is saved with an ID, called an evidence ID, and --evidence <evidence-id> opens it again without a new scan. See Free allowances. iris init sets a project up. After that, iris check gives a score, and iris gate checks it in CI and fails the run when it falls short.

iris init

Sets Iris Code up in a project in one step. Run it once when you start using Iris Code in a repository. It asks a few short questions, recommends a preset (a ready-made set of thresholds) and writes .irisconfig.json. It also installs the pre-push hook, a check that runs before git push, where the licence allows it, offers the package guard for coding agents, and creates or refreshes the AGENTS.md rules block. Free, except the Git hook step, which is Pro and is reported as skipped rather than failing the run.
The questions cover what kind of project this is, what matters most right now, and whether Iris Code should block a 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. You can always choose another preset from the list instead. A further question asks what a push check should judge. The recommended answer, Only what the push changes, writes "gateScope": "changes": code you do not touch never blocks a push, and a file you edit blocks only if you make it worse. Every file, every time writes "all". The git hook page explains the rules. The package guard question defaults to yes when the project already shows a coding agent in use, such as a CLAUDE.md file or a .cursor/ folder. With --yes, the guard is added only in that case. Each step reports what it did:
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 other steps or fail the command.

iris fix

Removes findings Iris Code can prove are safe to remove, such as a leftover debug statement or an unused variable. Use it to clear this kind of clutter from a file without editing it by hand. Free for a single file. It shows a preview by default and never writes without confirmation.
Five kinds of fix qualify, and each can span several lines: Anything else is refused. Refusals are reported for each finding rather than for the whole run, so one finding that cannot be fixed does not stop the ones that can. A hardcoded secret is never fixed automatically. The value has to move to the environment and the credential has to be replaced, and a fixer can do neither. A debug statement sharing its line with real code is left alone, because deleting the line would take the code with it. The fixer also refuses whenever removing something could change what the program does or leave it incomplete:
  • console.error is never removed, because it reports real errors.
  • A debug statement is kept if its arguments could do work, such as assigning a value, incrementing a counter, using await or calling something other than a simple formatter.
  • It is also kept if it is the whole body of an if, else, loop or arrow function, or the last expression of a Ruby method.
  • A removal is refused if it would leave a Go import or variable unused, or a Python block empty.
  • A Python class attribute or module variable, a Go package variable, and a top-level variable in a JavaScript or TypeScript file without imports or exports are kept, because other code can read them. Unused literal-only function locals and eligible module variables can be removed.
  • A TypeScript value import whose names are all unused is kept, because whether the module still loads depends on verbatimModuleSyntax. JavaScript keeps the load as import './a'.
  • Imports in Vue and Svelte components are not removed, because the template can use a name the script check cannot see.
  • Type-only TypeScript imports are not merged, and nor are Rust use statements that carry an attribute or doc comment.
The same fixes are offered as a Quick Fix in VS Code, through Apply mechanical fixes in the refactor playbook, and through iris_fix_safe on the MCP server. All of them use the same rules, so they agree on what is safe.

iris refactor

Prints a refactor plan for one file. Use it when a file is too long or too complex and you want a concrete next step for yourself, a reviewer or a coding agent. The plan lists the conventions the repository already follows, the mechanical fixes above, and ranked suggestions for restructuring the file, each with its evidence, risk and where the code would move. Free. The plan only reads your code; nothing is written.
Verifying one file without --baseline compares it with git HEAD, your last commit, including any uncommitted changes you already had. A plan for several files saves a private baseline: a snapshot of the files when you planned, kept between CLI runs. Pass its returned ID with --verify --baseline <baseline-id> to verify that same piece of work without using another project action. For a multi-file plan, run iris refactor ./src --format json and keep its baseline_id. Verify with iris refactor ./src --verify --baseline <baseline-id>. The MCP server and Verify refactor in the editor also keep the planned baseline. See verifying a refactor. Verification only reports: a regressed verdict does not change the exit code.

iris graph

Prints the import graph, the map of which files use code from which other files, that Code Map draws in the editor. Use --focus before changing a file to see what it depends on and what depends on it. Showing one focused file is Free. A fresh graph of the whole project uses your project access. --evidence <evidence-id> reads a saved graph without scanning again.
It reads TypeScript, JavaScript, Vue, Svelte, Go, Python, Java, C# and Rust. It works out where each import points in the same way as the editor and skips the same ignoreFiles. An import Iris Code cannot trace to a file 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.

iris schema

Prints the Schema graph: your database tables, their columns and how they link, using the table and column names read from their declarations in your project. Use it to see your data model, or add --usage to see where the code uses a table. The structure, and usage for one focused table, are Free. Usage across all tables can come from a saved result with --evidence <evidence-id>; otherwise a fresh project scan uses your project access.
JSON carries schemaVersion: 1. References Iris Code could not resolve, disagreements between sources and statements it did not read are reported for information only, so a successful run exits 0. Invalid arguments, or a table that is unknown or matches more than one name, exit 2. A build error exits 1. Use --evidence <evidence-id> to read usage across all tables from a result you own without scanning again. Without an evidence ID or --table, the command checks your project access before starting a fresh scan.

iris check

Scores source files and prints their findings. Use it on one file while you work, or on a folder to see how a whole area of the project stands. Checking a single file is Free. iris check . --inspect runs a one-off scan of the project using your project access. Using a directory, staged files or changed files as enforcement, a check that fails so the next step stops, still needs paid access. An inspection does not install or run a blocking hook. Findings silenced by inline suppressions (// iris-ignore: <ruleId> -- <reason>) do not count against the score. The number suppressed always appears in the output, --show-suppressed lists each one, and JSON reports include a suppressed array for each file. Directory checks also find duplicate code blocks across files, and each JSON file entry includes a duplicateBlocks array. Files left out of the duplicate comparison, because they are too large or look minified, are listed in the output rather than skipped silently.

iris secrets

Scans the project for credentials written into the code, such as API keys, tokens and passwords. Run it before you push, or in CI, so a secret is caught before it is shared. Free - no authentication required.
--history finds secrets that were committed and later removed. Every file version added by each commit, committed .env files included, goes through the same two-layer detection as your current files. Each distinct secret is reported once and always masked. The report shows when it was first and last seen, the commits and files involved, and whether the secret is still in your latest commit (HEAD). Merge commits are covered. Limits on what was checked, such as the depth, size caps and shallow clones (copies made without the full history), are always shown, so a clean result never suggests the whole history was checked when it was not. Everything runs against your local Git history; nothing leaves the machine. The real fix is to replace the credential: a secret that reached history should be rotated even if it was later removed.

iris security

Scans the project for nine risky coding patterns that often lead to security problems. Use it alongside iris secrets to catch them before they ship. Free - no authentication required. The patterns are:
  • eval or exec usage, which runs text as code
  • SQL built by joining strings together
  • insecure random number generation
  • regular expressions that can be made to run extremely slowly (ReDoS)
  • hardcoded localhost URLs
  • disabled TLS certificate checks
  • debug flags left switched on
  • weak hashing (MD5 or SHA-1)
  • open redirects
See Security Smells for the full pattern reference.

iris deps

Checks the packages your project depends on for newer versions and known CVEs, the published security advisories in the OSV.dev database. Use it to see what needs updating and what has a known vulnerability. It covers npm, Go, Python, RubyGems, NuGet, Cargo and Maven or Gradle projects. Nested Go, Python and Ruby projects in a monorepo are read too, and each of their packages is tagged with its folder. A fresh audit you choose to run uses one project action when it succeeds. A saved audit that is still valid, with nothing changed, can be reused; --no-cache asks for fresh results instead. Opening saved data does not look anything up again. When your project has a lockfile, the installed versions are read from it, for example package-lock.json v1-v3, pnpm-lock.yaml, yarn.lock classic and Berry, bun.lock, poetry.lock, Pipfile.lock, uv.lock, Gemfile.lock, packages.lock.json and Cargo.lock. The audit then reflects what is actually installed rather than the range in the manifest, and advisories are matched to that installed version. Monorepo workspace members (npm and yarn workspaces, pnpm-workspace.yaml) are found and counted once automatically, and internal workspace: / file: / link: dependencies are left out.
The first lookup over the network asks for your permission and shows exactly what is sent: package names and versions, nothing else. Your choice is saved in ~/.iris/preferences.json. Run with --revoke-network to turn lookups off later, or --allow-network to turn them back on. Once lookups have been turned off, --allow-network asks you to confirm and only works in a terminal, so a script or a coding agent cannot turn them back on for you; the command exits 4 instead. When results come from the 24-hour cache, the output shows how old the cached scan is. No token or rate-limit setup is needed. OSV.dev lookups need no account, 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) and, where one exists, the version that fixes it. Advisories without a verifiable ID or severity are never shown. They are left out, and the output says how many were skipped. A dependency whose lookup failed is marked “not checked”, never assumed clean.

iris cve

Pro. Runs the same dependency and CVE scan as iris deps, sharing its 24-hour cache and network permission, but exits 1 only when it finds a vulnerability at or above the --severity level. This is the command for a CI gate: it can block merges on high or critical advisories without failing the pipeline over minor ones. Each matched advisory shows its confidence label (fix-available, direct, transitive, or manual-review) and, where one exists, the version that fixes it.
A package reported in the OpenSSF malicious-packages feed fails the run at every --severity level and is listed under its own MALICIOUS heading. Those reports carry no severity score of their own, so without this rule they would rank 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. Use it in place of your usual install command when you want a package checked first. It checks for known vulnerabilities, malicious-package reports, yanked, deprecated and prerelease versions, and brand-new releases. 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.

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. It saves you remembering each package manager’s remove command. 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.
If the package manager itself fails, its exit code is passed through.

iris sbom

Free. Exports a software bill of materials (SBOM): a list of every package your project uses, in the CycloneDX 1.5 format that security and compliance tools read. It covers npm, Go, Python, RubyGems, NuGet, Cargo and Maven manifests in the project. Exporting from your manifests looks nothing up in a registry or advisory database, so it does not ask for network permission. When it reuses a saved audit that belongs to your account, it checks online that the audit is yours; a saved result already confirmed as yours can also be read offline. Each component carries the package name, the exact installed version (read from the lockfile), a purl (a standard package identifier), and a required or optional scope depending on whether the dependency is direct or for development only. If a cached iris deps scan exists, its known vulnerabilities are added as CycloneDX vulnerabilities entries, linked to each package by its 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 leaves out a dependency is worse than one that admits it does not know the version. They carry a purl without a version, such as pkg:nuget/CsvHelper, no version field, and an iris:version-unresolved property naming the reason. A purl with an invented version would look valid, so a scanner reading it would fail to match the package without reporting a problem.

iris todos

Lists every TODO, FIXME and HACK comment across the project, so you can see the unfinished work people have left notes about. Use --evidence <evidence-id> to read a saved result without scanning again; a fresh scan uses your project access. This command only reports: it does not check any threshold.

iris gate

Pro. Checks the project against every threshold configured in .irisconfig.json, including gateMaxNamingViolations, and shows each threshold beside its actual value with a PASS or FAIL. This is the recommended command for CI, because it exits 1 when any rule fails and so stops the pipeline. There is no command-line flag to override thresholds; set them in .irisconfig.json. With "gateScope": "changes", the gate judges only what the branch changed: each changed file is compared with its version at --from <revision>, or at the point where the branch left its upstream. Untouched files cannot fail it. A CI checkout often has no upstream branch, or already sits at it on a push event, so pass --from with the base of the pull request or the commit before the push. Without an earlier commit to compare with, the gate judges every file and prints a note saying so, rather than passing a change it never compared. Findings silenced by inline suppressions (// iris-ignore: <ruleId> -- <reason>) do not count against gate rules, but the number suppressed always appears in the output. Set gateMaxSuppressions to cap suppressions per file, or ignoreSuppressions: true to ignore every suppression comment so suppressed findings count again.

iris slack

Sets up and tests Slack notifications, so the result of iris check or iris gate is posted to a channel your team reads. The command is Free. Iris Code reads the webhook (the address Slack gives you for posting messages) only from IRIS_SLACK_WEBHOOK, and sends messages directly from your machine or CI. The complete setup, what each message contains and how the webhook is handled are covered in Slack notifications.

iris rules

Writes this project’s configured thresholds, taken from .irisconfig.json, into the file your coding agent already reads, so the agent knows your limits before it writes code. Free. Nothing is analysed, nothing is sent anywhere, and no model is involved. A project using two agents may need two files. Claude Code reads only CLAUDE.md, while AGENTS.md is the default shared target, and Cursor and Copilot have their own target files too. Each file is written separately, so one damaged file is reported and skipped while the rest still update. The rules go 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 an MCP server. MCP is a connection that lets a coding agent call tools, so the agent can check files and read your project’s rules itself while it works. The server talks to the agent over standard input and output. Basic file checks, configuration, one-file fixes and plans, focused schema information and the package guard are Free. Fresh project scans, dependency audits and multi-file plans use your project access; reading a result you already earned does not use it again. Fresh enforcement still needs paid access. See MCP tools.
Leave out --root unless you specifically need the folder pinned. Passing it stops Iris Code asking your editor, so a single pinned setup 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 a fix needs before it is written, and the limits on response size are in MCP server.

iris report

Exports a report of a scan that you can share with people who do not use Iris Code. It writes HTML by default, or a PNG or SVG card, or selected PDF pages. --evidence <evidence-id> exports a saved result you own without scanning your current files. Existing anonymous introductory cards and PDFs remain readable. A fresh directory scan uses your project access; an HTML report for a single file stays Free. The PDF page IDs, in output order, are summary, findings, areas, standard, trend and dependencies.
  • Summary is always included.
  • Full includes the first four sections, plus the trend when it is available. Dependencies is only included when you ask for it.
  • Standard continuation pages keep their section number.
  • Trend needs more than one saved scan, and Dependencies needs a saved dependency audit.
Full writes iris-report.pdf, Summary writes iris-report-summary.pdf, and Custom writes iris-report-custom.pdf unless you use --output. Cards are named by size, such as iris-report-portrait.png. A page you list in --pages that the scan cannot provide prints Left out <id>: <reason> to stderr, and the export still exits 0 if it succeeds. Full includes the score trend only when there is saved history, and prints no notice when it leaves it out. An unknown page ID, or --pages with HTML, PNG or SVG, exits 2.

iris hook

Installs and removes two checks that run automatically: the Git pre-push hook, which runs before each git push, and the build hook, which runs as part of your project’s build. These do the same as the hook commands in the VS Code command palette. It also manages the package guard hook for coding agents. The type (git, build or agent) comes before the action. status and uninstall are Free, including after a licence expires or while offline. Installing a Git or build hook that blocks needs paid access for the selected project. The active pre-push hook is .git/hooks/pre-push, unless Git’s core.hooksPath setting points elsewhere. With Husky, the block goes in .husky/pre-push rather than Husky’s generated files. iris hook agent takes these options:
  • --target with claude, cursor, codex, copilot, gemini, windsurf, a comma-separated list of them, or all. Without it, install picks the agents the project already shows signs of, or Claude Code.
  • --yes to skip the confirmation when a settings file already exists.
  • --dry-run.
  • --verify-on-finish, which adds the optional finish verification hook for every agent except Windsurf.

iris auth

Signs you in, shows your sign-in status and signs you out. Signing in lets the CLI use your Pro licence. Every subcommand asks its questions interactively. There is no flag to pass a token directly on the command line; on CI runners, use the IRIS_LICENCE_TOKEN environment variable instead. See the Authentication page for the full guide.

iris config

Creates or checks .irisconfig.json, the file that holds your project’s thresholds. Use init to create one from a preset, and validate to find mistakes in one you have edited.

iris hook verify

Pro. Run in CI for a Team project, it checks the Team’s records for a passing pre-push hook run on a pushed commit. Formats: pretty, json, github. --sha is optional on supported CI providers. When there is no record, it warns and tries to write a Push with no hook record entry. Unlike the other Pro commands, it always exits 0, including for a missing licence, invalid arguments and network failures. See Team governance for how the commit is found and every reason a check can be skipped.

iris usage

Shows your account’s or team’s allowance and the results saved on this machine. It does not start a scan.
recover matches recorded actions with their outcomes, and leaves any whose outcome is still unknown waiting for confirmation. See Free allowances for offline access and the commands for saved results. A result opened with --evidence keeps the project folder and configuration it was scanned with. If you also give a path, it must match that folder; leave the path out to read a result from another working directory. With a saved graph, a --focus path is looked up inside the saved project folder.

Verification integrity

iris check . --integrity checks whether your current changes weaken your tests or rules, such as a deleted or skipped test or a lowered threshold, compared with your last commit. It is Free.
  • --from <revision> compares with another branch or commit instead.
  • --staged compares exactly what you have staged with git add against your last commit.
  • --from and --staged cannot be used together.
  • --format json adds an integrity report with the findings, how many block, and anything that could not be checked.
A blocking finding exits 1, a clean comparison exits 0 and a bad flag exits 2. Score scans keep their usual access requirements. iris gate . --from <revision> also checks for weakened tests and rules against that revision before it checks scores. See verification integrity.