gh-cli

## Quick Start Verify authentication first: ``` gh auth status ``` All other `gh` commands support `-R OWNER/REPO` to target a specific repository. When omitted, the current directory's repo is used. ## Pull Requests ### Create ``` gh pr create --title "TITLE" --body "BODY" ``` - `--fill` — autofill title and body from commit messages - `--fill-first` — use only the first commit - `--fill-verbose` — use full commit msg + body - `--draft` — create as draft - `--base BRANCH` — set target branch - `--head USER:BRANCH` — specify head from fork - `-a @me` — self-assign - `-l LABEL` — add labels (repeatable) - `-r HANDLE` — request reviewers (repeatable) - `-F file` — read body from file - `--web` — open browser to create Reference issues with `Closes #N` or `Fixes #N` in the body for auto-closure. ### View and List ``` gh pr list [--state open|closed|all] [--label NAME] [--reviewer ME] gh pr view <NUMBER|URL|BRANCH> gh pr status # relevant PRs across repos ``` ### Review ``` gh pr review --approve gh pr review -r -b "Request changes because..." gh pr review --comment -b "Comment only" ``` ### Merge ``` gh pr merge --squash --delete-branch gh pr merge --rebase --delete-branch gh pr merge --merge --delete-branch gh pr merge --auto # auto-merge after checks pass ``` Use `--admin` to bypass merge queue requirements. Use `--match-head-commit SHA` for safety. ### Other ``` gh pr checkout <NUMBER> gh pr diff <NUMBER> gh pr checks <NUMBER> gh pr update-branch <NUMBER> gh pr close <NUMBER> gh pr reopen <NUMBER> gh pr edit <NUMBER> --title "..." --body "..." gh pr lock <NUMBER> gh pr unlock <NUMBER> ``` ## Issues ### Create ``` gh issue create --title "TITLE" --body "BODY" ``` - `-l LABEL` — add labels (repeatable) - `-a HANDLE` — assign (use `@me` or `@copilot`) - `-m MILESTONE` — add to milestone - `-T TEMPLATE` — use issue template - `-F file` — read body from file - `-e` — open editor for title and body - `--web` — open browser ### View and List ``` gh issue list [--state open|closed|all] [--label NAME] [--assignee HANDLE] gh issue view <NUMBER|URL> gh issue status # relevant issues across repos ``` ### Manage ``` gh issue edit <NUMBER> --title "..." --label "..." gh issue comment <NUMBER> -b "COMMENT" gh issue close <NUMBER> gh issue reopen <NUMBER> gh issue lock <NUMBER> gh issue unlock <NUMBER> gh issue pin <NUMBER> gh issue unpin <NUMBER> gh issue transfer <NUMBER> OWNER/REPO gh issue delete <NUMBER> ``` ## Repositories ``` gh repo clone OWNER/REPO gh repo fork OWNER/REPO gh repo create [--private|--public] gh repo list [--visibility public|private|all] gh repo view [--web] gh repo set-default OWNER/REPO gh repo rename <NAME> gh repo archive gh repo unarchive gh repo sync gh repo delete OWNER/REPO # destructive, confirm carefully ``` ## GitHub Actions ``` gh run list gh run view <RUN_ID> gh run watch <RUN_ID> gh run cancel <RUN_ID> gh run rerun <RUN_ID> gh run download <RUN_ID> gh run delete <RUN_ID> gh workflow list gh workflow view <NAME> ``` ## Releases ``` gh release create TAG --title "TITLE" --notes "NOTES" gh release list gh release view TAG gh release upload TAG FILE gh release download TAG --output FILE gh release edit TAG gh release delete TAG gh release delete-asset TAG ASSET gh release verify TAG ``` ## Search ``` gh search issues "QUERY" gh search prs "QUERY" gh search repos "QUERY" gh search code "QUERY" gh search commits "QUERY" ``` Use `--` before queries with hyphens to avoid flag parsing issues: ``` gh search issues -- "is:open -label:bug" ``` ## API Requests For anything not covered by built-in commands: ``` gh api repos/{owner}/{repo}/releases gh api repos/{owner}/{repo}/issues --jq '.[].title' ``` - `-X METHOD` — HTTP method (default GET, auto POST with params) - `-f key=value` — string parameter - `-F key=value` — typed parameter (auto-converts true/false/null/numbers, `@file` reads from file) - `--jq 'QUERY'` — filter output with jq - `--paginate` — fetch all pages - `--slurp` — wrap paginated results into single array - `--input file` — send file as request body - `-H 'Key: Value'` — custom header - `{owner}`, `{repo}`, `{branch}` — auto-resolved placeholders ### Nested parameters ``` gh api endpoint -F 'key[sub]=val' -F 'arr[]=a' -F 'arr[]=b' ``` ### GraphQL ``` gh api graphql -f query='query { viewer { name } }' -F var='value' ``` ## Output Formatting Append to any command producing JSON: ``` --jq '.field' # jq filter --json FIELD,FIELD # specific fields as JSON ``` ## Common Workflows ### Create PR from current branch ``` gh pr create --fill --reviewer HANDLE ``` ### Review and approve current branch PR ``` gh pr review --approve ``` ### Squash merge and cleanup ``` gh pr merge --squash --delete-branch ``` ### Check CI before merging ``` gh pr checks ``` ### Full PR lifecycle 1. Push branch: `git push -u origin BRANCH` 2. Create PR: `gh pr create --fill` 3. Check CI: `gh pr checks` 4. Review: `gh pr review --approve` 5. Merge: `gh pr merge --squash --delete-branch`