Patterns for invoking the GitHub CLI (gh) from agents. Covers structured output, pagination, repo targeting, search vs list, gh api fallback.
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.
