Reference

Interactivity policy

gh already does the right thing in non-TTY contexts: it skips the pager, strips ANSI color, and errors out fast with a helpful message instead of prompting (e.g. must provide --title and --body when not running interactively). You don't need to defensively set GH_PAGER or pass --no-pager (no such flag exists).

Parsing JSON

Human output from gh is column-formatted. If you want structured data:

• Add --json field1,field2,... for structured output.
• Run a command with --json and no field list to print the full set of

available fields, then pick what you need.

• Use --jq '<expr>' for filtering without piping through a separate jq.
• Use --template '<go-template>' (alongside --json) when you want shaped

text output. Note that --template/-T collides with a body-template flag on a few commands (e.g. gh pr create -T, gh issue create -T); always check --help before assuming which one you're hitting.

Pagination and silent truncation

List commands cap results.

• gh issue list, gh pr list, gh search ...: pass -L N (--limit N).

The default is usually 30.

• gh issue list / gh pr list do not expose aggregate totals like

totalCount via --json. If you need a true total, use gh api graphql to query totalCount; otherwise, treat -L as the cap for the current call.

• For raw API calls use gh api --paginate <path>. Combine with

--jq and (optionally) --slurp to assemble one array.

Repo targeting

gh infers the repo from the cwd's git remotes.

Pass --repo OWNER/REPO (-R) to override the resolved CWD repo.

Search vs list

• gh search issues|prs|code|repos|commits|users uses GitHub's search

index and accepts the full search syntax (is:open, author:, label:, repo:owner/name, in:title, ...). Pass the entire query as one quoted string, the same way you would for --search: gh search issues "is:open author:foo repo:cli/cli". Prefer it for anything cross-repo or filtered by author/label.

• gh issue list --search "..." and gh pr list --search "..." accept

the same syntax but are scoped to one repo.

Fall back to gh api for anything --json doesn't expose

Sometimes useful data isn't on the typed commands. Examples:

• Review-thread comments on a PR: gh api repos/{owner}/{repo}/pulls/{n}/comments

(the --comments flag on gh pr view shows issue-level comments only).

• Arbitrary GraphQL: gh api graphql -f query='...' -F var=value.
• REST shortcuts: gh api repos/{owner}/{repo}/... - note the

{owner}/{repo} placeholder is filled in for you when run from a repo with detected remotes; pass them literally if you want determinism.

Authentication

• gh auth status prints the active host(s), user, and which env var (if

any) is being honored.

• gh auth status --json is supported.

Other notes

• gh pr checkout <n> switches branches. Use gh pr diff <n> or

gh pr view <n> if you only need to read.

• NO_COLOR, CLICOLOR_FORCE, and GH_FORCE_TTY are honored. Set

GH_FORCE_TTY=1 if you want TTY-style output (colors, tables, the pager, interactivity) inside an agent harness; leave it unset unless needed.