GitHub CLI (gh) — Comprehensive Skill

Version: gh 2.66.1+
Auth: gh auth login or set GH_TOKEN env var
Always use --repo OWNER/REPO (or -R) when not inside a git repo directory.

Table of Contents

1. Authentication & Config
2. Repositories
3. Issues
4. Pull Requests
5. GitHub Actions (Runs & Workflows)
6. Releases
7. Gists
8. Search
9. Labels
10. Secrets & Variables
11. Caches
12. Projects V2
13. API (REST & GraphQL)
14. Extensions
15. Codespaces
16. Copilot
17. Other Commands
18. JSON Output & Formatting
19. Environment Variables
20. Advanced Patterns
21. Tips & Gotchas

1. Authentication & Config

Auth

# Interactive login (browser-based OAuth)
gh auth login

# Login with a PAT from stdin
echo "$MY_TOKEN" | gh auth login --with-token

# Login to GitHub Enterprise
gh auth login --hostname enterprise.example.com

# Add extra scopes (e.g., project scope for Projects V2)
gh auth refresh -s project

# Add delete_repo scope
gh auth refresh -s delete_repo

# Check auth status (shows active account, scopes, token validity)
gh auth status
gh auth status --show-token

# Switch active account (when multiple accounts configured)
gh auth switch

# Print the active token (useful for piping to other tools)
gh auth token

# Logout
gh auth logout

Required scopes by feature:

Config

# List all config
gh config list

# Get/set individual values
gh config get git_protocol        # https or ssh
gh config set git_protocol ssh
gh config set editor "code --wait"
gh config set pager "less -R"
gh config set prompt disabled     # disable interactive prompts (good for scripts)
gh config set browser "firefox"

# Clear CLI cache
gh config clear-cache

Git credential setup

# Configure git to use gh for HTTPS auth
gh auth setup-git

2. Repositories

Create

# Interactive
gh repo create

# Public repo, clone locally
gh repo create my-project --public --clone

# In an org
gh repo create my-org/my-project --private

# From local directory
gh repo create my-project --private --source=. --remote=upstream --push

# From template
gh repo create my-project --template owner/template-repo --clone

# With options
gh repo create my-project --public --description "My project" \
  --license mit --gitignore Node --add-readme

Clone

gh repo clone owner/repo
gh repo clone owner/repo my-dir
gh repo clone owner/repo -- --depth=1    # shallow clone

# Clone your own repo (owner defaults to you)
gh repo clone my-repo

Fork

# Fork current repo
gh repo fork

# Fork and clone
gh repo fork owner/repo --clone

# Fork into an org
gh repo fork owner/repo --org my-org --fork-name new-name

# Fork default branch only
gh repo fork owner/repo --default-branch-only

View

# View current repo (README + description)
gh repo view
gh repo view owner/repo

# Open in browser
gh repo view --web

# JSON output
gh repo view --json name,description,stargazerCount,url
gh repo view --json name,stargazerCount --jq '.stargazerCount'

JSON fields for repo: archivedAt, assignableUsers, codeOfConduct, createdAt, defaultBranchRef, deleteBranchOnMerge, description, diskUsage, forkCount, hasDiscussionsEnabled, hasIssuesEnabled, hasProjectsEnabled, hasWikiEnabled, homepageUrl, id, isArchived, isEmpty, isFork, isPrivate, isTemplate, languages, latestRelease, licenseInfo, name, nameWithOwner, owner, parent, primaryLanguage, pullRequests, pushedAt, sshUrl, stargazerCount, updatedAt, url, visibility, watchers

List

# Your repos
gh repo list
gh repo list --limit 100

# Another user/org's repos
gh repo list my-org

# Filter
gh repo list --language go --visibility public
gh repo list --topic cli --no-archived
gh repo list --fork        # only forks
gh repo list --source      # only non-forks

# JSON output
gh repo list --json name,stargazerCount --jq '.[] | "\(.name): \(.stargazerCount) stars"'

Edit

# Edit settings
gh repo edit --description "New description"
gh repo edit --homepage "https://example.com"
gh repo edit --enable-issues --enable-wiki
gh repo edit --enable-projects=false
gh repo edit --default-branch main
gh repo edit --enable-auto-merge
gh repo edit --delete-branch-on-merge
gh repo edit --add-topic "cli,automation"
gh repo edit --remove-topic "old-topic"
gh repo edit --template    # make it a template repo

# Change visibility (DANGEROUS — requires acknowledgment)
gh repo edit --visibility public --accept-visibility-change-consequences

Delete / Archive

gh repo delete owner/repo --yes          # requires delete_repo scope
gh repo archive owner/repo --yes
gh repo unarchive owner/repo --yes

Rename

gh repo rename new-name                  # renames current repo
gh repo rename new-name -R owner/repo

Set Default

# Set which remote is used for gh commands in this local clone
gh repo set-default owner/repo
gh repo set-default --view     # see current default
gh repo set-default --unset

Sync (Fork ↔ Upstream)

# Sync local repo from remote parent
gh repo sync

# Sync specific branch
gh repo sync --branch v1

