dg --help

Display the help menu, listing all available commands, flags, and usage patterns. This is the quickest way to see what Diff Guardian can do from your terminal.

Usage

npx dg --help
npx dg -h
npx dg help

All three forms are equivalent. They print the help menu and exit with code 0.

Output

$ npx dg --help

  Diff-Guardian — API Contract Enforcement Engine

  Usage: npx dg <command> [options]

  Commands:
    check              Analyze uncommitted working tree changes
    check --staged     Analyze only staged files
    compare <base>     Compare two git refs
    trace <symbol>     Show all importers and call sites
    rules              List all classification rules
    init               Scaffold config + GitHub Actions workflow

  Options:
    --help, -h         Show this help message
    --version, -v      Print version number
    --report-file      Write JSON report to specified path
    --staged           Limit check to staged files only

  Smart default:
    Running 'npx dg' with no arguments auto-detects the environment:
      - GitHub Actions: compares PR base to head, posts PR comment
      - Local terminal: compares default branch to HEAD, strict mode
      - Git hook:       uses DG_HOOK env var to determine behavior

  Examples:
    npx dg check                  Analyze working tree changes
    npx dg check --staged         Analyze only staged files
    npx dg compare main           Compare main branch to HEAD
    npx dg compare v1.0 v2.0      Compare two tags
    npx dg trace processPayment   Find all importers of a symbol
    npx dg rules                  List all 28 classification rules
    npx dg init                   Create config + CI workflow

Global flags

Flag	Short	Description
`--help`	`-h`	Display the help menu and exit.
`--version`	`-v`	Print the installed version of diff-guardian.
`--report-file <path>`	—	Write a JSON report to the specified file instead of (or in addition to) terminal output.
`--staged`	—	When used with `check`, analyze only files in the git staging area.

Version

$ npx dg --version
diff-guardian v0.1.3

Smart default behavior

When npx dg is invoked with no command, it detects the environment and chooses the appropriate behavior automatically:

Environment	Detection	Behavior
GitHub Actions	`GITHUB_ACTIONS=true`	Compares PR base to head SHA. Posts a PR comment. Always exits 0 (advisory).
Git hook (pre-push)	`DG_HOOK=pre-push`	Compares against remote HEAD. Strict mode. Exits 1 on breaking changes.
Git hook (pre-merge-commit)	`DG_HOOK=pre-merge-commit`	Compares merge base to incoming branch. Strict mode.
Git hook (post-merge)	`DG_HOOK=post-merge`	Generates an advisory report. Never blocks.
Local terminal	Default fallback	Compares the default branch (main/master) to HEAD. Terminal output. Strict mode.