github-pp-cli

An experiment: generate a CLI for an API that already has a great CLI.

This repo is the output of pointing the cli-printing-press machine at GitHub's REST API — a deliberately hard target, because GitHub already ships gh, the canonical first-party CLI most developers reach for. The point of the experiment was to see what a generator can produce on top of a 1000-endpoint OpenAPI spec, where the bar is set by a polished, battle-tested incumbent, and what value (if any) is left to add once the obvious surface is already covered.

What came out is github-pp-cli: a Go binary that mirrors gh's read surface, plus 11 hand-built commands the generator can't infer from a spec alone (cross-repo aggregations, an FTS5 index that bypasses GitHub's 1000-result search cap, a typed-exit pr ship-check, a tag-to-tag release-diff), plus a paired MCP server with code orchestration over all 819 catalogued endpoints. Most of the surface is generator output; the differentiating layer is the part written by hand. The split is the actual experimental result.

If you want the long version — every command, every flag, the auto-emitted API reference — see REFERENCE.md. What follows is just enough to use the thing.

What this is and isn't

• Is: an agent-native GitHub CLI plus an MCP server. Better surface for an LLM than gh (typed exit codes, dotted-path --select, --dry-run, MCP tool catalog at ~5K tokens vs the official MCP's ~50K), with a local SQLite store for cross-repo questions gh structurally can't answer.
• Isn't: a replacement for gh. gh pr create, gh pr checkout, gh repo clone, gh run watch — all better in gh. Use gh for the human-shaped flows; use this for agents and structured questions.

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 binaries land in $GOBIN (typically ~/go/bin — make sure that's on your PATH).

Authenticate

The CLI reuses an existing gh session if you have one:

github-pp-cli auth login --gh
github-pp-cli auth status

Or set GITHUB_TOKEN / GH_TOKEN directly.

Register the MCP server with Claude Desktop

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

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

Restart Claude Desktop. 26 tools become available, including github_graphql for Projects v2 / Discussions v2, pr_ship_check with typed exit codes, and the cross-repo aggregations.

Headline commands

Real verified examples — none of these exist in gh:

# Cross-entity timeline across every synced repo
github-pp-cli recent --since 24h --json

# Per-repo throughput stats
github-pp-cli velocity --org acme --window 30d --json

# What's stuck right now
github-pp-cli bottlenecks --org acme --json

# Tag-to-tag changelog
github-pp-cli release-diff v2.91.0 v2.92.0 --repo cli/cli --json

# One-shot mergeability check with typed exit (0=mergeable, 2=blocked, 3=conflicted)
github-pp-cli pr ship-check cli/cli#1234

# FTS5 search bypassing GitHub's 1000-result cap
github-pp-cli fts "memory leak" --type pulls,issues --json

Plus everything gh does (issues, pulls, repos, releases, runs, search, gists, notifications) wrapped in --json --select and typed exit codes. See github-pp-cli --help for the full tree.

Where to look next

• REFERENCE.md — the full auto-emitted command reference (all 43 resources, every endpoint).
• SKILL.md — guidance for agents using this CLI: when to reach for it, recipes, trigger phrases.
• github-pp-cli api — browse the live command tree from the binary itself.
• cli-printing-press — the generator that produced ~84% of this repo.
• cli/cli — gh, the incumbent. Use it for human-interactive flows.
• github/github-mcp-server — the official GitHub MCP. 162 endpoint-mirror tools, no aggregations, no offline store. This CLI's MCP is a complement, not a replacement.

Provenance

Generated 2026-05-08 from the official GitHub OpenAPI 3.0 spec (sha256 328f1e30...d593c3a2) by the Printing Press v4.0.6, then hand-extended with 11 transcendence commands, an auth subcommand, and a github_graphql MCP tool. Scorecard 89/100 (Grade A); 5/5 shipcheck legs PASS at first publish.

The generator's full pipeline (research, absorb manifest, novel-features brainstorm, build log, retro findings) is preserved at ~/printing-press/manuscripts/github/20260508-100744/ on the author's machine. Three retro issues filed against the Printing Press during this experiment are tracked at #739 (auth synthesis), #740 (mcp_token_efficiency calibration), #741 (writeThroughCache routing).

License

Apache-2.0 — see LICENSE.