@iris-code/cli

Code health enforcement for JS/TS, Go, and Python — 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.

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)
• GITHUB_TOKEN env var — GitHub PAT for higher CVE rate limits in iris deps

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 only files changed since last commit | | iris secrets [path] | Free | Scan for hardcoded API keys, tokens, passwords | | iris deps [path] | Pro | Dependency versions + CVE vulnerabilities | | iris todos [path] | Pro | List all TODO / FIXME / HACK comments | | iris gate [path] | Pro | Run enforcement gate, show pass/fail per rule | | 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 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 files changed since last commit (Pro)

iris secrets

Scans JS, TS, Go, and Python for hardcoded secrets — API keys, tokens, passwords. Free, no licence required.

iris secrets .
iris secrets src/ --format json

iris deps

Checks all dependencies against current registry versions and the GitHub Advisory Database for CVEs.

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

Without a GitHub token, the advisory API is limited to 60 req/hr. Run iris auth login to store a GitHub PAT and raise it to 5,000 req/hr, or set GITHUB_TOKEN in your environment.

iris gate

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

iris gate .
iris gate . --format json

Gate rules are read from .irisconfig.json: minHealthScore, gateMaxSecrets, gateMaxComplexity, gateMaxFileLength, gateMaxSmellsPerFile.

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 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 reads .irisconfig.json from the target directory upwards. Preset configs are free; custom thresholds and gate limits require Pro.

{
  "presetId": "balanced",        // free — "legacy" | "balanced" | "strict"
  "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
  "ignoreFiles": ["**/*.test.ts", "**/generated/**"]
}

Exit codes

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

GitHub Actions

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

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

- name: Check code health
  run: iris check . --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 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.