CLI
@rulefix-ai/cli scans a repository on your machine or in CI, prints findings or writes SARIF, GitLab SAST, JSON or Markdown reports, and can record each scan in your RuleFix project.
On this page
Run it
The CLI needs Node.js 18 or newer and nothing else. Run it with npx, or install it with npm install -g @rulefix-ai/cli to get a rulefix command.
# Scan the current repository (Node 18+)
npx -y @rulefix-ai/cli scan
# Only DPDP and PCI DSS rules, as Markdown
npx -y @rulefix-ai/cli scan --framework dpdp,pci-dss --format markdown --output rulefix-report.md
# Look up a rule
npx -y @rulefix-ai/cli explain dpdp.pii-in-logsScanning runs entirely on your machine with the same rules as the dashboard and MCP server. Your code is not sent anywhere.
What is scanned
- In a git repository: every tracked file plus untracked files that
.gitignoredoes not exclude. Paths are relative to the repository root, so issues match the ones from dashboard scans. - Outside git: the directory tree, skipping dependency and build folders (node_modules, vendor, dist, build, .next and similar).
- Binary files, media, archives and lockfiles are skipped, as are files over 512 KiB (change it with --max-file-size).
- Suppress a finding in code with
// rulefix-ignore <rule-id> -- reason; see the rules reference.
Commands and options
| Command or option | What it does |
|---|---|
rulefix scan [dir] | Scan a directory (default: the current one). |
--framework dpdp,gdpr | Only run rules for these frameworks. |
--format | text (default), json, sarif, gitlab-sast or markdown. |
--output <file> | Write the report to a file instead of the terminal. |
--fail-on | Exit with code 1 on findings at or above high (default), medium or low; none never fails. |
--report --project <id> | Record the scan in a RuleFix project (needs RULEFIX_API_KEY). |
--max-file-size · --max-files | Raise or lower the per-file size limit and the file count limit. |
--quiet · --no-color | Print only the summary; plain text without colours (also NO_COLOR=1). |
rulefix rules [--framework] | List the rules. |
rulefix explain <rule-id> | Why a rule matters and how to fix it. |
rulefix projects | List projects in your workspace (needs RULEFIX_API_KEY). |
rulefix scan [dir]- What it does
- Scan a directory (default: the current one).
--framework dpdp,gdpr- What it does
- Only run rules for these frameworks.
--format- What it does
- text (default), json, sarif, gitlab-sast or markdown.
--output <file>- What it does
- Write the report to a file instead of the terminal.
--fail-on- What it does
- Exit with code 1 on findings at or above high (default), medium or low; none never fails.
--report --project <id>- What it does
- Record the scan in a RuleFix project (needs RULEFIX_API_KEY).
--max-file-size · --max-files- What it does
- Raise or lower the per-file size limit and the file count limit.
--quiet · --no-color- What it does
- Print only the summary; plain text without colours (also NO_COLOR=1).
rulefix rules [--framework]- What it does
- List the rules.
rulefix explain <rule-id>- What it does
- Why a rule matters and how to fix it.
rulefix projects- What it does
- List projects in your workspace (needs RULEFIX_API_KEY).
Record scans in RuleFix
With --report, the CLI sends the findings to your project through the REST API. It sends rule ids, file paths, line numbers, messages and redacted one-line excerpts — never file contents.
export RULEFIX_API_KEY=rf_live_… # Settings → API keys
npx -y @rulefix-ai/cli projects # find the project id
npx -y @rulefix-ai/cli scan --report --project 7c2e…A scan of the whole repository is complete: issues that no longer appear are marked fixed in the dashboard. Scanning a subdirectory, using --framework, or hitting a limit makes the scan partial, and a partial scan never closes issues.
Use in CI
Add RULEFIX_API_KEY as a CI secret and the project id as a variable. The job fails on high-severity findings, and SARIF or GitLab SAST output shows findings on the diff.
name: RuleFix
on:
pull_request:
push:
branches: [main]
jobs:
rulefix:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
- run: npx -y @rulefix-ai/cli scan --fail-on high --format sarif --output rulefix.sarif --report
env:
RULEFIX_API_KEY: ${{ secrets.RULEFIX_API_KEY }}
RULEFIX_PROJECT_ID: ${{ vars.RULEFIX_PROJECT_ID }}
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: rulefix.sarifrulefix:
image: node:22
script:
- npx -y @rulefix-ai/cli scan --fail-on high --format gitlab-sast --output gl-sast-report.json --report
artifacts:
when: always
reports:
sast: gl-sast-report.jsonExit codes
0 no findings at or above --fail-on · 1 findings at or above --fail-on · 2 a usage, network or API error.
Environment variables
| Variable | Use |
|---|---|
RULEFIX_API_KEY | API key for --report and projects. |
RULEFIX_PROJECT_ID | Default project for --report. |
RULEFIX_API_URL | API base URL. Default https://api.rulefix.in/v1. |
CI | When set, scans are labelled ci instead of cli in the dashboard. |
RULEFIX_API_KEY- Use
- API key for --report and projects.
RULEFIX_PROJECT_ID- Use
- Default project for --report.
RULEFIX_API_URL- Use
- API base URL. Default https://api.rulefix.in/v1.
CI- Use
- When set, scans are labelled ci instead of cli in the dashboard.