GitHub CLI

Every gh command, plus a local store, cross-org rollups, and FTS no other GitHub tool ships.

github-pp-cli matches gh surface for surface and adds a sync engine + SQLite store so you can answer cross-repo questions in one query — recent, bottlenecks, flake-rank, release-diff, reviewer-load, velocity, who-broke-main — plus FTS that bypasses GitHub's 1000-result cap and a rate-limit-aware paginate that doesn't cliff-fail. Every command is agent-native by default: --json, --select, typed exit codes, --dry-run on every mutation.

Learn more at GitHub.

Install

Requires Go 1.26 or newer.

go install github.com/cpard/github-pp-cli/cmd/github-pp-cli@latest
go install github.com/cpard/github-pp-cli/cmd/github-pp-mcp@latest

The two binaries land in $GOBIN (typically ~/go/bin). Make sure that's on your PATH.

From source

git clone https://github.com/cpard/github-pp-cli.git
cd github-pp-cli
go build -o ./github-pp-cli ./cmd/github-pp-cli
go build -o ./github-pp-mcp ./cmd/github-pp-mcp

Register the MCP server with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform:

{
  "mcpServers": {
    "github-pp": {
      "command": "/absolute/path/to/github-pp-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

Restart Claude Desktop. The 26 tools (including github_graphql, pr_ship_check, the 9 cross-repo aggregation tools, fts, and the github_search + github_execute Cloudflare-pattern pair) become available in your conversations.

Authentication

github-pp-cli reuses your gh auth token when present. If gh is signed in (run gh auth status to confirm), no setup is needed. Otherwise set GITHUB_TOKEN (fine-grained PAT recommended; classic PATs and GitHub App installation tokens also accepted). For sync-heavy use, GitHub App installation tokens raise the rate limit ceiling from 5000/hr to 15000/hr.

Quick Start

# Verify token + scopes + rate-limit budget
github-pp-cli auth status


# Build the local store; one watermarked walk per resource
github-pp-cli sync --org acme


# Friday triage: one query across every synced repo
github-pp-cli bottlenecks --org acme --json --select kind,repo,number,reason


# Cross-entity rollup since yesterday
github-pp-cli recent --since 24h --json


# FTS bypassing the 1000-result cap
github-pp-cli fts "flaky test" --type prs,issues --json --select repo,number,title

Unique Features

These capabilities aren't available in any other tool for this API.

Cross-org rollups

reviewer-load — See review load (given, received, pending) per teammate over a window — for 1:1 prep, perf cycles, and cross-squad rollups.

Reach for this when you need to know who's overloaded with reviews — gh cannot answer this without N round trips, and the 1000-result search cap breaks it on big orgs.
```
github-pp-cli reviewer-load --org acme --since 30d --json --select user,reviews_given,reviews_pending,median_ttr_hours
```
recent — One command, all repos: PRs merged, issues closed, releases cut, runs failed since a watermark.

Reach for this for daily / weekly cross-repo standup rollups instead of opening N tabs of gh invocations.
```
github-pp-cli recent --since 24h --org acme --json --select kind,repo,number,title,actor
```
velocity — Per-repo throughput: PRs/day merged, median PR lifetime, p50 time-to-first-review, median CI duration.

Reach for this for engineering health checks and rollups instead of pasting gh pr list --json into a spreadsheet.
```
github-pp-cli velocity --org acme --window 30d --json --select repo,merged_per_day,median_lifetime_h,p50_ttfr_h
```

Local store leverage

fts — Full-text search across every cached issue, PR, commit, and release across every synced repo — bypasses GitHub's 1000-result cap.

Use this when GitHub's search would silently truncate at 1000 hits or when you need to grep comments + bodies + commit messages in one shot.
```
github-pp-cli fts "flaky test" --type prs,issues --since 90d --json --select repo,number,title,updated_at
```
bottlenecks — Surfaces PRs open >N days awaiting review, PRs red >24h, issues without a triage label after 48h.

Use this for Friday triage or sprint hygiene — one command instead of six tabs.
```
github-pp-cli bottlenecks --org acme --review-stale 7d --check-stale 24h --json --select kind,repo,number,reason,age_hours
```

CI / release forensics

flake-rank — Per-job success rate over the last N runs of a workflow, ranked by flakiness with mean duration and last failure.

Use this to triage 'is this job flaking for the team or just on my PR' — gh run list cannot rank.
```
github-pp-cli flake-rank --workflow ci.yml --repo acme/web --since 50runs --json --select job,success_rate,mean_duration_s,last_failure
```
release-diff — Show PRs merged, issues closed, contributors, and files changed between two tags in one repo.

Reach for this to draft release notes or audit what shipped between two tags without walking git log and pasting SHAs into gh pr view.
```
github-pp-cli release-diff v2.14.0 v2.15.0 --repo acme/web --json --select prs,authors,files_changed
```
who-broke-main — For each red main-branch run, the merge commit, PR, author, and elapsed-red duration.

Use this for incident retros and deploy postmortems instead of scrolling gh run list and clicking through.
```
github-pp-cli who-broke-main acme/web --since 7d --json --select run_id,pr,author,started_at,red_duration_s
```

Agent-native plumbing

pr ship-check — One-shot rollup of required reviewers, branch-protection rules, all check runs, merge queue position, and conflicts. Typed exit (0=mergeable, 2=blocked, 3=conflicted).

Agents reach for this to decide whether to merge; humans reach for it to debug 'why won't this PR merge'.
```
github-pp-cli pr ship-check acme/web#1234 --json --select mergeable,blockers,required_reviewers,checks
```

Usage

Run github-pp-cli --help for the full command reference and flag list.

Commands

advisories

Manage advisories

github-pp-cli advisories security-get-global-advisory - Gets a global security advisory using its GitHub Security Advisory (GHSA) identifier.
github-pp-cli advisories security-list-global - Lists all global security advisories that match the specified parameters. If no other parameters are defined, the request will return only GitHub-reviewed advisories that are not malware.

By default, all responses will exclude advisories for malware, because malware are not standard vulnerabilities. To list advisories for malware, you must include the type parameter in your request, with the value malware. For more information about the different types of security advisories, see "About the GitHub Advisory database."

agents

Endpoints for Agents secrets and variables.

github-pp-cli agents tasks-create-task-in-repo - > [!NOTE]

This endpoint is in public preview and is subject to change.

Starts a new Copilot cloud agent task for a repository.

This endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.

Fine-grained access tokens for "Start a task"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Agent tasks" repository permissions (read and write)

GitHub App installation access tokens are not supported for this endpoint.

github-pp-cli agents tasks-get-task-by-id - > [!NOTE]

This endpoint is in public preview and is subject to change.

Returns a task by ID with its associated sessions

Fine-grained access tokens for "Get a task by ID"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Agent tasks" repository permissions (read)

GitHub App installation access tokens are not supported for this endpoint.

github-pp-cli agents tasks-get-task-by-repo-and-id - > [!NOTE]

This endpoint is in public preview and is subject to change.

Returns a task by ID scoped to an owner/repo path

Fine-grained access tokens for "Get a task by repo"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Agent tasks" repository permissions (read)

GitHub App installation access tokens are not supported for this endpoint.

github-pp-cli agents tasks-list-tasks - > [!NOTE]

This endpoint is in public preview and is subject to change.

Returns a list of tasks for the authenticated user

Fine-grained access tokens for "List tasks"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Agent tasks" repository permissions (read)

GitHub App installation access tokens are not supported for this endpoint.

github-pp-cli agents tasks-list-tasks-for-repo - > [!NOTE]

This endpoint is in public preview and is subject to change.

Returns a list of tasks for a specific repository

Fine-grained access tokens for "List tasks for repository"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Agent tasks" repository permissions (read)

GitHub App installation access tokens are not supported for this endpoint.

app

Information for integrations and installations.

github-pp-cli app create-installation-access-token - Creates an installation access token that enables a GitHub App to make authenticated API requests for the app's installation on an organization or individual account. Installation tokens expire one hour from the time you create them. Using an expired token produces a status code of 401 - Unauthorized, and requires creating a new installation token. By default the installation token has access to all repositories that the installation can access.

Optionally, you can use the repositories or repository_ids body parameters to specify individual repositories that the installation access token can access. If you don't use repositories or repository_ids to grant access to specific repositories, the installation access token will have access to all repositories that the installation was granted access to. The installation access token cannot be granted access to repositories that the installation was not granted access to. Up to 500 repositories can be listed in this manner.

Optionally, use the permissions body parameter to specify the permissions that the installation access token should have. If permissions is not specified, the installation access token will have all of the permissions that were granted to the app. The installation access token cannot be granted permissions that the app was not granted.