@iris-code/cli

Code health enforcement for JS/TS, Vue, Svelte, Go, Python, Ruby, Rails, ERB, C#/.NET, Java, and Rust - in your terminal, CI pipelines, and git hooks.

Install

npm install -g @iris-code/cli

Or download a self-contained binary from iriscode.co/download - no Node.js required.

Updating

npm install -g does not auto-update - if a command is missing (unknown command: sbom) or the CLI crashes on exit, you're on an old global install:

npm install -g @iris-code/cli@latest
iris --version

Authentication

iris auth login     # sign in via browser or paste your licence token
iris auth status    # check what's stored
iris auth logout    # clear credentials

Credentials are stored in ~/.iris/credentials. The CLI also reads:

• IRIS_LICENCE_TOKEN env var - licence key (takes priority over credentials file)

Commands

| Command | Free/Pro | What it does | |---|---|---| | iris check <file> | Free | Health score for a single file | | iris check <directory> | Pro | Health score across all files | | iris check --staged | Pro | Check only git-staged files | | iris check --changed | Pro | Check staged, unstaged, and untracked files | | iris secrets [path] | Free | Scan for hardcoded API keys, tokens, passwords | | iris secrets --history | Pro | Scan the git commit history for secrets, including removed ones | | iris security [path] | Free | Scan for security smells (eval usage, SQL injection, weak hashing, etc.) | | iris deps [path] | Pro | Dependency versions + CVE vulnerabilities | | iris cve [path] | Pro | Fail only on CVEs at or above a severity threshold | | iris sbom [path] | Pro | Export a CycloneDX 1.5 SBOM (offline) | | iris todos [path] | Pro | List all TODO / FIXME / HACK comments | | iris gate [path] | Pro | Run enforcement gate, show pass/fail per rule | | iris slack <setup\|test\|manifest> | Free | Post gate and check results to a Slack channel | | iris report [path] | Free | Generate a standalone HTML scan report | | iris hook git install | Pro | Install pre-push git hook | | iris hook git uninstall | Pro | Remove pre-push git hook | | iris hook git status | Free | Check if git hook is installed | | iris hook build install | Pro | Install pre-build hook | | iris hook build uninstall | Pro | Remove pre-build hook | | iris hook build status | Free | Check if build hook is installed | | iris config init | Free | Generate .irisconfig.json with a preset | | iris config validate | Free | Validate an existing .irisconfig.json |

iris auth login/status/logout (all Free) are covered in Authentication above.

iris check

iris check app/server.ts          # single file (Free)
iris check .                      # full directory scan (Pro)
iris check . --min-score 80       # custom threshold
iris check . --format json        # machine-readable output
iris check . --format json --output iris-report.json
iris check . --verbose            # show individual warnings per file
iris check --staged               # check staged files only (Pro)
iris check --changed              # check staged, unstaged, and untracked files (Pro)
iris check . --show-suppressed    # list findings hidden by iris-ignore comments

Findings suppressed inline with // iris-ignore: <rule> -- <reason> comments are excluded from scores and output; suppressed counts always appear in the summary, and --show-suppressed lists each suppressed finding with its reason.

iris secrets

Scans JS, TS, Vue, Svelte, Go, Python, Ruby, Rails, executable ERB tags, C# source and project files, Java source and .properties files, and Rust for hardcoded secrets - API keys, tokens, passwords. Free, no licence required.

iris secrets .
iris secrets src/ --format json

iris secrets --history (Pro)

The working tree can be clean while a secret still sits in an old commit. --history walks the git commit history and runs every file version introduced by each commit - committed .env files included - through the same detection.

iris secrets --history              # scan the last 50 commits
iris secrets --history --depth 500  # scan the last 500 commits
iris secrets --history --depth 0    # scan the full history

