GitHub CLI Reference (gh)
IMPORTANT: This skill is for READ-ONLY operations only. DO NOT execute any commands that create, modify, or delete resources.
Repository Identification
Always be specific about which repository to use.
| Method | Command |
|---|---|
Use -R flag | gh <command> -R owner/repo |
| List remotes | git remote -v |
Best Practice: Use -R owner/repo explicitly instead of relying on the default repository to avoid ambiguity.
Issues (Read-Only)
| Task | Command |
|---|---|
| List issues | gh issue list -R owner/repo |
| View issue | gh issue view <number> -R owner/repo |
| View issue (web) | gh issue view <number> -R owner/repo --web |
| Issue status | gh issue status -R owner/repo |
List options: --state open|closed|all, --label bug, --assignee @me, --limit 10
Pull Requests (Read-Only)
| Task | Command |
|---|---|
| List PRs | gh pr list -R owner/repo |
| View PR | gh pr view <number> -R owner/repo |
| View PR diff | gh pr diff <number> -R owner/repo |
| View PR checks | gh pr checks <number> -R owner/repo |
| PR status | gh pr status -R owner/repo |
List options: --state open|closed|merged|all, --label enhancement, --draft, --limit 10
Repository (Read-Only)
| Task | Command |
|---|---|
| View repo info | gh repo view owner/repo |
| View repo (web) | gh repo view owner/repo --web |
| List your repos | gh repo list |
| List org repos | gh repo list <org> |
GitHub Actions - Workflow Runs (Read-Only)
| Task | Command |
|---|---|
| List runs | gh run list -R owner/repo |
| View run | gh run view <run-id> -R owner/repo |
| View run log | gh run view <run-id> -R owner/repo --log |
| Watch run | gh run watch <run-id> -R owner/repo |
List options: --workflow <name>, --branch <branch>, --limit 10, --status completed|failed|in_progress
GitHub Actions - Workflows (Read-Only)
| Task | Command | | ------------------ | -------------------------------- | ------------------------- | | List workflows | gh workflow list -R owner/repo | | View workflow | gh workflow view <name | id> -R owner/repo | | View workflow YAML | gh workflow view <name | id> -R owner/repo --yaml |
GitHub Actions - Cache (Read-Only)
| Task | Command |
|---|---|
| List caches | gh cache list -R owner/repo |
List options: --limit 10, --sort size|created_at, --order asc|desc
Releases (Read-Only)
| Task | Command |
|---|---|
| List releases | gh release list -R owner/repo |
| View release | gh release view <tag> -R owner/repo |
| View latest | gh release view --latest -R owner/repo |
Search (Read-Only)
| Task | Command |
|---|---|
| Search repos | gh search repos <query> |
| Search issues | gh search issues <query> |
| Search PRs | gh search prs <query> |
| Search code | gh search code <query> |
| Search commits | gh search commits <query> |
Examples:
gh search repos "language:go stars:>1000"
gh search issues "is:open label:bug repo:cli/cli"
gh search code "function main" --language=goStatus (Read-Only)
| Task | Command |
|---|---|
| View status | gh status |
| Org status | gh status -o <org> |
| Exclude repos | gh status -e owner/repo1 -e owner/repo2 |
Shows assigned issues, PRs, review requests, mentions across your subscribed repositories.
API (Read-Only GET Requests)
| Task | Command |
|---|---|
| GET endpoint | gh api <endpoint> -R owner/repo |
| With jq filter | gh api <endpoint> -R owner/repo --jq '.[]' |
| Paginate | gh api <endpoint> -R owner/repo --paginate |
Examples:
gh api repos/owner/repo/issues --paginate
gh api repos/owner/repo/pulls -q '.[] | {number, title}'
gh api graphql -f query='query { viewer { login } }'Common Output Options
| Goal | Flag | Example | | ---------------- | ----------------- | ------------------------------------------------------------- | -------------------------------------- | --------- | | JSON output | --json | gh issue list -R owner/repo --json number,title,state | | JSON fields | --json <fields> | gh pr view 123 -R owner/repo --json headRefName,baseRefName | | Quiet (IDs only) | --jq '.[] |.number' | gh issue list -R owner/repo --jq '.[] |.number' | | Web browser | --web | gh issue view 123 -R owner/repo --web |
Identifying the Current Repository
Before running commands, determine the repository:
# From git remote
git remote -v
# From jj (if using Jujutsu)
jj git remote listAlways use explicit -R owner/repo to ensure you're querying the correct repository.