CLI Reference

Convention enforcement

caliper init --agent

Set up the Claude Code stop hook.

npx caliper init --agent

caliper refresh

Regenerate deterministic checks from CLAUDE.md files (root and nested). Requires ANTHROPIC_API_KEY.

npx caliper refresh                   # Auto-accept all generated checks
npx caliper refresh --interactive     # Manually approve each check
npx caliper refresh --force           # Bypass manifest cache and re-extract everything
npx caliper refresh --trace           # Write extraction trace to /tmp/caliper/refresh/trace.json
npx caliper refresh --concurrency 8   # Run N file extractions in parallel (default: 4)
npx caliper refresh --eslint          # Also generate .caliper/eslint.config.js from checks

Convention enforcement (stop hook)

caliper check

Claude Code stop hook — runs deterministic convention checks after every agent turn. No API key needed.

npx caliper check              # Run convention checks (stop hook mode)
npx caliper check --all-files  # Check all source files, not just recently changed
npx caliper check --severity blocking  # Only report blocking issues
npx caliper check --verbose    # Show details

Flag	Description
--all-files	Check all source files, not just recently changed
--severity <level>	Minimum severity to report (blocking, recommendation, nit)
--verbose	Show details

caliper gate

Pre-commit hook — runs deterministic and AI checks non-interactively and blocks commits with blocking findings. Requires ANTHROPIC_API_KEY.

npx caliper gate               # Non-interactive, exit 1 on blocking findings

Flag	Description
--severity <level>	Minimum severity to report (blocking, recommendation, nit)
--verbose	Show details

Local code review

caliper review

Review local changes before committing — no GitHub PR needed.

npx caliper review             # Review staged changes interactively
npx caliper review --fix       # Auto-apply suggested fixes to working tree
npx caliper review --branch    # Review all commits on this branch vs base
npx caliper review --resume    # Resume the last review without re-running AI
npx caliper review --full      # Run full pipeline (synthesis, lenses, consolidation)
npx caliper review --severity blocking  # Only report blocking issues
npx caliper review --verbose   # Show Claude API request/response details

Flag	Description
--fix	Auto-apply suggested fixes to working tree files
--full	Run full pipeline (synthesis, lenses, consolidation)
--resume	Resume the last review without re-running AI
--branch	Review all commits on this branch vs base branch
--pre-push	Review only commits not yet pushed (reads pre-push stdin)
--fail-on-blocking	Exit 1 if blocking findings are found
--severity <level>	Minimum severity to report (blocking, recommendation, nit)
--verbose	Show Claude API request/response details

PR review

caliper <pr-number>

Run a full review pipeline on a pull request.

npx caliper <pr-number> [flags]

Flag	Description
--resume	Resume from the last saved phase
--skip-refresh	Skip the staleness check on startup
--no-post	Run the review but skip the posting phase
--post-only	Post findings from a previous review without re-running
--sequential	Use sequential finding reviewer instead of navigator
--fast	Force fast path (skip synthesis/lenses/consolidation/narrative)
--full	Force full pipeline even for small PRs
--ci	Non-interactive mode for CI/CD (auto-approve and post findings)
--min-severity <level>	Minimum severity to post in CI mode (blocking, recommendation, nit)
--max-cost <amount>	Cost ceiling in USD — skip review if exceeded (CI mode)
--fail-on-blocking	Exit 1 if blocking findings found (CI mode)
--verbose	Show Claude API request/response details
--help, -h	Show help message
--version, -V	Show version number

Examples:

npx caliper 142                # Full review
npx caliper 142 --resume       # Resume interrupted review
npx caliper 142 --no-post      # Review without posting
npx caliper 142 --post-only    # Re-enter approval for existing findings
npx caliper 142 --fast         # Force fast path
npx caliper 142 --ci           # Non-interactive CI mode

caliper (no args)

When run with no arguments in a TTY, shows an interactive PR picker to select an open PR for review.

Configuration & diagnostics

caliper config

View or manage project configuration.

npx caliper config           # Print the resolved configuration
npx caliper config path      # Print the config file path
npx caliper config edit      # Open the config file in your editor

caliper doctor

Run diagnostic health checks and print a pass/fail checklist.

npx caliper doctor

Checks: Node.js version, GitHub CLI installation and auth, .caliper/ directory, config validity, API key, backend reachability.

Utilities

caliper init

Scaffold .caliper/ configuration, compile conventions, and install hooks.

npx caliper init                # Auto-detect everything, zero prompts (default)
npx caliper init --interactive  # Full 8-step questionnaire for preferences
npx caliper init --agent        # Set up Claude Code stop hook only
npx caliper init --hooks-only   # Install git hooks only — works from git worktrees
npx caliper init --ci           # Set up GitHub Actions workflow only

Init runs the full setup in one command:

1. Creates .caliper/ with config and policy
2. Compiles CLAUDE.md conventions into deterministic checks (if CLAUDE.md and API key exist)
3. Installs Claude Code stop hook and git pre-commit hook
4. Runs your first convention checks to show immediate results

If gh CLI or ANTHROPIC_API_KEY are missing, init gracefully falls back to convention enforcement only and shows next steps to unlock AI review. --yes / -y are kept as backward-compatible aliases (now the default behavior).

caliper trace

View the pipeline trace for a completed review.

npx caliper trace <pr-number>          # Print summary and open trace.html
npx caliper trace <pr-number> --json   # Print path to trace.json

Output includes: step count, AI call count, total duration, cost estimate, and convention check results.

caliper clean

Remove old review state and trace files.

npx caliper clean                  # Remove all review state
npx caliper clean <pr-number>      # Remove state for a specific PR
npx caliper clean --older-than 7   # Remove reviews older than 7 days

caliper stats

Display review history analysis — approval rates, false positive patterns, emerging conventions, and phase effectiveness.

npx caliper stats

Requires at least 5 history entries in .caliper/history.jsonl. History is recorded automatically when you approve or skip findings during npx caliper review and npx caliper <pr-number> reviews.

caliper-post

Standalone script for posting findings from a completed review.

# Post specific findings by index
caliper-post <pr-number> <index> [<index> ...]

# Post all pending findings as a batched review
caliper-post <pr-number> --review [--event REQUEST_CHANGES|COMMENT|APPROVE]