# Sync remote fork from its parent
gh repo sync owner/my-fork

# Sync from a specific source
gh repo sync owner/repo --source owner2/repo2

# Force sync (hard reset)
gh repo sync --force

3. Issues

Create

gh issue create --title "Bug report" --body "Description here"
gh issue create --title "Bug" --label "bug,urgent" --assignee "@me"
gh issue create --title "Feature" --project "Roadmap" --milestone "v2.0"
gh issue create --template "Bug Report"       # use issue template
gh issue create --body-file description.md    # body from file
gh issue create -R owner/repo --title "Bug"   # different repo

List

gh issue list
gh issue list --state closed
gh issue list --state all --limit 100
gh issue list --label "bug" --assignee "@me"
gh issue list --author monalisa
gh issue list --milestone "v2.0"
gh issue list --search "error no:assignee sort:created-asc"

# JSON output
gh issue list --json number,title,labels,state --jq '.[] | "#\(.number) \(.title)"'

JSON fields for issues: assignees, author, body, closed, closedAt, comments, createdAt, id, isPinned, labels, milestone, number, projectCards, projectItems, reactionGroups, state, stateReason, title, updatedAt, url

View

gh issue view 123
gh issue view 123 --web           # open in browser
gh issue view 123 --comments      # include comments
gh issue view 123 --json title,body,labels,assignees

# View by URL
gh issue view https://github.com/owner/repo/issues/123

Edit

gh issue edit 123 --title "New title" --body "New body"
gh issue edit 123 --add-label "bug,help wanted" --remove-label "core"
gh issue edit 123 --add-assignee "@me" --remove-assignee monalisa
gh issue edit 123 --add-project "Roadmap" --remove-project "v1"
gh issue edit 123 --milestone "v2.0"
gh issue edit 123 --remove-milestone
gh issue edit 123 --body-file body.md

# Bulk edit multiple issues
gh issue edit 123 456 789 --add-label "help wanted"

Close / Reopen

gh issue close 123
gh issue close 123 --comment "Fixed in PR #456"
gh issue close 123 --reason "not planned"     # completed | not planned
gh issue reopen 123

Comment

gh issue comment 123 --body "Hello from CLI"
gh issue comment 123 --body-file comment.md
gh issue comment 123 --edit-last              # edit your last comment

Pin / Unpin

gh issue pin 123
gh issue unpin 123

Transfer

gh issue transfer 123 owner/other-repo

Lock / Unlock

gh issue lock 123
gh issue unlock 123

Develop (linked branches)

# Create a branch linked to issue
gh issue develop 123 --checkout
gh issue develop 123 --name "fix-bug-123" --base develop

# List linked branches
gh issue develop 123 --list

Delete

gh issue delete 123 --yes

4. Pull Requests

Create

gh pr create --title "Fix bug" --body "Description"
gh pr create --fill                    # auto-fill title/body from commits
gh pr create --fill-first              # use first commit only
gh pr create --fill-verbose            # use commit messages + bodies
gh pr create --draft                   # create as draft
gh pr create --base develop            # target branch
gh pr create --head owner:feature-branch
gh pr create --reviewer monalisa,hubot --reviewer myorg/team-name
gh pr create --label "bug" --assignee "@me"
gh pr create --project "Roadmap"
gh pr create --milestone "v2.0"
gh pr create --template "pull_request_template.md"
gh pr create --no-maintainer-edit      # prevent maintainers from pushing
gh pr create --dry-run                 # preview without creating

List

gh pr list
gh pr list --state merged --limit 50
gh pr list --state all
gh pr list --author "@me"
gh pr list --assignee monalisa
gh pr list --label "bug" --label "priority"
gh pr list --base main
gh pr list --head feature-branch
gh pr list --draft                     # only drafts
gh pr list --search "status:success review:required"
gh pr list --search "<SHA>" --state merged   # find PR for a commit

# JSON output
gh pr list --json number,title,author,state --jq '.[].title'

JSON fields for PRs: additions, assignees, author, autoMergeRequest, baseRefName, body, changedFiles, closed, closedAt, comments, commits, createdAt, deletions, files, headRefName, headRefOid, id, isDraft, labels, latestReviews, maintainerCanModify, mergeCommit, mergeStateStatus, mergeable, mergedAt, mergedBy, milestone, number, projectItems, reviewDecision, reviewRequests, reviews, state, statusCheckRollup, title, updatedAt, url

View

gh pr view 123
gh pr view 123 --web
gh pr view 123 --comments
gh pr view 123 --json title,body,reviews,mergeable
gh pr view feature-branch              # by branch name

Checkout

gh pr checkout 123
gh pr checkout 123 --branch local-name
gh pr checkout 123 --force             # reset existing local branch
gh pr checkout 123 --recurse-submodules
gh co 123                              # alias

Diff

gh pr diff 123
gh pr diff 123 --name-only             # list changed files
gh pr diff 123 --patch                 # patch format

Merge

