GitHub CLI

Overview

Use gh for day-to-day GitHub operations from the terminal. Prefer read-only commands first, then run mutating commands only after clear user intent.

Quick Start

1. Check installation and auth:

gh --version
gh auth status

1. Establish repository context:

scripts/gh_preflight.sh --repo owner/repo

1. If not in the target repository, pass -R owner/repo to commands.
2. Use --json with --jq or --template for automation-friendly output.

Workflow

1. Establish context first.

• Determine GitHub host (github.com by default), repository, and branch.
• Run scripts/gh_preflight.sh before multi-step operations.

1. Read current state.

• Use list, view, and status subcommands before changing anything.

1. Apply requested mutation.

• For create/edit/merge/delete actions, restate the operation and require explicit confirmation unless the user already asked clearly.

1. Report stable identifiers.

• Return URLs and IDs for created or changed objects (PR number, issue number, run URL, release tag).

Common Commands

• Repository:
• gh repo view
• gh repo clone owner/repo
• gh repo create
• gh repo set-default owner/repo
• Pull requests:
• gh pr list
• gh pr view <number>
• gh pr checkout <number>
• gh pr create
• gh pr review <number> --approve|--request-changes|--comment
• gh pr merge <number>
• Issues:
• gh issue list
• gh issue view <number>
• gh issue create
• gh issue comment <number> --body "..."
• gh issue close <number>
• Actions:
• gh workflow list
• gh workflow run <workflow>
• gh run list
• gh run watch <run-id>
• gh run view <run-id> --log
• Releases:
• gh release list
• gh release view <tag>
• gh release create <tag> [assets...]
• gh release upload <tag> <file>
• API:
• gh api repos/{owner}/{repo}/pulls --paginate

For broader command coverage, read references/command-map.md.

Safety Defaults

• Confirm before commands that change remote state:
• gh pr create|merge|close|reopen|ready
• gh issue create|edit|close|reopen|delete
• gh repo create|edit|archive|delete
• gh release create|edit|delete
• gh secret set|delete
• gh variable set|delete
• gh workflow run
• Avoid destructive flags (--delete-branch, force flags) unless explicitly requested.
• Show exact command before bulk updates and prefer smallest safe scope.

Structured Output

Use JSON output when parsing or summarizing results:

gh pr list --json number,title,url --jq '.[] | "\(.number)\t\(.title)\t\(.url)"'
gh issue list --json number,title,labels --template '{{range .}}{{printf "#%v %v\n" .number .title}}{{end}}'

Troubleshooting

• Auth errors: gh auth login or gh auth refresh.
• Wrong account/host: gh auth status --hostname github.com, then gh auth switch.
• Unknown command options: gh <command> <subcommand> --help.
• Manual reference: https://cli.github.com/manual/.

Resources

scripts/

• scripts/gh_preflight.sh: Check gh availability, auth status, and repository context.

references/

• references/command-map.md: Command map for repo, PR, issue, actions, release, and API operations.