Github CLI

GitHub CLI

Safety-first wrapper for GitHub CLI (gh). Every command is classified by risk level before execution.

When to Use

• User asks to create, list, merge, or close PRs
• User asks to manage issues, releases, or repos
• User asks to check CI/CD status or workflow runs
• User asks to call the GitHub API via gh api
• User asks to manage GitHub Actions secrets or variables

Prerequisites

1. Install: brew install gh or see https://cli.github.com
2. Auth: gh auth login
3. Verify: gh --version (requires v2.86+)
4. Scopes: gh auth status — confirm repo, read:org scopes minimum

Safety Model

Every gh command falls into one of four risk tiers:

See references/safety-rules.md for the full classification and confirmation templates.

Decision Flow

Command received
  → Classify risk tier (see Quick Reference)
  → Safe?        Execute immediately
  → Write?       Inform user what will happen → execute
  → Destructive? AskUserQuestion with options → wait for answer → execute or cancel
  → Forbidden?   Warn → require typed confirmation → final confirm → execute or cancel

Quick Reference

Safe (read-only, execute immediately)

Write (inform, then execute)

Destructive (AskUserQuestion required)

Forbidden (multi-step validation)

Workflow Patterns

Pull Requests

# List open PRs
gh pr list

# Create PR (Write — inform user first)
gh pr create --title "feat: add auth" --body "$(cat <<'EOF'
## Summary
- Add JWT authentication middleware

## Test plan
- [ ] Unit tests pass
- [ ] Manual login flow verified
EOF
)"

# View PR with checks
gh pr view 42
gh pr checks 42

# Merge PR (Destructive — AskUserQuestion first)
gh pr merge 42 --squash --delete-branch

Issues

# List issues with filters
gh issue list --label bug --assignee @me
gh issue list --state closed --limit 10

# Create issue (Write)
gh issue create --title "Bug: login fails" --body "Steps to reproduce..." --label bug

# View issue
gh issue view 123

# Close issue (Destructive — confirm first)
gh issue close 123 --reason completed

Releases

# List releases
gh release list

# Create release (Write — inform user)
gh release create v1.2.0 --generate-notes --title "v1.2.0"

# Create release with assets
gh release create v1.2.0 ./dist/*.tar.gz --title "v1.2.0" --notes "Release notes here"

# Delete release (Destructive — confirm first)
gh release delete v1.2.0

CI/CD & Actions

# List recent runs
gh run list --limit 10

# View specific run
gh run view 12345

# View logs for failed run
gh run view 12345 --log-failed

# Re-run failed jobs (Write)
gh run rerun 12345 --failed

# Cancel running workflow (Destructive — confirm)
gh run cancel 12345

# Manage secrets (Write for set, Destructive for delete)
gh secret set API_KEY --body "sk-..."
gh secret list

Repository

# View repo info
gh repo view

# Create repo (Write)
gh repo create my-app --public --clone

# Clone
gh repo clone owner/repo

# Fork (Write)
gh repo fork owner/repo --clone

# Archive (Destructive — confirm first)
gh repo archive owner/repo

API

# GET (Safe)
gh api repos/owner/repo/pulls
gh api repos/owner/repo/issues/123/comments

# POST (Write)
gh api repos/owner/repo/issues -f title="Bug" -f body="Description"

# DELETE (Destructive — confirm first)
gh api repos/owner/repo/issues/123/labels/bug -X DELETE

Self-Healing

gh evolves monthly. On any error: read it → gh help <command> → if still unclear, WebFetch https://cli.github.com/manual/gh_<command> (underscores join subcommands, e.g. gh_pr_merge) → adjust → re-run. Release notes: https://github.com/cli/cli/releases.

AskUserQuestion Integration

For Destructive operations, use AskUserQuestion with tailored options:

PR Merge Example

Question: "How should PR #42 'feat: add auth' be merged?"
Options:
  - "Squash and merge" — Combine all commits into one
  - "Create merge commit" — Preserve commit history
  - "Rebase and merge" — Rebase onto base branch
  - "Cancel" — Do not merge

PR/Issue Close Example

Question: "Close PR #42 'feat: add auth'?"
Options:
  - "Close only" — Close without deleting branch
  - "Close and delete branch" — Close PR and remove source branch
  - "Cancel" — Keep open

Delete Example

Question: "Delete release v1.2.0?"
Options:
  - "Delete release only" — Keep the git tag
  - "Delete release and tag" — Remove both release and git tag
  - "Cancel" — Keep release

For Forbidden operations, follow the triple-confirmation protocol in references/safety-rules.md.

Error Handling

CLI Flags Reference

Shell Safety

• No interactive mode: Never use -i or --interactive flags
• No pagers: Always pipe to cat if output may trigger a pager: gh pr list | cat
• Timeouts: Set reasonable timeouts for commands that could hang
• Quote arguments: Always quote multi-word arguments and heredoc bodies
• Never pass --yes to forbidden operations — always require explicit confirmation

Integration

Pairs with:

• code-quality — Review code before PR creation
• brainstorm — Design features before opening issues
• codex-cli — Second-opinion audit before merging PRs
• gemini-cli — Alternative AI review for PR changes