CLI Tool Reference

The ai-guard command-line interface provides fast developer utilities for local scanning, Git pre-commit hooks, and CI/CD pipelines without requiring complex configuration files.

CLI Overview

npx ai-guard <command> [options]

ai-guard run

Scans the repository or specified paths using AST rules:

# Run with default recommended preset
npx ai-guard run

# Scan specific directories
npx ai-guard run --path src,server

# Strict mode (all 18 rules at error)
npx ai-guard run --strict

# Security rules only
npx ai-guard run --security

# Output SARIF 2.1.0 file for GitHub Code Scanning
npx ai-guard run --sarif --sarif-output results.sarif

# Machine-readable JSON output for custom CI pipelines
npx ai-guard run --json

ai-guard changed

Differential scanner designed specifically for Git branches, PRs, and pre-commit hooks. Scans only modified files:

# Scan only files changed in current Git branch vs main
npx ai-guard changed --pr

# Scan only staged files (ideal for Husky / lint-staged)
npx ai-guard changed --staged

ai-guard baseline

When adding AI Guard to a legacy codebase with existing technical debt, you do not want to fail CI on pre-existing code. Use baseline to track only *new* regressions:

# Create baseline snapshot of existing issues
npx ai-guard baseline --create

# Run scanner in baseline mode (fails only on newly introduced issues)
npx ai-guard run --baseline .ai-guard-baseline.json

ai-guard init-context

Generates AI tool rules files (CLAUDE.md, .cursorrules, and .github/copilot-instructions.md) so that AI coding models avoid generating anti-patterns at prompt time.

npx ai-guard init-context

ai-guard doctor

Verifies your local development environment, checking ESLint installation, config resolution, parser compatibility, and TypeScript setup:

npx ai-guard doctor

Exit Codes & Fail Strategies

• 0: Scan passed cleanly (or warnings only with --fail-on errors).
• 1: Lint errors detected or exit criteria violated.
• 2: Configuration or internal runtime error.

Controlling Fail Sensitivity in CI:

# Fail only if error-level issues are found (default)
npx ai-guard run --fail-on errors

# Fail if any warning is detected
npx ai-guard run --max-warnings 0

# Never fail CI, only report issues
npx ai-guard run --fail-on none