@diffpulse/cli

Deterministic checks for git diffs and pull requests.

DiffPulse evaluates changes against .diffpulse/policy.yaml — diff size, sensitive paths, test presence, lockfiles, and more — and returns structured findings with a verdict. It runs on local git state. No hosted AI. No GitHub App required for local review.

What DiffPulse is not

• Not an AI reviewer (does not call OpenAI, Anthropic, or other LLM providers)
• Not a GitHub App dependency for local workflows
• Not a code generator

Install

npm install -D @diffpulse/cli

Or run without installing:

npx @diffpulse/cli <command>

Command aliases: diffpulse, diffp, dpulse.

Quick start

npx @diffpulse/cli init
npx @diffpulse/cli doctor

git checkout -b my-change
# ... edit, commit ...
npx @diffpulse/cli check

By default, check auto-detects the diff target: staged → unstaged → branch vs detected base. When staged changes exist, DiffPulse reviews what you are about to commit.

For pre-commit hooks, use diffpulse check --staged or the diffpulse:check:staged npm script added by diffpulse init.

Example commands

diffpulse check                           # auto-detect target
diffpulse check --staged                  # staged changes only
diffpulse check --unstaged                # unstaged changes only
diffpulse check --all-local               # all local changes
diffpulse check --base main               # branch target vs main
diffpulse check --target branch --base main
diffpulse check --format markdown
diffpulse check --format json             # machine-readable source of truth

Commands

| Command | Description | |---------|-------------| | diffpulse init | Scaffold .diffpulse/policy.yaml and .github/workflows/diffpulse.yml | | diffpulse check | Evaluate git diff against base ref | | diffpulse config validate | Validate the policy file | | diffpulse doctor | Check local environment and configuration | | diffpulse version | Print version |

check options

| Option | Description | |--------|-------------| | --target <target> | Diff target: staged, unstaged, all-local, or branch | | --base <ref> | Base git ref for branch target (implies --target branch) | | --staged / --unstaged / --all-local | Shorthand for --target | | --policy <path> | Policy file path (default: .diffpulse/policy.yaml) | | --format <format> | text (default), json, or markdown | | --output <path> | Write report to file | | --fail-on <verdict> | Exit non-zero at warn or block level (default: block) |

Secrets redaction

The secrets_in_diff check scans added diff lines for likely credentials. Secret values are never printed in full — CLI text, JSON, and Markdown output use redacted snippets only.

Exit codes

| Code | Meaning | |------|---------| | 0 | pass (or below --fail-on threshold) | | 1 | warn | | 2 | block | | 3 | error |

Cursor / MCP workflow

1. Configure @diffpulse/mcp in .cursor/mcp.json
2. Stage your changes (or check out a feature branch for branch review)
3. Ask: "Review my staged changes with DiffPulse before I commit."
4. Cursor calls DiffPulse MCP; DiffPulse returns structured findings; Cursor explains and fixes them

DiffPulse analyzes local git diffs only — staged, unstaged, all-local, or branch vs base. It does not read GitHub or Azure DevOps PR APIs. Hosted PR targets are future work.

{
  "mcpServers": {
    "diffpulse": {
      "command": "npx",
      "args": ["-y", "@diffpulse/mcp"]
    }
  }
}

| MCP tool | Purpose | |----------|---------| | diffpulse_review_diff | Review local branch diff (primary) | | diffpulse_check | Alias for diffpulse_review_diff | | diffpulse_policy_summary | Summarize policy checks and thresholds | | diffpulse_explain_report | Deterministic report explanation |

See MCP Setup.

Links

• Documentation
• Issues
• npm

License

MIT