gh-cli

GH CLI

Quick reference for the GitHub CLI (gh). Covers the most common operations in the farm repo workflow.

Overview

gh is GitHub's official CLI tool. It wraps the GitHub API and Git operations into composable commands. Most commands accept --json for structured output and --jq for filtering.

Prerequisites

gh auth status                          # verify authenticated
gh auth login                           # authenticate if needed

Common Operations

Pull Requests

Issues

Note: gh issue create does not support --type. Use gh api for issue types (see API section below).

Repositories

Workflows & CI

Search

API Access

Call arbitrary GitHub REST endpoints:

gh api repos/{owner}/{repo}/issues \
  -X POST \
  -f title="Title" \
  -f body="Body in markdown" \
  -f labels[]="bug" \
  --jq '{number, html_url}'

For GraphQL:

gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      issues(first: 5, states: OPEN) {
        nodes { number title }
      }
    }
  }
' -f owner=org -f repo=repo

Key flags for gh api:

• -X METHOD — HTTP method (GET, POST, PATCH, DELETE)
• -f key=value — form field (repeat for multiple values; use -f key[]=val for arrays)
• -F key=@file — file upload
• --jq '...' — filter JSON output with jq syntax
• --paginate — follow pagination automatically
• -H "Header: value" — custom headers

Typical Patterns in Farm

Create a PR for the current branch

git push -u origin "$(git branch --show-current)"
gh pr create --fill

If --fill fails, provide explicit title/body:

gh pr create --title "feat: description" --body "Closes #123"

Check if a branch already has a PR

gh pr list --head "$(git branch --show-current)" --json number,title,state,url

Returns empty [] if no PR exists.

View CI status for a PR

gh pr checks
# or for a specific PR
gh pr checks <number>

Merge a PR with squash

gh pr merge --squash --delete-branch

JSON Output and Filtering

Most gh commands support --json and --jq:

# Get PR number and URL
gh pr list --head "my-branch" --json number,url --jq '.[0] | {number, url}'

# Get specific field
gh pr view --json title --jq '.title'

# List PR numbers only
gh pr list --state open --json number --jq '.[].number'

Tips

• Use --json + --jq instead of parsing text output
• gh pr create --fill uses branch commits for title/body — works best with conventional commits
• gh api is the escape hatch when built-in commands lack features (e.g., issue types)
• For GitHub Actions secrets: gh secret set NAME --body "value" --repo owner/repo
• GH_TOKEN env var or GH_HOST can target different GitHub instances
• Run gh <command> --help for full flag documentation on any command