Getting Started

#Prerequisites

• Node.js 20 or newer.
• npm 10 or newer (yarn, pnpm, and bun work when you pin packages locally).
• A repository with source files you want to scan.

#Quick start

npx @critiq/cli check .

Run this from your repository root. You do not need to install anything first in an interactive terminal: when the default @critiq/rules catalog is missing, Critiq detects whether the CLI is installed locally or globally, checks your repo and global Node modules, then prompts you to install the catalog in the repository or globally. Critiq picks npm, yarn, pnpm, or bun from your lockfile, prints the exact install command, and continues the scan after a successful install.

The target argument defaults to ., so npx @critiq/cli check and npx @critiq/cli check . target the current working tree.

#Pin for CI and teams

npm install -D @critiq/cli @critiq/rules

Add both packages as dev dependencies when you want reproducible versions in package.json, shared scripts, or CI. This is the recommended path for pull request checks and non-interactive runners (where Critiq prints install instructions instead of prompting).

#One-shot without installing

npx -p @critiq/cli -p @critiq/rules critiq check .

Use this when you want a single command that downloads both @critiq/cli and @critiq/rules into a temporary npx cache, for example in a snippet or a non-interactive environment that should not modify your repository.

#Scan behavior

• If .critiq/config.yaml exists, the scan uses it. If it does not exist, Critiq falls back to the default OSS catalog and recommended preset.
• Built-in ignores skip dependency output and generated folders before your own ignorePaths are applied.
• Test files are excluded by default so the first run focuses on production paths. Enable includeTests: true when you want rules to inspect test code as well.
• Findings should be treated as deterministic rule results. The rule ID, category, severity, and evidence are stable enough to use in scripts and CI checks.

#Diff-scoped scan

npx @critiq/cli check . --base origin/main --head HEAD

Use diff mode when a pull request or local branch only needs findings for changed files and changed ranges. Both --base and --head are required.

#Output formats

• --format pretty is the default for terminal output.
• --format json is available for scripts, checks, and CI parsing.
• --format sarif produces a SARIF document for security-platform ingestion. check only.
• --format html produces a human-readable report for review handoff. check only.

npx @critiq/cli check . --format pretty
npx @critiq/cli check . --format json
npx @critiq/cli check . --format sarif
npx @critiq/cli check . --format html

#Audit secrets

critiq audit secrets is a dedicated secret-pattern scan that exits non-zero on findings. critiq check already runs the same scanner in an advisory pass (it does not affect the check exit code), so use the audit when you want secrets to fail the run.

npx @critiq/cli audit secrets .
npx @critiq/cli audit secrets . --staged
npx @critiq/cli audit secrets . --base origin/main --head HEAD --format json

See the Audit Secrets guide for configuration tuning, JSON envelope, and sample pre-commit / pre-push hooks. The Scan code guide covers the catalog scan workflow and how it relates to audits.

#Exit codes

#Package scripts

For local repeatability, add Critiq to the same script surface your team already uses for tests and linting after you pin the packages.

{
  "scripts": {
    "critiq": "critiq check .",
    "critiq:json": "critiq check . --format json"
  }
}

#Common failures

• Unknown option usually means the command does not support that flag yet. Check the CLI reference for the exact command surface.
• The check command no longer accepts a rules glob means rule selection should move into .critiq/config.yaml.
• If Critiq reports that the rules catalog package is missing in CI or with --format json, pin @critiq/cli and @critiq/rules in package.json or use the one-shot npx -p @critiq/cli -p @critiq/rules form.
• If a scan exits with 1, inspect whether the cause is a finding, invalid input, or a config diagnostic before treating it as a runtime failure.

#Language support

Tests are excluded by default unless includeTests: true is set in .critiq/config.yaml. TypeScript and JavaScript have the deepest support today. Go, Java, PHP, Python, Ruby, and Rust have narrower phase-one adapter coverage.

#Next links