Grapple PR CLI

Command-line interface for Grapple PR — AI code review platform.

Install

npm install -g grapple-pr

Requires Node.js 20+.

Authentication

The CLI authenticates via GitHub OAuth using a secure PKCE flow:

grapple login

This opens your browser, redirects to GitHub for authorization, and stores tokens locally. No API keys or manual token management required.

How it works:

1. A temporary local server starts on a random port (http://127.0.0.1:{port})
2. Your browser opens to GitHub OAuth via Supabase
3. After authorization, GitHub redirects back to the local server with an auth code
4. The code is exchanged for session tokens (access + refresh)
5. Tokens are stored in ~/.grapple/credentials.json (0600 permissions on Unix)
6. The local server shuts down

Token refresh: The CLI automatically refreshes expired tokens before each API call. If refresh fails (e.g., session revoked from the dashboard), it prompts you to grapple login again.

Logout:

grapple logout

Clears ~/.grapple/credentials.json and any cached context.

Quick Start

# Authenticate via GitHub
grapple login

# Check connection
grapple status

# List your repos
grapple repos

# View findings for the current PR (auto-detected from your branch)
grapple findings

# Trigger a re-review
grapple review

# Apply a fix
grapple fix <findingId>

Commands

grapple login

Authenticate with Grapple PR via GitHub OAuth.

grapple login
grapple login --api-url https://custom-api.example.com

grapple logout

Clear stored credentials.

grapple logout

grapple status

Show connection status, logged-in user, organization, and current repo/branch/PR context. Works partially without auth (shows API health).

grapple status
grapple status --json

Example output:

Grapple PR Status
─────────────────────
  API:      https://api.grapple-pr.com (ok, 245ms)
  Version:  0.1.2
  User:     [email protected]
  Org:      my-org (owner)
  Repo:     my-org/my-app
  Branch:   feat/login-page
  PR:       #42 Fix auth flow (completed)

grapple repos

List all connected repositories with their graph build status.

grapple repos
grapple repos --json

grapple findings

List review findings for a PR. Auto-detects the PR from your current branch, or specify with --pr.

grapple findings
grapple findings --pr 42
grapple findings --severity critical
grapple findings --agent security
grapple findings --status pending
grapple findings --json

Filters:

• --pr <number> — PR number (auto-detected from branch if omitted)
• --severity <level> — Filter: critical, major, minor, info
• --agent <name> — Filter: security, logic, architecture, performance, style
• --status <status> — Filter: pending, accepted, dismissed, fixed

grapple review

Trigger a review (or re-review) on a PR.

grapple review
grapple review --pr 42
grapple review --pr 42 --wait

Options:

• --pr <number> — PR number (auto-detected from branch if omitted)
• --wait — Poll until the review completes (5-minute timeout). Shows a spinner with elapsed time.

grapple fix <findingId>

Apply an autofix for a specific finding.

# Apply fix to the PR branch via GitHub API (default)
grapple fix abc123-def456

# Apply fix to your local working tree
grapple fix abc123-def456 --local

grapple fix abc123-def456 --json

Options:

• --local — Write the patch to your local files instead of committing to the PR branch. Useful for reviewing the diff before committing.

The finding ID is shown in grapple findings output.

grapple config

Read or update repository review settings.

# Show all settings
grapple config

# Show a specific setting
grapple config confidenceThreshold

# Update a setting
grapple config confidenceThreshold 80
grapple config enabledAgents security,logic,architecture
grapple config autoFixEnabled true

Available settings:

• confidenceThreshold — Minimum confidence score (0-100, default 70)
• enabledAgents — Comma-separated agent list
• autoFixEnabled — Enable/disable autofix (true/false)
• maxPrSize — Max PR file count (1-10000)
• excludePaths — Comma-separated glob patterns to ignore
• inlineCommentSeverity — Minimum severity for inline GitHub comments

grapple init

Generate a .grapple.yml configuration file interactively.

grapple init
grapple init --force   # overwrite existing file

Prompts for:

• Which agents to enable
• Confidence threshold
• Paths to ignore
• Linters in use (to avoid duplicate findings)
• Hotfix branch patterns

grapple finding-mark <findingId> <action>

Mark a finding as accepted, dismissed, or pending. Useful for clearing noise without leaving the terminal.

grapple finding-mark abc123 dismissed --reason "false positive"
grapple finding-mark abc123 accepted

grapple preferences

Manage your personal notification preferences (email digests, review-complete pings).

grapple preferences get
grapple preferences set digest on
grapple preferences set frequency weekly       # daily | weekly | off
grapple preferences set notify off

grapple notifications <orgId>

Manage org-level Slack and Discord webhooks.

grapple notifications get <orgId>
grapple notifications set <orgId> slackWebhookUrl https://hooks.slack.com/...
grapple notifications set <orgId> slackEnabled true
grapple notifications set <orgId> discordWebhookUrl https://discord.com/api/webhooks/...
grapple notifications set <orgId> discordEnabled true
grapple notifications test <orgId> --provider slack
grapple notifications test <orgId> --provider discord

Webhook URLs are masked when displayed so they don't leak in screenshots or shell history.

grapple stats <orgId>

Show review activity stats for an org.

grapple stats <orgId> --days 7              # summary
grapple stats <orgId> --days 30 --trends    # daily trend rows
grapple stats <orgId> --days 30 --agents    # per-agent breakdown
grapple stats <orgId> --json

grapple billing <orgId>

Show billing tier or usage.

grapple billing <orgId>             # plan / tier / Stripe link status
grapple billing <orgId> --usage     # daily + monthly review counts

grapple audit

Run a codebase audit on the current repo (auto-detected from git context) or fetch the most recent one.

grapple audit run
grapple audit run --max-files 50
grapple audit status

grapple admin (PLATFORM_ADMIN-only)

Operational commands for managing per-org feature flags and viewing internal stats. Requires isPlatformAdmin: true on your account.

# Feature flags
grapple admin flags get <orgId>
grapple admin flags set <orgId> autofixGate on          # on | off | shadow
grapple admin flags set <orgId> rankerMinScore 0.65
grapple admin flags reset <orgId>                       # clear all overrides

# Internal stats
grapple admin stats <orgId> --kind autofix --days 30
grapple admin stats <orgId> --kind self-check --days 30

Flag values are parsed as JSON, so quote complex values ('"shadow"' etc.) — bare strings like on / off work without quoting.

grapple completion

Output shell completion scripts.

# Bash — add to ~/.bashrc
eval "$(grapple completion bash)"

# Zsh — add to ~/.zshrc
eval "$(grapple completion zsh)"

# Fish — save to completions directory
grapple completion fish > ~/.config/fish/completions/grapple.fish

Global Options

All commands support:

• --json — Output results as JSON (for scripting/CI)
• --no-color — Disable colored output
• --api-url <url> — Override the API URL

Git Context Detection

The CLI auto-detects your repository and PR from the current directory:

1. Reads git remote -v to find the GitHub owner/repo
2. Matches it against your connected Grapple PR repositories
3. Reads the current branch and finds the matching PR

This means you can run grapple findings or grapple review without any flags when you're on a feature branch with an open PR.

Environment Variables

• GRAPPLE_API_URL — Override the default API URL
• GRAPPLE_SUPABASE_URL — Override the Supabase project URL (advanced)
• GRAPPLE_SUPABASE_ANON_KEY — Override the Supabase anon key (advanced)

Files

• ~/.grapple/credentials.json — OAuth tokens (auto-managed, 0600 permissions)
• ~/.grapple/context-cache.json — Cached org/repo mappings (auto-managed)
• .grapple.yml — Per-repo configuration (created by grapple init, read by review agents)

Troubleshooting

"Not logged in" — Run grapple login. If it fails, check that your GitHub account has access to the Grapple PR GitHub App.

"No authorization code received" — Try grapple login again. If the issue persists, check that your browser completed the GitHub authorization and redirected back to 127.0.0.1.

"Not in a git repo or no GitHub remote found" — Run the command from inside a git repo with a GitHub remote, or use --pr <number> to specify the PR explicitly.

"Repository X is not connected to Grapple PR" — Install the Grapple PR GitHub App on the repository first, then run grapple repos to verify it appears.

Login hangs / doesn't exit — The CLI waits up to 2 minutes for the OAuth callback. If your browser didn't open, copy the URL from the terminal manually. Press Ctrl+C to cancel.

Node.js version — Requires Node.js 20 or later. Check with node --version.