gh pr merge 123 --merge                # merge commit
gh pr merge 123 --squash               # squash merge
gh pr merge 123 --rebase               # rebase merge
gh pr merge 123 --squash --delete-branch
gh pr merge 123 --auto --squash        # enable auto-merge
gh pr merge 123 --disable-auto         # disable auto-merge
gh pr merge 123 --admin                # bypass merge queue / requirements
gh pr merge 123 --squash --subject "feat: new feature" --body "Details"

Review

gh pr review 123 --approve
gh pr review 123 --comment --body "LGTM"
gh pr review 123 --request-changes --body "Please fix the tests"
gh pr review                           # review current branch's PR

Checks (CI Status)

gh pr checks 123
gh pr checks 123 --watch               # live-update until done
gh pr checks 123 --watch --fail-fast   # stop on first failure
gh pr checks 123 --required            # only required checks
gh pr checks 123 --json name,state,bucket
gh pr checks 123 --web

# Exit codes: 0=pass, 1=fail, 8=pending

JSON fields for checks: bucket, completedAt, description, event, link, name, startedAt, state, workflow

Edit

gh pr edit 123 --title "New title" --body "New body"
gh pr edit 123 --add-label "bug" --remove-label "wip"
gh pr edit 123 --add-reviewer monalisa --remove-reviewer hubot
gh pr edit 123 --add-assignee "@me"
gh pr edit 123 --add-project "Roadmap"
gh pr edit 123 --base develop          # change target branch
gh pr edit 123 --milestone "v2.0"

Close / Reopen

gh pr close 123
gh pr close 123 --comment "Superseded by #456" --delete-branch
gh pr reopen 123

Ready / Draft

gh pr ready 123           # mark ready for review
gh pr ready 123 --undo    # convert back to draft (requires plan support)

Update Branch

gh pr update-branch 123              # merge base into head
gh pr update-branch 123 --rebase    # rebase head onto base

Comment

gh pr comment 123 --body "Comment text"
gh pr comment 123 --body-file comment.md

Lock / Unlock

gh pr lock 123
gh pr unlock 123

5. GitHub Actions (Runs & Workflows)

Workflow Runs

# List runs
gh run list
gh run list --limit 50
gh run list --workflow build.yml
gh run list --branch main
gh run list --status failure
gh run list --user monalisa
gh run list --event push
gh run list --commit abc123
gh run list --json name,status,conclusion,url

# View a run
gh run view 12345
gh run view 12345 --verbose            # show job steps
gh run view 12345 --log                # full log output
gh run view 12345 --log-failed         # only failed step logs
gh run view 12345 --job 456789         # specific job
gh run view 12345 --job 456789 --log   # specific job logs
gh run view 12345 --attempt 3          # specific attempt
gh run view 12345 --web

# Watch a run (live progress)
gh run watch 12345
gh run watch 12345 --exit-status       # exit non-zero on failure

# Rerun
gh run rerun 12345                     # rerun entire run
gh run rerun 12345 --failed            # rerun only failed jobs
gh run rerun 12345 --debug             # rerun with debug logging
gh run rerun 12345 --job 456789        # rerun specific job

# ⚠️ GOTCHA: --job needs databaseId, NOT the number from the URL!
# Get the right ID:
gh run view 12345 --json jobs --jq '.jobs[] | {name, databaseId}'

# Cancel
gh run cancel 12345

# Delete
gh run delete 12345

# Download artifacts
gh run download 12345                  # all artifacts
gh run download 12345 --name "build-output"
gh run download 12345 --dir ./artifacts
gh run download --name "coverage" --pattern "*.xml"

JSON fields for runs: attempt, conclusion, createdAt, databaseId, displayTitle, event, headBranch, headSha, name, number, startedAt, status, updatedAt, url, workflowDatabaseId, workflowName

Workflows

# List workflows
gh workflow list
gh workflow list --all                  # include disabled

# View a workflow
gh workflow view build.yml
gh workflow view build.yml --web

# Run a workflow (workflow_dispatch)
gh workflow run build.yml
gh workflow run build.yml --ref my-branch
gh workflow run build.yml -f name=value -f env=prod
echo '{"name":"value"}' | gh workflow run build.yml --json

# Enable / disable
gh workflow enable build.yml
gh workflow disable build.yml

6. Releases

Create

# Interactive
gh release create

# With tag + notes
gh release create v1.2.3 --notes "Bug fix release"
gh release create v1.2.3 --generate-notes            # auto-generated notes
gh release create v1.2.3 --notes-from-tag             # from annotated tag
gh release create v1.2.3 -F CHANGELOG.md              # notes from file
gh release create v1.2.3 --draft                      # save as draft
gh release create v1.2.3 --prerelease
gh release create v1.2.3 --latest=false               # don't mark as latest
gh release create v1.2.3 --target release-branch      # tag from specific branch
gh release create v1.2.3 --verify-tag                 # abort if tag doesn't exist
gh release create v1.2.3 --discussion-category "General"

