name: gh-cli description: GitHub CLI (gh) reference for repositories, issues, PRs, Actions, releases, and all GitHub operations from the command line. Use when working with GitHub API, automating workflows, or managing repos. allowed-tools: "Bash(gh *), Bash(git *), Read, Glob, Grep"

GitHub CLI (gh)

Reference for GitHub CLI. If arguments are provided, execute: gh $ARGUMENTS or git $ARGUMENTS

Decision: Which Command?

Think about what the user needs, then select the right command family:

Repositories

gh repo create my-repo --public --description "Description"
gh repo clone owner/repo
gh repo view [--json name,description]
gh repo fork owner/repo --clone
gh repo sync                        # Sync fork with upstream

Issues

gh issue create --title "Title" --body "Body" --labels bug
gh issue list [--state all] [--assignee @me] [--labels bug]
gh issue view 123 [--comments] [--json title,body,state]
gh issue edit 123 --add-label high-priority
gh issue close 123 --comment "Fixed in PR #456"
gh issue develop 123 --branch fix/issue-123

Pull Requests

gh pr create --title "Feature" --body "Description" [--draft]
gh pr list [--state all] [--author @me] [--json number,title]
gh pr view 123 [--comments] [--json title,body,files]
gh pr checkout 123
gh pr diff 123
gh pr merge 123 --squash --delete-branch
gh pr review 123 --approve
gh pr checks 123 --watch
gh pr ready 123                     # Mark draft as ready

Actions and Workflows

gh run list [--workflow "ci.yml"] [--branch main]
gh run view 123456 [--log] [--job ID]
gh run watch 123456
gh run rerun 123456 [--job ID]
gh workflow list
gh workflow run ci.yml [--ref develop]
gh cache list [--branch main]
gh cache delete --all

Secrets and Variables

gh secret list
gh secret set MY_SECRET [--env production]
echo "$VALUE" | gh secret set MY_SECRET
gh variable set MY_VAR "value" [--env production]

Releases

gh release create v1.0.0 --notes "Release notes" [--draft]
gh release list
gh release download v1.0.0 [--pattern "*.tar.gz"]

Search

gh search code "pattern" [--repo owner/repo]
gh search issues "label:bug state:open"
gh search prs "is:open review:required"
gh search repos "stars:>1000 language:python"

API Requests

gh api /user
gh api --method POST /repos/owner/repo/issues \
  --field title="Title" --field body="Body"
gh api /user/repos --paginate
gh api graphql -f query='{ viewer { login } }'

Output Formatting

gh pr list --json number,title --jq '.[] | select(.number > 100)'
gh repo view --json owner,name --jq '.owner.login + "/" + .name'

<environment_variables>

</environment_variables>

Create PR from issue

gh issue develop 123 --branch feature/issue-123
git add . && git commit -m "Fix #123" && git push
gh pr create --title "Fix #123" --body "Closes #123"

Check CI and wait for results

gh workflow run ci.yml --ref main
gh run list --workflow ci.yml --limit 1 --json databaseId \
  --jq '.[0].databaseId' | xargs gh run watch

Bulk close stale issues

gh issue list --search "label:stale" --json id --jq '
  if length == 0 then
    "query { __typename }"
  else
    "mutation { " + (
      to_entries
      | map(
        "c\(.key): addComment(input:{subjectId:" + (.value.id | @json) + ",body:" + ("Closing as stale" | @json) + "}){clientMutationId}" +
        " s\(.key): closeIssue(input:{issueId:" + (.value.id | @json) + "}){clientMutationId}"
      )
      | join("")
    ) + " }"
  end
' | gh api graphql -f query=-

References

• Manual: https://cli.github.com/manual/
• REST API: https://docs.github.com/en/rest
• GraphQL API: https://docs.github.com/en/graphql