Findings are deduplicated per distinct secret, values are always masked, and each shows its first and last sighting, the commits and files involved, and whether it is still in HEAD or historical-only. Content introduced by merge commits is included. Coverage limits are always disclosed: a depth cap, a size cap ("depth reduced"), or a shallow clone (run git fetch --unshallow for full coverage) each produce an explicit note instead of implying a clean full history. Exits 1 if any secret is found in the scanned range. Everything runs against local git - nothing leaves the machine.

iris security

Scans JS, TS, Vue, Svelte, Go, and Python for 9 security smell categories: eval/exec usage, SQL built by string concatenation, insecure RNG, ReDoS-prone regex, hardcoded localhost URLs, disabled TLS verification, debug flags, weak hashing (MD5/SHA1), and open redirects. Free, no licence required.

iris security .
iris security src/ --format json

iris deps

Checks all dependencies against current registry versions and the OSV.dev vulnerability database for CVEs. Installed versions are resolved from your lockfile (package-lock.json, pnpm-lock.yaml, yarn.lock, poetry.lock, Pipfile.lock, Gemfile.lock, packages.lock.json) when present, and advisories are filtered to the version you actually have. Monorepo workspace members are scanned and deduplicated; internal workspace: deps are excluded. RubyGems and Cargo lockfiles include transitive dependencies; NuGet projects without packages.lock.json, and Maven or Gradle projects, scan declared dependencies only.

iris deps .
iris deps . --no-cache     # bypass the 24-hour local cache
iris deps . --verbose      # show individual CVE titles and URLs

The first run asks consent before contacting registries - only package names and versions are sent, never your code. The answer persists in ~/.iris/preferences.json; use --revoke-network to disable lookups and --allow-network to re-enable.

Advisory lookups need no token or rate-limit setup. Each advisory shows a confidence label (fix-available, direct, transitive, manual-review) and the fixed-in version; records without a verifiable id or severity are skipped and the skip count is disclosed. Dependencies whose lookup errored are marked "not checked", never assumed clean.

iris cve

Same scan and cache as iris deps, but fails only on CVEs at or above a severity threshold - built for CI gates that should block on serious findings without going red over low-severity noise.

iris cve .                        # fail on high or critical (default)
iris cve . --severity critical    # fail only on critical
iris cve . --severity low         # fail on any known CVE
iris cve . --format json --output cve-report.json

iris sbom

Exports a CycloneDX 1.5 SBOM (Software Bill of Materials) covering npm, Go, Python, RubyGems, NuGet, Cargo, and Maven/Gradle dependencies. Fully offline - no network calls, no consent needed.

iris sbom .                       # writes iris-sbom.json
iris sbom . --output sbom.json
iris sbom . --stdout

Each component carries its name, exact installed version, package URL (purl), and direct/dev scope. If a cached iris deps scan exists, known vulnerabilities are folded in as CycloneDX vulnerabilities entries cross-referenced by purl.

iris gate

Runs the full enforcement gate and shows each configured rule's threshold vs actual value:

iris gate .
iris gate . --format json
iris gate . --show-suppressed     # list findings hidden by iris-ignore comments

Gate rules are read from .irisconfig.json: minHealthScore, gateMaxSecrets, gateMaxComplexity, gateMaxFileLength, gateMaxSmellsPerFile, gateMaxSecuritySmells, gateMaxSuppressions (per-file cap on iris-ignore suppressions). Setting ignoreSuppressions: true makes all iris-ignore comments inert so suppressed findings count as live.

Slack notifications

Set one environment variable and the commands you already run post their results to a Slack channel:

export IRIS_SLACK_WEBHOOK="https://hooks.slack.com/services/..."
iris gate .        # posts when the gate fails; silent when it passes

That is the whole integration - no flag, no pipeline change. The message is built and sent from the machine running the command, so it never passes through Iris servers.

iris slack setup      # guided: validates the URL, sends a test message, prints the CI secret to add
iris slack test       # send a test message using IRIS_SLACK_WEBHOOK
iris slack manifest   # one-click link to create a pre-configured Slack app

