gh-cli

description	Patterns for invoking the GitHub CLI (gh) from agents. Covers structured output, pagination, repo targeting, search vs list, gh api fallback. Use when calling GitHub CLI, namely the `gh` command.
name	gh-cli

gh CLI

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.

Issue Types, Sub-Issues, and Relationships

Newer gh issue subcommands model issue types, sub-issue hierarchy, and blocked-by/blocking relationships.

• gh issue create: --type <name>, --parent <number|url> (creates the new issue as a sub-issue), --blocked-by <number|url,...>, --blocking <number|url,...>.
• gh issue edit (edits one or more issues in the same repo, e.g. gh issue edit 23 34): --type <name> / --remove-type, --parent <n|url> / --remove-parent, --add-sub-issue <n,n> / --remove-sub-issue <n,n>, --add-blocked-by <n,n> / --remove-blocked-by <n,n>, --add-blocking <n,n> / --remove-blocking <n,n>. Relationship and parent refs are issue numbers or URLs; a URL may point to another repo on the same host, but a different host is rejected. --add-sub-issue cannot be used when editing more than one issue.
• gh issue list --type <name> filters by issue type.
• gh issue view and gh issue list accept these as --json fields (prefer them over scraping the default text output): issueType, parent, subIssues, subIssuesSummary, blockedBy, blocking. subIssues, blockedBy, and blocking are objects shaped {"nodes": [...], "totalCount": N} (not flat arrays), and nodes is capped (subIssues at 100, blockedBy/blocking at 50), so compare the node count against totalCount to detect truncation.
• GHES: issue types and sub-issues need 3.17+; blocked-by/blocking relationships need 3.19+.

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.

Writing Descriptions and Comments

GitHub's Markdown renderer diverges from CommonMark on line breaks: consecutive lines without a blank line between them are rendered as separate lines (unlike standard Markdown where they are joined). Therefore, do NOT hard-wrap long lines in issue/PR descriptions or comments. Let each paragraph stay a single long line.

// Standard CommonMark: renders as one joined line
This is the first line.
This is the second line.

// GitHub: renders as two separate lines
This is the first line.
This is the second line.

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.