# With assets
gh release create v1.2.3 ./dist/*.tar.gz
gh release create v1.2.3 'binary.zip#Linux Build'     # with display label

List / View

gh release list
gh release list --limit 50
gh release view v1.2.3
gh release view v1.2.3 --web
gh release view --json tagName,publishedAt,assets

Download

gh release download v1.2.3                    # all assets
gh release download v1.2.3 --pattern '*.deb'
gh release download v1.2.3 -p '*.deb' -p '*.rpm'
gh release download v1.2.3 --archive zip      # source code archive
gh release download v1.2.3 --dir ./downloads
gh release download v1.2.3 --output single-file.tar.gz
gh release download --pattern '*.AppImage'    # latest release (no tag arg)

Edit / Upload / Delete

gh release edit v1.2.3 --title "New Title" --notes "Updated notes"
gh release edit v1.2.3 --draft=false          # publish a draft
gh release edit v1.2.3 --prerelease=false
gh release upload v1.2.3 ./new-asset.zip
gh release upload v1.2.3 'asset.tar.gz#Display Label'
gh release delete v1.2.3 --yes
gh release delete-asset v1.2.3 asset-name

7. Gists

# Create
gh gist create file.py                        # secret gist
gh gist create --public file.py               # public gist
gh gist create file.py -d "My Python snippet"
gh gist create file1.py file2.js              # multi-file gist
echo "hello" | gh gist create -               # from stdin
cat data.json | gh gist create --filename data.json

# List
gh gist list
gh gist list --public
gh gist list --secret
gh gist list --limit 50

# View
gh gist view GIST_ID
gh gist view GIST_ID --raw                    # raw content
gh gist view GIST_ID --filename file.py       # specific file

# Edit
gh gist edit GIST_ID
gh gist edit GIST_ID --add newfile.txt
gh gist edit GIST_ID --filename file.py       # edit specific file

# Rename
gh gist rename GIST_ID old-name.py new-name.py

# Clone
gh gist clone GIST_ID

# Delete
gh gist delete GIST_ID

8. Search

Repos

gh search repos "vim plugin"
gh search repos --owner=microsoft --visibility=public
gh search repos --language=go --stars=">1000"
gh search repos --topic=cli,automation
gh search repos --good-first-issues=">=10"
gh search repos --archived=false
gh search repos cli shell --sort stars --limit 10
gh search repos --json fullName,stargazersCount,description

Issues

gh search issues "memory leak"
gh search issues --assignee=@me --state=open
gh search issues --owner=cli --label="bug"
gh search issues --comments=">100"
gh search issues --repo owner/repo "error"
gh search issues -- -label:bug                # exclude label
gh search issues --json number,title,repository,state

Pull Requests

gh search prs "fix bug"
gh search prs --repo=cli/cli --draft
gh search prs --review-requested=@me --state=open
gh search prs --assignee=@me --merged
gh search prs --checks=success --review=approved
gh search prs --json number,title,repository,state

Commits

gh search commits "bug fix"
gh search commits --author=monalisa
gh search commits --committer-date="<2024-01-01"
gh search commits --repo=cli/cli --hash=abc123
gh search commits --json sha,commit,repository

Code

gh search code "TODO" --repo=owner/repo
gh search code "import React" --language=typescript
gh search code "api_key" --filename=".env"
gh search code panic --owner=cli --extension=go
gh search code --json path,repository,textMatches

9. Labels

# List
gh label list
gh label list -R owner/repo
gh label list --json name,color,description

# Create
gh label create "priority:high" --color FF0000 --description "High priority"

# Edit
gh label edit "bug" --name "bug 🐛" --color 00FF00 --description "Something broken"

# Delete
gh label delete "old-label" --yes

# Clone labels from one repo to another
gh label clone source-owner/source-repo --repo dest-owner/dest-repo

10. Secrets & Variables

Secrets (encrypted)

# Set (repo-level, for Actions)
gh secret set MY_SECRET --body "secret-value"
gh secret set MY_SECRET < secret-file.txt
echo "value" | gh secret set MY_SECRET

# Set for specific app
gh secret set MY_SECRET --app dependabot --body "value"
gh secret set MY_SECRET --app codespaces --body "value"

# Set environment secret
gh secret set MY_SECRET --env production --body "value"

# Set org-level secret
gh secret set MY_SECRET --org my-org --visibility all --body "value"
gh secret set MY_SECRET --org my-org --visibility selected --repos repo1,repo2

# Set user secret (for Codespaces)
gh secret set MY_SECRET --user --body "value"

# Bulk set from .env file
gh secret set -f .env

# List
gh secret list
gh secret list --env production
gh secret list --org my-org

# Delete
gh secret delete MY_SECRET
gh secret delete MY_SECRET --env production
gh secret delete MY_SECRET --org my-org

Variables (plaintext)

# Set
gh variable set MY_VAR --body "value"
gh variable set MY_VAR --env staging --body "value"
gh variable set MY_VAR --org my-org --visibility all --body "value"

# Bulk set from .env file
gh variable set -f .env

# Get
gh variable get MY_VAR

# List
gh variable list
gh variable list --env production
gh variable list --org my-org

# Delete
gh variable delete MY_VAR
gh variable delete MY_VAR --env production

11. Caches

# List Actions caches
gh cache list
gh cache list --limit 100
gh cache list --sort size --order desc

# Delete
gh cache delete CACHE_KEY
gh cache delete --all

12. Projects V2

⚠️ Requires project scope: gh auth refresh -s project

Projects V2 uses the GraphQL-based ProjectsV2 API. The CLI provides commands for most operations, but some advanced field mutations require direct GraphQL via gh api graphql.

List Projects

gh project list                           # your projects
gh project list --owner my-org            # org projects
gh project list --owner my-org --closed   # include closed
gh project list --format json             # JSON output

Create

gh project create --owner "@me" --title "My Roadmap"
gh project create --owner my-org --title "Sprint Board"

View

gh project view 1                         # by number
gh project view 1 --owner my-org
gh project view 1 --web                   # open in browser
gh project view 1 --format json

Edit

gh project edit 1 --owner "@me" --title "New Title"
gh project edit 1 --description "Updated description"
gh project edit 1 --readme "Project README content"
gh project edit 1 --visibility PUBLIC     # PUBLIC or PRIVATE

Close / Reopen / Delete

gh project close 1 --owner "@me"
gh project close 1 --owner "@me" --undo   # reopen
gh project delete 1 --owner "@me"

Copy

gh project copy 1 --source-owner monalisa --target-owner my-org --title "Copied Project"
gh project copy 1 --source-owner monalisa --target-owner my-org --drafts  # include drafts

Link / Unlink to Repository or Team

gh project link 1 --owner monalisa --repo my-repo
gh project link 1 --owner my-org --team my-team
gh project unlink 1 --owner monalisa --repo my-repo

Mark as Template

gh project mark-template 1 --owner my-org
gh project mark-template 1 --owner my-org --undo

Fields

# List fields (shows IDs needed for item-edit)
gh project field-list 1 --owner "@me"
gh project field-list 1 --owner "@me" --format json

# Create field
gh project field-create 1 --owner "@me" --name "Priority" --data-type "SINGLE_SELECT" \
  --single-select-options "Low,Medium,High,Critical"
gh project field-create 1 --owner "@me" --name "Points" --data-type "NUMBER"
gh project field-create 1 --owner "@me" --name "Notes" --data-type "TEXT"
gh project field-create 1 --owner "@me" --name "Due Date" --data-type "DATE"

# Delete field
gh project field-delete --id FIELD_NODE_ID

Field data types: TEXT, SINGLE_SELECT, DATE, NUMBER
(Iteration fields must be created via the web UI or GraphQL)

Items

# List items
gh project item-list 1 --owner "@me"
gh project item-list 1 --owner "@me" --limit 100
gh project item-list 1 --owner "@me" --format json

# Add an existing issue/PR to project
gh project item-add 1 --owner "@me" --url https://github.com/owner/repo/issues/123

# Create a draft issue in project
gh project item-create 1 --owner "@me" --title "Draft task" --body "Details"

# Edit a draft issue (title/body)
gh project item-edit --id ITEM_NODE_ID --title "Updated title" --body "Updated body"

# Edit a field value on an item
gh project item-edit --id ITEM_NODE_ID --field-id FIELD_ID --project-id PROJECT_ID \
  --text "some value"
gh project item-edit --id ITEM_NODE_ID --field-id FIELD_ID --project-id PROJECT_ID \
  --number 5
gh project item-edit --id ITEM_NODE_ID --field-id FIELD_ID --project-id PROJECT_ID \
  --date "2024-12-31"
gh project item-edit --id ITEM_NODE_ID --field-id FIELD_ID --project-id PROJECT_ID \
  --single-select-option-id OPTION_ID
gh project item-edit --id ITEM_NODE_ID --field-id FIELD_ID --project-id PROJECT_ID \
  --iteration-id ITERATION_ID

# Clear a field value
gh project item-edit --id ITEM_NODE_ID --field-id FIELD_ID --project-id PROJECT_ID --clear

# Archive / unarchive item
gh project item-archive 1 --owner "@me" --id ITEM_NODE_ID
gh project item-archive 1 --owner "@me" --id ITEM_NODE_ID --undo

# Delete item from project
gh project item-delete 1 --owner "@me" --id ITEM_NODE_ID

Getting Node IDs (Essential for item-edit)

The item-edit command requires node IDs for the item, field, project, and option. Here's how to get them:

# Get project ID and item IDs
gh project item-list 1 --owner "@me" --format json | jq '.'

# Get field IDs and single-select option IDs
gh project field-list 1 --owner "@me" --format json | jq '.'

# Via GraphQL (more control)
gh api graphql -f query='
  query {
    user(login: "USERNAME") {
      projectV2(number: 1) {
        id
        fields(first: 50) {
          nodes {
            ... on ProjectV2SingleSelectField {
              id
              name
              options { id name }
            }
            ... on ProjectV2IterationField {
              id
              name
              configuration {
                iterations { id title startDate duration }
              }
            }
            ... on ProjectV2Field {
              id
              name
              dataType
            }
          }
        }
      }
    }
  }
'

Projects V2 via GraphQL (for what the CLI can't do)

Some operations require direct GraphQL:

# Update a field value (equivalent to item-edit but more flexible)
gh api graphql -f query='
  mutation {
    updateProjectV2ItemFieldValue(input: {
      projectId: "PVT_xxxx"
      itemId: "PVTI_xxxx"
      fieldId: "PVTF_xxxx"
      value: { singleSelectOptionId: "option_id" }
    }) {
      projectV2Item { id }
    }
  }
'

# Add issue/PR to project via GraphQL
gh api graphql -f query='
  mutation {
    addProjectV2ItemById(input: {
      projectId: "PVT_xxxx"
      contentId: "I_xxxx"
    }) {
      item { id }
    }
  }
'

# Update draft issue
gh api graphql -f query='
  mutation {
    updateProjectV2DraftIssue(input: {
      draftIssueId: "DI_xxxx"
      title: "New Title"
      body: "New body"
    }) {
      draftIssue { id title }
    }
  }
'

# Convert draft to real issue
gh api graphql -f query='
  mutation {
    convertProjectV2DraftIssueItemToIssue(input: {
      projectId: "PVT_xxxx"
      itemId: "PVTI_xxxx"
      repositoryId: "R_xxxx"
    }) {
      item {
        id
        content {
          ... on Issue { id number url }
        }
      }
    }
  }
'

# Get all items with field values
gh api graphql -f query='
  query {
    user(login: "USERNAME") {
      projectV2(number: 1) {
        items(first: 100) {
          nodes {
            id
            content {
              ... on Issue { title number url }
              ... on PullRequest { title number url }
              ... on DraftIssue { title body }
            }
            fieldValues(first: 20) {
              nodes {
                ... on ProjectV2ItemFieldTextValue { text field { ... on ProjectV2Field { name } } }
                ... on ProjectV2ItemFieldNumberValue { number field { ... on ProjectV2Field { name } } }
                ... on ProjectV2ItemFieldDateValue { date field { ... on ProjectV2Field { name } } }
                ... on ProjectV2ItemFieldSingleSelectValue { name field { ... on ProjectV2SingleSelectField { name } } }
                ... on ProjectV2ItemFieldIterationValue { title field { ... on ProjectV2IterationField { name } } }
              }
            }
          }
        }
      }
    }
  }
'

Projects V2 Workflow (Complete Example)

# 1. Create a project
gh project create --owner "@me" --title "Sprint 1"

# 2. Add fields
gh project field-create 1 --owner "@me" --name "Status" \
  --data-type SINGLE_SELECT --single-select-options "Todo,In Progress,Done"
gh project field-create 1 --owner "@me" --name "Priority" \
  --data-type SINGLE_SELECT --single-select-options "Low,Medium,High"
gh project field-create 1 --owner "@me" --name "Points" --data-type NUMBER

# 3. Get field IDs
FIELDS=$(gh project field-list 1 --owner "@me" --format json)
echo "$FIELDS" | jq '.'

# 4. Add issues to project
gh project item-add 1 --owner "@me" --url https://github.com/owner/repo/issues/1
gh project item-add 1 --owner "@me" --url https://github.com/owner/repo/issues/2

# 5. Create draft issues
gh project item-create 1 --owner "@me" --title "Research task" --body "Investigate X"

# 6. Set field values on items (need IDs from steps 3-5)
gh project item-edit --id ITEM_ID --field-id STATUS_FIELD_ID \
  --project-id PROJECT_ID --single-select-option-id TODO_OPTION_ID

# 7. Link project to repo
gh project link 1 --owner "@me" --repo my-repo

13. API (REST & GraphQL)

REST API

# GET request (default)
gh api repos/{owner}/{repo}
gh api repos/cli/cli/releases --jq '.[].tag_name'

# With query parameters
gh api -X GET search/issues -f q='repo:cli/cli is:open label:bug'

# POST request
gh api repos/{owner}/{repo}/issues -f title="New Issue" -f body="Description"
gh api repos/{owner}/{repo}/issues/123/comments -f body='Comment text'

# PATCH / PUT / DELETE
gh api -X PATCH repos/{owner}/{repo} -f description="Updated"
gh api -X DELETE repos/{owner}/{repo}/issues/123/labels/bug

# With typed fields (-F for auto-type-conversion, -f for raw strings)
gh api repos/{owner}/{repo}/issues -f title="Bug" -F private=true -F number:=42

# Request body from file
gh api repos/{owner}/{repo}/issues --input issue.json

# Custom headers
gh api -H 'Accept: application/vnd.github.v3.raw+json' repos/{owner}/{repo}/readme

# Include response headers
gh api -i repos/{owner}/{repo}

# Verbose output (shows full HTTP request/response)
gh api --verbose repos/{owner}/{repo}

# Silent (no output)
gh api --silent repos/{owner}/{repo}/issues/123/labels -f labels[]=bug

# Caching
gh api --cache 3600s repos/{owner}/{repo}/releases

Placeholders

The special placeholders {owner}, {repo}, and {branch} are auto-populated from the current git directory or GH_REPO.

Pagination

# Auto-paginate REST results
gh api --paginate repos/{owner}/{repo}/issues --jq '.[].title'

# Slurp all pages into single array
gh api --paginate --slurp repos/{owner}/{repo}/issues | jq 'flatten | length'

GraphQL API

# Basic query
gh api graphql -f query='{ viewer { login } }'

# With variables
gh api graphql -F owner='{owner}' -F name='{repo}' -f query='
  query($owner: String!, $name: String!) {
    repository(owner: $owner, name: $name) {
      releases(last: 5) {
        nodes { tagName publishedAt }
      }
    }
  }
'

# Mutation
gh api graphql -f query='
  mutation {
    addStar(input: {starrableId: "MDEwOlJlcG9zaXRvcnkxMjM="}) {
      starrable { stargazerCount }
    }
  }
'

# Paginated GraphQL (requires $endCursor variable and pageInfo)
gh api graphql --paginate -f query='
  query($endCursor: String) {
    viewer {
      repositories(first: 100, after: $endCursor) {
        nodes { nameWithOwner }
        pageInfo { hasNextPage endCursor }
      }
    }
  }
'

# GraphQL with JQ filtering
gh api graphql -f query='{ viewer { repositories(first: 10) { nodes { nameWithOwner stargazerCount } } } }' \
  --jq '.data.viewer.repositories.nodes[] | "\(.nameWithOwner): \(.stargazerCount) ⭐"'

Common GraphQL Patterns

# Get repository ID (needed for many mutations)
gh api graphql -f query='query { repository(owner: "OWNER", name: "REPO") { id } }' \
  --jq '.data.repository.id'

# Get issue/PR node ID
gh api graphql -f query='
  query {
    repository(owner: "OWNER", name: "REPO") {
      issue(number: 123) { id }
    }
  }
' --jq '.data.repository.issue.id'

# Get user/org ID
gh api graphql -f query='query { user(login: "USERNAME") { id } }' --jq '.data.user.id'

# Check rate limit
gh api graphql -f query='{ rateLimit { limit remaining resetAt } }'
gh api rate_limit --jq '.rate'

14. Extensions

# Search for extensions
gh extension search "copilot"
gh extension search --limit 30

# Browse extensions in TUI
gh extension browse

# Install
gh extension install owner/gh-extension-name
gh extension install https://github.com/owner/gh-extension-name

# List installed
gh extension list

# Upgrade
gh extension upgrade extension-name
gh extension upgrade --all

# Remove
gh extension remove extension-name

# Execute (useful if name conflicts with core command)
gh extension exec extension-name

# Create a new extension
gh extension create my-extension
gh extension create my-extension --precompiled=go

15. Codespaces

# List
gh codespace list

# Create
gh codespace create --repo owner/repo
gh codespace create --repo owner/repo --branch feature --machine largePremiumLinux

# SSH into codespace
gh codespace ssh

# Open in VS Code
gh codespace code

# Copy files
gh codespace cp local-file.txt remote:~/path/
gh codespace cp remote:~/path/file.txt ./local/

# View details
gh codespace view

# Port forwarding
gh codespace ports

# Rebuild
gh codespace rebuild

# Stop / Delete
gh codespace stop
gh codespace delete

16. Copilot

(Requires gh-copilot extension)

# Suggest a command
gh copilot suggest "find large files in current directory"

# Explain a command
gh copilot explain "find . -type f -size +100M -exec ls -lh {} +"

# Configure
gh copilot config

17. Other Commands

Browse (open in browser)

gh browse                          # repo home
gh browse 123                      # issue or PR #123
gh browse src/main.go              # specific file
gh browse src/main.go:42           # file at line
gh browse --settings               # repo settings
gh browse --projects                # repo projects
gh browse --releases                # repo releases
gh browse --branch feature src/    # specific branch
gh browse --commit abc123          # specific commit
gh browse -n                       # print URL instead of opening

Status (cross-repo overview)

gh status                          # assigned issues, PRs, review requests, mentions
gh status --org my-org             # limit to org
gh status -e owner/repo            # exclude repo

Aliases

gh alias set pv 'pr view'
gh alias set bugs 'issue list --label=bug'
gh alias set --shell igrep 'gh issue list --label="$1" | grep "$2"'
gh alias list
gh alias delete pv
gh alias import aliases.yml

SSH Keys / GPG Keys

gh ssh-key list
gh ssh-key add ~/.ssh/id_ed25519.pub --title "My Laptop"
gh ssh-key delete KEY_ID

gh gpg-key list
gh gpg-key add pubkey.gpg
gh gpg-key delete KEY_ID

Rulesets

gh ruleset list
gh ruleset view RULESET_ID
gh ruleset check branch-name      # what rules apply to this branch

Attestations

gh attestation verify artifact.tar.gz --owner owner
gh attestation download --owner owner artifact.tar.gz

Org

gh org list

18. JSON Output & Formatting

Most listing/view commands support --json, --jq, and --template flags.

Basic JSON

# Discover available fields (pass --json with no value)
gh pr list --json

# Select specific fields
gh pr list --json number,title,author

# JQ filtering
gh pr list --json number,title,author --jq '.[].author.login'
gh issue list --json number,title,labels --jq '
  map(select(.labels | length > 0))
  | map(.labels = (.labels | map(.name)))
  | .[:5]
'

Go Template Formatting

# Table output
gh pr list --json number,title,headRefName,updatedAt --template \
  '{{range .}}{{tablerow (printf "#%v" .number | autocolor "green") .title .headRefName (timeago .updatedAt)}}{{end}}'

# Hyperlinks
gh issue list --json title,url --template \
  '{{range .}}{{hyperlink .url .title}}{{"\n"}}{{end}}'

# Color
gh pr list --json title,state --template \
  '{{range .}}{{.title}} ({{.state | color "green"}}){{"\n"}}{{end}}'

Template Functions

19. Environment Variables

20. Advanced Patterns

Scripting Best Practices

# Disable prompts for non-interactive use
GH_PROMPT_DISABLED=1 gh pr create --fill

# Use GH_TOKEN for CI/automation
GH_TOKEN=${{ github.token }} gh pr list

# Use GH_REPO to avoid -R everywhere
export GH_REPO=owner/repo
gh issue list   # targets owner/repo

Batch Operations

# Close all issues with a label
gh issue list --label "wontfix" --json number --jq '.[].number' | \
  xargs -I{} gh issue close {} --reason "not planned"

# Add label to all open PRs
gh pr list --json number --jq '.[].number' | \
  xargs -I{} gh pr edit {} --add-label "needs-review"

# Download all artifacts from recent failed runs
gh run list --status failure --json databaseId --jq '.[].databaseId' | \
  xargs -I{} gh run download {}

Working with Multiple Accounts

# List configured accounts
gh auth status

# Switch active account
gh auth switch

# Use a specific token for one command
GH_TOKEN=ghp_xxx gh api user --jq '.login'

# Login to multiple hosts
gh auth login --hostname github.com
gh auth login --hostname github.enterprise.com

Rate Limiting

# Check current rate limit
gh api rate_limit --jq '.rate | "\(.remaining)/\(.limit) (resets \(.reset | strftime("%H:%M:%S")))"'

# GraphQL rate limit (separate pool)
gh api graphql -f query='{ rateLimit { limit remaining resetAt } }'

# Use caching to reduce API calls
gh api --cache 3600s repos/{owner}/{repo}/releases

Complex API Patterns

# Nested parameters
gh api gists -F 'files[myfile.txt][content]=@myfile.txt'

# Array parameters
gh api -X PATCH /orgs/{org}/properties/schema \
  -F 'properties[][property_name]=env' \
  -F 'properties[][allowed_values][]=staging' \
  -F 'properties[][allowed_values][]=production'

# Combine REST pagination with JQ
gh api --paginate repos/{owner}/{repo}/issues --jq '[.[] | select(.labels | length > 0)] | length'

# GraphQL with slurp for aggregation
gh api graphql --paginate --slurp -f query='
  query($endCursor: String) {
    viewer {
      repositories(first: 100, after: $endCursor) {
        nodes { isFork stargazerCount }
        pageInfo { hasNextPage endCursor }
      }
    }
  }
' | jq '[.[].data.viewer.repositories.nodes[]] | map(.stargazerCount) | add'

21. Tips & Gotchas

Common Mistakes

1. --json field names differ from API field names. For example, PR files use files (not changed_files), author uses author.login (not user.login). Always run gh <cmd> --json without arguments to see available fields.

2. gh run rerun --job needs databaseId, not the URL number. Get it with:

   gh run view RUN_ID --json jobs --jq '.jobs[] | {name, databaseId}'
   

3. Projects V2 require the project scope. If you get permission errors:

   gh auth refresh -s project
   

4. gh repo delete requires delete_repo scope:

   gh auth refresh -s delete_repo
   

5. Subcommand quoting in shells: PowerShell and some shells need {owner} escaped. Use quotes: "{owner}".

When to Use gh api vs Specific Commands

Performance Tips

• Use --limit to fetch only what you need
• Use --json with specific fields (fetches less data)
• Use --cache with gh api for frequently accessed, slowly changing data
• Use --paginate --slurp for aggregations across all pages
• Set GH_PAGER=cat to disable paging in scripts

Exit Codes

Authentication Precedence

1. GH_TOKEN / GITHUB_TOKEN environment variable
2. GH_ENTERPRISE_TOKEN (for GHES hosts)
3. Stored credentials from gh auth login
4. .env file in repo (only if configured)

Useful One-Liners

# My open PRs across all repos
gh search prs --author=@me --state=open --json repository,number,title

# Repos I starred recently
gh api --paginate user/starred --jq '.[].full_name' | head -20

# Who's the top contributor to a repo
gh api --paginate repos/owner/repo/contributors --jq '.[] | "\(.login): \(.contributions)"' | head -10

# Create issue from clipboard
pbpaste | gh issue create --title "From clipboard" --body-file -

# Get latest release tag
gh release view --json tagName --jq '.tagName'

# Watch CI and notify on completion
gh run watch && notify-send "CI done!"

# Export all issues as JSON
gh issue list --state all --limit 9999 --json number,title,state,labels,assignees > issues.json

# Find which PR merged a commit
gh pr list --search "SHA_HERE" --state merged --json number,title,url