iris gate . --slack-on always   # also report passing runs
iris gate . --slack-dry-run     # print the payload, post nothing
IRIS_SLACK_WEBHOOK="https://hooks.slack.com/services/..." iris gate .

• The payload contains file paths, scores, rule names and counts. Never source, finding text, or secret values (masked or otherwise).
• Only https://hooks.slack.com/... URLs are accepted. The webhook is environment-only: it is never read from .irisconfig.json or accepted as a command-line argument, because both can expose a posting credential.
• A failed post writes one warning to stderr and never changes the exit code.

Full guide.

iris report

Generates a dark-themed standalone HTML report.

iris report .
iris report . --output reports/iris-$(date +%Y%m%d).html

iris hook

Manages pre-push and pre-build hooks - same as the VS Code commands but scriptable.

iris hook git install              # install pre-push hook
iris hook git status               # check status (Free)
iris hook build install            # install pre-build hook (Node: package.json prebuild; Go/Python: Makefile)
iris hook build status             # check status (Free)

After installing a hook, Iris Code needs your licence token at push/build time. Set IRIS_LICENCE_TOKEN in your shell profile or run iris auth login once to store it in ~/.iris/credentials.

iris config

iris config init        # interactive preset selection, writes .irisconfig.json
iris config validate    # validate an existing .irisconfig.json

Configuration

Iris Code reads .irisconfig.json from the target directory upwards. Preset configs are free; custom thresholds and gate limits require Pro. iris config init interactively offers legacy, balanced, or strict - security and typescript are also valid presetId values but must be set by hand.

{
  "presetId": "balanced",         // free - "legacy" | "balanced" | "strict" | "security" | "typescript"
  "minHealthScore": 75,           // pro - gate threshold
  "gateMaxSecrets": 0,            // pro - fail if any secrets found
  "gateMaxComplexity": 15,        // pro - fail if any file exceeds this
  "gateMaxFileLength": 400,       // pro - fail if any file exceeds this line count
  "gateMaxSmellsPerFile": 10,     // pro - fail if any file exceeds this total smell count
  "gateMaxSecuritySmells": 0,     // pro - fail if any security smells found
  "ignoreFiles": ["**/*.test.ts", "**/generated/**"]
}

Exit codes

check, secrets, security, deps, cve, and gate fail the run when they find something (cve only at or above its --severity threshold):

| Code | Meaning | |------|---------| | 0 | Pass / no findings | | 1 | Fail / findings found | | 2 | Invalid arguments or config error |

config validate exits 1 only on schema/value errors (warnings still exit 0). todos, report, sbom, hook, and config init are informational or one-shot - they exit 0 on success and 2 on bad arguments or an unwritable path; they never exit 1 based on what they find.

--output must resolve inside the current working directory on every command that writes a file (check, deps, cve, report, sbom). A path that escapes it - ../report.html, or an absolute path elsewhere - exits 2 and writes nothing, so a templated path in CI cannot drop files outside the project being scanned.

GitHub Actions

- uses: actions/setup-node@v4
  with:
    node-version: '20'

- run: npm install -g @iris-code/cli

- name: Iris Code enforcement gate
  run: iris gate . --format github
  env:
    IRIS_LICENCE_TOKEN: ${{ secrets.IRIS_LICENCE_TOKEN }}

--format github emits inline PR annotations on failing lines and a pass/fail summary table, and exits 1 to block the merge when a rule fails. Requires Pro.

To keep a machine-readable report as a build artifact regardless of pass/fail, add:

- name: Save JSON report
  if: always()
  run: iris gate . --format json --output iris-report.json
  env:
    IRIS_LICENCE_TOKEN: ${{ secrets.IRIS_LICENCE_TOKEN }}

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: iris-report
    path: iris-report.json

Full documentation and workflow variants at iriscode.co/docs/enforcement/github-actions.

VS Code extension

The Iris Code VS Code extension provides the same analysis interactively in your editor - sidebar UI, inline diagnostics, hook management, and a dependency audit panel. Install it from the VS Code Marketplace.