| 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.
