GitHub CLI for Pull Request operations with secure token storage
npm install gh-vaultA GitHub CLI with secure token storage using system vaults.
> Note: This is a vibe coded project — built collaboratively with Claude Code. The irony isn't lost on us: an AI-assisted tool designed to give AI assistants less access to your tokens.
A drop-in replacement for the official GitHub CLI (gh)
with enhanced security. Designed for:
- Seamless migration — Same command syntax, no script changes needed
- AI agent compatibility — AI assistants naturally use gh commands;
gh-vault ensures they can't access your token
- Fine-grained token support — First-class support for scoped tokens
The official GitHub CLI (gh) has several limitations that motivated this project:
GitHub's fine-grained Personal Access Tokens let you scope access to specific repositories — a major security improvement. But the official gh CLI treats them as second-class citizens.
You can't use the normal auth flow (gh auth login) with fine-grained tokens — you're forced to export them as environment variables, which:
1. Still doesn't make all commands work — several gh pr commands fail regardless (#7978, #9166)
2. Exposes the token in your shell environment — any process can read it
3. Leaves it in shell history — if you set it inline (GH_TOKEN=xxx gh pr list)
- CVE-2024-53858: gh leaked tokens when cloning repos with submodules on non-GitHub hosts (fixed in v2.63.0)
- Silent fallback: When keyring is unavailable, gh falls back to plaintext ~/.config/gh/hosts.yaml without warning
- Supply chain risks: The Shai-Hulud 2.0 attack (Nov 2025) specifically executed gh auth token to steal GitHub credentials from compromised npm packages
When AI tools like Claude Code access your terminal, they can:
- Read environment variables containing tokens
- Execute commands that output tokens (gh auth token)
- Access config files with stored credentials
gh-vault takes a security-first approach:
| Feature | gh | gh-vault |
|---------|-----|----------|
| Token storage | Config file (plaintext fallback) | System vault (cross-platform) |
| Fine-grained PAT | Env var recommended | Native support |
| Token output command | gh auth token (prints to stdout) | Intentionally omitted |
With gh: Your token has access to everything — repos, gists, orgs, SSH keys, GPG keys. If you share this with an AI tool, you're trusting it with all of that.
With gh-vault:
- Create a fine-grained PAT scoped to just the repos you want
- Store it separately from your main gh authentication
- The AI only gets access to PR operations on repos you choose
- Token never appears in environment variables, command history, or AI context
``bashInstall globally from npm
npm install -g gh-vault
$3
To use
gh as an alias for gh-vault:`bash
Add to ~/.zshrc or ~/.bashrc
alias gh='gh-vault'
`Quick Start
$3
Go to GitHub Settings → Fine-grained PATs:
- Set expiration (90 days recommended)
- Select only the repositories you want to expose
- Permissions: Pull requests (Read/Write), Contents (Read)
$3
`bash
gh auth login
Paste your token when prompted — it's stored in your system vault
`For CI/CD or non-interactive environments:
`bash
echo "$GITHUB_PAT" | gh-vault auth login --dangerously-skip-vault
`$3
`bash
gh pr list
gh pr view 123
gh pr create --title "Fix bug" --body "Description"
`CLI Commands
gh-vault mirrors the official
gh CLI syntax.$3
`bash
List PRs
gh pr list # Open PRs in current repo
gh pr list --state closed # Closed PRs
gh pr list --author octocat # Filter by author
gh pr list --json number,title # JSON outputView PRs
gh pr view 123 # View PR #123
gh pr view --comments # Include comments
gh pr view --web # Open in browserCreate PRs
gh pr create -t "Title" -b "Body"
gh pr create --draft # Create as draft
gh pr create -r reviewer # Request reviewerManage PRs
gh pr edit 123 --add-label bug
gh pr merge 123 --squash
gh pr close 123
gh pr checkout 123View changes
gh pr diff 123
gh pr diff --patch # Full diff
gh pr checks 123 # CI status
`$3
`bash
Repository operations
gh repo list
gh repo view owner/repo
gh repo clone owner/repoWorkflow runs
gh run list
gh run view Workflows
gh workflow list
gh workflow run Search
gh search repos "topic:cli"
gh search prs "is:open author:me"
`gh CLI manual for full command reference.Comparison with official gh
$3
- Secure vault storage: Token encrypted at rest in your OS vault (Keychain, Credential Manager, Secret Service)
- Fine-grained PAT first: Native support for scoped tokens
- Token isolation: Use different tokens for different tools
$3
| Feature | gh command | gh-vault | Coverage |
|---------|------------|----------|----------|
| Pull Requests |
gh pr | ✅ Supported | 14/18 subcommands |
| Repository | gh repo | ✅ Supported | 9/16 subcommands |
| Actions Runs | gh run | ✅ Supported | 5/7 subcommands |
| Workflows | gh workflow | ✅ Full | 5/5 subcommands |
| Search | gh search | ✅ Full | 5/5 subcommands |
| API | gh api | ✅ Full | Complete |
| Issues | gh issue | Not yet | — |
| Releases | gh release | Not yet | — |
| Gists | gh gist | Not planned | — |
| SSH keys | gh ssh-key | Not planned | — |For operations not yet supported, continue using
gh. gh-vault is designed to complement it.$3
gh auth token or any command that outputs the token to stdout.The official
gh auth token command prints your token in plaintext — convenient for scripting, but dangerous when AI assistants or other tools can capture command output. This directly contradicts gh-vault's security-first design.#### Real-World Attack: Shai-Hulud 2.0 (November 2025)
The largest npm supply chain attack compromised 796 packages and over 27,000 repositories. The malware specifically executed
gh auth token to steal GitHub credentials:> "The malicious code executed
gh auth token` as a child process to extract GitHub credentials, which were then exfiltrated to attacker-controlled servers."gh-vault prevents this attack vector by never outputting tokens to stdout.
The entire point of gh-vault is to keep your token in the system vault and nowhere else:
- No token in environment variables
- No token in command output
- No token in shell history
- No token in AI context windows
If you need to extract a token for another tool, use your system's credential manager directly (Keychain Access on macOS, Credential Manager on Windows, or Secret Service tools on Linux) — but understand you're bypassing gh-vault's security model.
- macOS: Keychain
- Linux: Secret Service (GNOME Keyring, KWallet)
- Windows: Credential Manager
- Node.js 20+
For development:
- pnpm (enforced via hooks)
See ARCHITECTURE.md for technical details and development setup.
MIT