Skill: Complete GitHub CLI (cli-trunk)

Use gh to operate GitHub end-to-end from the command line. This skill is built from the cli-trunk source code and is meant for practical, reproducible command execution.

Goal

• Solve GitHub tasks with precise and repeatable gh commands.
• Pick the right command family by domain: PRs, Issues, repositories, Actions, releases, configuration, security, and API.
• Prefer structured output (--json, --jq) whenever automation is needed.

Install GitHub CLI on Linux

Use official packages when possible.

Debian and Ubuntu (official repository)

(type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \
  && sudo mkdir -p -m 755 /etc/apt/keyrings \
  && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
  && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
  && sudo mkdir -p -m 755 /etc/apt/sources.list.d \
  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
  && sudo apt update \
  && sudo apt install gh -y

Upgrade:

sudo apt update
sudo apt install gh

RPM-based distros (DNF5)

sudo dnf install dnf5-plugins
sudo dnf config-manager addrepo --from-repofile=https://cli.github.com/packages/rpm/gh-cli.repo
sudo dnf install gh --repo gh-cli

Upgrade:

sudo dnf update gh

RPM-based distros (DNF4)

sudo dnf install 'dnf-command(config-manager)'
sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
sudo dnf install gh --repo gh-cli

Amazon Linux 2 (yum)

type -p yum-config-manager >/dev/null || sudo yum install yum-utils
sudo yum-config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
sudo yum install gh

openSUSE and SUSE (zypper)

sudo zypper addrepo https://cli.github.com/packages/rpm/gh-cli.repo
sudo zypper ref
sudo zypper install gh

Alternative official methods

• Homebrew on Linux:

brew install gh

• Precompiled binaries: https://github.com/cli/cli/releases/latest

Verify installation

gh --version

Login and Authentication (Do This First)

Most gh commands require authentication. Use one of these methods.

Interactive login (recommended for local development)

gh auth login
gh auth status
gh auth setup-git

What this does:

• gh auth login: signs you in (browser/device flow) and stores credentials.
• gh auth status: confirms active account, host, and token scopes.
• gh auth setup-git: configures git credential helper integration.

GitHub Enterprise Server login

gh auth login --hostname github.example.com
gh auth status --hostname github.example.com

Token-based login (CI/non-interactive)

export GH_TOKEN=\x3Cyour_token>
gh auth status

Notes:

• GH_TOKEN / GITHUB_TOKEN are used for github.com.
• GH_ENTERPRISE_TOKEN / GITHUB_ENTERPRISE_TOKEN are used for GHES hosts.

Common auth lifecycle commands

gh auth refresh -s repo,read:org,project
gh auth switch
gh auth logout

• gh auth refresh: updates token scopes.
• gh auth switch: switches between authenticated accounts/hosts.
• gh auth logout: removes stored credentials for a host.

Notes:

• Official Linux installation documentation in this repo: cli-trunk/docs/install_linux.md.
• Recommended official package host: https://cli.github.com/

Operating Rules

• If you are not inside a local git repository, use --repo OWNER/REPO or a full URL.
• For automation, prefer:
  • --json \x3Cfields> for structured output.
  • --jq '\x3Cfilter>' for JSON filtering.
• For large listings and searches, cap output with --limit.
• If no dedicated subcommand exists, use gh api.

Syntax and Patterns

• Required placeholder: \x3Cvalue>.
• Optional argument: [--flag] or [\x3Carg>].
• Exclusive alternatives: {a | b} or [a | b] depending on required vs optional.
• Repeatable arguments: \x3Carg>....

Root Commands (Complete Map)

• gh pr (pull requests)
• gh issue (issues)
• gh repo (repositories)
• gh release (releases)
• gh run (workflow runs)
• gh workflow (workflows)
• gh auth (authentication)
• gh config (configuration)
• gh project (GitHub Projects)
• gh secret (secrets)
• gh variable (Actions variables)
• gh search (global search)
• gh gist (gists)
• gh extension / gh ext (extensions)
• gh codespace / gh cs (Codespaces)
• gh org (organizations)
• gh ruleset / gh rs (rulesets)
• gh cache (Actions cache)
• gh label (labels)
• gh ssh-key (SSH keys)
• gh gpg-key (GPG keys)
• gh attestation / gh at (artifact attestations)
• gh agent-task / gh agent (preview)
• gh api (REST/GraphQL API)
• gh browse (open in browser)
• gh status (cross-repo status)
• gh copilot (preview)
• gh completion (shell completion)
• gh licenses (third-party licenses)
• gh preview (experimental commands)
• gh actions (hidden; guidance text)
• gh accessibility / gh a11y (hidden; accessibility)
• gh credits (hidden)
• gh version (hidden)

Subcommands by Domain

Pull Requests: gh pr

• list, create, status
• view, diff, checkout, checks, review, merge, update-branch, ready, comment, close, reopen, revert, edit, lock, unlock

Examples:

gh pr list --repo OWNER/REPO --limit 20
gh pr view 123 --repo OWNER/REPO --json number,title,state,author
gh pr checks 123 --repo OWNER/REPO

Issues: gh issue

• list, create, status
• view, comment, close, reopen, edit, develop, lock, unlock, pin, unpin, transfer, delete

Examples:

gh issue list --repo OWNER/REPO --limit 50
gh issue view 456 --repo OWNER/REPO --json number,title,state,labels
gh issue create --repo OWNER/REPO --title "Bug" --body "Details"

Repositories: gh repo

• list, create
• view, clone, fork, set-default, sync, edit, deploy-key, license, gitignore, rename, archive, unarchive, delete, credits, garden, autolink

Examples:

gh repo view OWNER/REPO --web
gh repo list OWNER --limit 100
gh repo sync OWNER/REPO

Releases: gh release

• list, create
• view, edit, upload, download, delete, delete-asset, verify, verify-asset

Examples:

gh release list --repo OWNER/REPO
gh release view v1.2.3 --repo OWNER/REPO
gh release download v1.2.3 --repo OWNER/REPO

GitHub Actions: gh run, gh workflow, gh cache

• gh run: list, view, rerun, download, watch, cancel, delete
• gh workflow: list, enable, disable, view, run
• gh cache: list, delete

Examples:

gh run list --repo OWNER/REPO --limit 10
gh run view \x3Crun-id> --repo OWNER/REPO --log-failed
gh workflow run ci.yml --repo OWNER/REPO

Authentication and Config: gh auth, gh config

• gh auth: login, logout, status, refresh, git-credential, setup-git, token, switch
• gh config: get, set, list, clear-cache

Examples:

gh auth status
gh auth refresh -s repo,read:org
gh config set git_protocol ssh

Projects: gh project

• Project-level: list, create, copy, close, delete, edit, link, view, mark-template, unlink
• Items: item-list, item-create, item-add, item-edit, item-archive, item-delete
• Fields: field-list, field-create, field-delete

Examples:

gh project list --owner ORG
gh project view 1 --owner ORG --web
gh project item-list 1 --owner ORG

Secrets and Variables: gh secret, gh variable

• gh secret: list, set, delete
• gh variable: get, set, list, delete

Examples:

gh secret list --repo OWNER/REPO
gh secret set MY_SECRET --repo OWNER/REPO --body "value"
gh variable set MY_VAR --repo OWNER/REPO --body "value"

Global Search: gh search

• code, commits, issues, prs, repos

Examples:

gh search prs "is:open review:required org:ORG"
gh search code "function NewCmd" --repo OWNER/REPO

PowerShell note: for queries containing negative qualifiers (-qualifier), use stop-parsing with --%.

Gists, Labels, and Keys

• gh gist: clone, create, list, view, edit, delete, rename
• gh label: list, create, clone, edit, delete
• gh ssh-key: add, delete, list
• gh gpg-key: add, delete, list

Codespaces: gh codespace (gh cs)

• code, create, edit, delete, jupyter, list, view, logs, ports, ssh, cp, stop, select, rebuild

Examples:

gh cs list
gh cs ssh -c \x3Ccodespace>
gh cs ports -c \x3Ccodespace>

Extensions: gh extension (gh ext)

• search, list, install, upgrade, remove, browse, exec, create

Examples:

gh ext search
gh ext install owner/gh-myext
gh ext exec myext -- --help

Rulesets, Org, Attestation, Agent Task

• gh ruleset: list, view, check
• gh org: list
• gh attestation: download, inspect, verify, trustedroot
• gh agent-task (preview): list, create, view

Examples:

gh ruleset list --repo OWNER/REPO
gh at verify -R OWNER/REPO ./artifact.zip
gh agent-task list

Useful Standalone Commands

• gh browse (issues, PRs, paths, commits, settings, releases, wiki, actions)
• gh api (authenticated REST/GraphQL)
• gh status (issues, PRs, mentions, activity)
• gh copilot (preview)
• gh completion -s {bash|zsh|fish|powershell}
• gh licenses

Complete Command Explanations (All Root Commands)

This section explains each root command in plain language and points to its key subcommands.

Collaboration and Code Review

• gh pr: manage pull requests from creation to merge.
  • Main subcommands: list, view, create, status, checks, review, merge, checkout, diff, update-branch, ready, comment, edit, close, reopen, revert, lock, unlock.
• gh issue: manage issue lifecycle and discussion.
  • Main subcommands: list, view, create, status, comment, edit, develop, close, reopen, transfer, delete, pin, unpin, lock, unlock.
• gh label: create and maintain repository labels.
  • Main subcommands: list, create, clone, edit, delete.

Repositories and Releases

• gh repo: administer repositories.
  • Main subcommands: list, view, create, clone, fork, sync, set-default, edit, rename, archive, unarchive, delete, autolink, deploy-key, license, gitignore, credits, garden.
• gh release: create, publish, inspect, and verify releases.
  • Main subcommands: list, view, create, edit, upload, download, delete, delete-asset, verify, verify-asset.
• gh gist: work with GitHub Gists.
  • Main subcommands: list, view, create, edit, rename, clone, delete.

Actions, CI, and Workflow Automation

• gh run: inspect and control workflow runs.
  • Main subcommands: list, view, watch, rerun, download, cancel, delete.
• gh workflow: inspect and trigger workflow files.
  • Main subcommands: list, view, run, enable, disable.
• gh cache: manage GitHub Actions cache entries.
  • Main subcommands: list, delete.

Projects, Organization, and Governance

• gh project: manage GitHub Projects (project, item, and field operations).
  • Main subcommands: list, view, create, edit, delete, copy, close, link, unlink, mark-template, plus item-* and field-* families.
• gh org: organization-level operations.
  • Main subcommands: list.
• gh ruleset: inspect and evaluate repository rulesets.
  • Main subcommands: list, view, check.

Security, Secrets, and Identity

• gh auth: account and token authentication lifecycle.
  • Main subcommands: login, status, refresh, setup-git, token, switch, logout, git-credential.
• gh secret: manage secrets at repository/org/environment/user scope.
  • Main subcommands: list, set, delete.
• gh variable: manage Actions/Dependabot variables.
  • Main subcommands: list, get, set, delete.
• gh ssh-key: manage SSH keys on your GitHub account.
  • Main subcommands: list, add, delete.
• gh gpg-key: manage GPG keys on your GitHub account.
  • Main subcommands: list, add, delete.
• gh attestation: download, inspect, and verify artifact attestations.
  • Main subcommands: download, inspect, verify, trustedroot.

Discovery and Navigation

• gh search: search code, commits, issues, PRs, and repositories on GitHub.
  • Main subcommands: code, commits, issues, prs, repos.
• gh browse: open repo pages, files, issues, PRs, commits, and settings in your browser.
  • Useful flags: --branch, --commit, --settings, --wiki, --projects, --actions, --blame, --no-browser.
• gh status: aggregated dashboard of assigned issues, PRs, review requests, mentions, and activity.
  • Useful flags: --org, --exclude.

Extensions, Aliases, and Developer Experience

• gh extension (gh ext): discover/install/manage CLI extensions.
  • Main subcommands: search, list, install, upgrade, remove, browse, exec, create.
• gh alias: create and manage command shortcuts.
  • Main subcommands: set, list, delete, import.
• gh completion: generate shell completion scripts.
  • Main usage: gh completion -s bash|zsh|fish|powershell.
• gh config: read and update CLI behavior.
  • Main subcommands: get, set, list, clear-cache.

API and Advanced Power Tools

• gh api: send authenticated REST/GraphQL requests when built-in subcommands are not enough.
  • Important options: --method, --field, --raw-field, --input, --paginate, --slurp, --jq, --template, --header, --hostname, --preview.
• gh codespace (gh cs): manage Codespaces.
  • Main subcommands: list, create, view, edit, logs, ports, ssh, stop, delete, rebuild, code, cp, jupyter, select.
• gh agent-task (gh agent) (preview): create/list/view Copilot agent tasks.
  • Main subcommands: create, list, view.
• gh copilot (preview): run GitHub Copilot CLI via gh.

Informational and Hidden Commands

• gh licenses: view third-party license info for the current gh build.
• gh preview: run unstable preview commands (currently includes preview tools such as prompter).
• gh actions (hidden): informational help text about Actions command groups.
• gh accessibility / gh a11y (hidden): accessibility guidance and related configuration pointers.
• gh credits (hidden): credits animation/static credits.
• gh version (hidden): print current gh version/build info.

Advanced API Usage

Use gh api when no dedicated subcommand exists or when you need custom payload/query control.

REST examples:

gh api repos/{owner}/{repo}/pulls/123
gh api repos/{owner}/{repo}/issues -X GET -f state=open -f per_page=100

GraphQL examples:

gh api graphql -f query='query { viewer { login } }'
gh api graphql --paginate -f query='query($endCursor: String) { viewer { repositories(first: 100, after: $endCursor) { nodes { nameWithOwner } pageInfo { hasNextPage endCursor } } } }'

Quick Recipes by Intent

• Show PRs with failing checks:

gh pr list --repo OWNER/REPO --json number,title,statusCheckRollup --jq '.[] | select(any(.statusCheckRollup[]?; .conclusion=="FAILURE")) | {number,title}'

• Get open issues in a compact format:

gh issue list --repo OWNER/REPO --json number,title,author --jq '.[] | "#\(.number) \(.title) (@\(.author.login))"'

• Fast Actions diagnosis:

gh run list --repo OWNER/REPO --limit 5
gh run view \x3Crun-id> --repo OWNER/REPO --log-failed

Command Selection Heuristic

• If the task is about PRs or Issues, start with gh pr or gh issue.
• If it is CI/CD related, use gh run, gh workflow, and gh cache.
• If it is repository administration, use gh repo.
• If it is governance/security, use gh ruleset, gh secret, gh variable, and gh attestation.
• If no clear coverage exists, use gh api.

Diagnostics and Common Errors

• Authentication issues: run gh auth status, then gh auth login or gh auth refresh -s \x3Cscopes>.
• Unresolved repository context: run inside a valid git repo or pass --repo OWNER/REPO.
• Ambiguous PR/Issue selectors: use full URL or explicit number.
• In scripts, avoid human-oriented output; use --json + --jq.

Completeness Criterion

This skill covers the full command catalog visible in pkg/cmd/root/root.go and subcommands registered in pkg/cmd/* modules within cli-trunk.