OpenParable
Skip to content
← Back to skills

GH CLI

Apps & Automation
gh-cli

GH CLI is an Agent Skill for apps & automation published in the farm-fe/farm repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when working with GitHub via the gh CLI - managing PRs, issues, releases, repos, workflows, searching code, or calling the GitHub API. Triggers on tasks involving GitHub operations, PR creation/management, issue tracking, release workflows, or any gh command usage.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/farm-fe/farm/blob/HEAD/.claude/skills/gh-cli/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/gh-cli, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

OperationCommand
List PRsgh pr list --state open
List PRs for current branchgh pr list --head "$(git branch --show-current)" --json number,title,state,url
Create from current branchgh pr create --fill
Create with explicit title/bodygh pr create --title "feat: ..." --body "...description..."
Create with body from filegh pr create --title "..." --body-file body.md
View PR detailsgh pr view [number]
View PR by branchgh pr view --head "$(git branch --show-current)"
Check PR out locallygh pr checkout <number>
View CI checksgh pr checks [number]
Merge PRgh pr merge <number> --squash
Close PRgh pr close <number>
Comment on PRgh pr comment <number> --body "..."
Request reviewgh pr edit <number> --add-assignee @me --add-reviewer @user
Draft PRgh pr create --draft --title "..." --body "..."

Issues

OperationCommand
List issuesgh issue list --state open --limit 20
Create issuegh issue create --title "..." --body "..."
Create with typegh api repos/{owner}/{repo}/issues -X POST -f title=... -f body=... -f type="Bug"
View issuegh issue view <number>
Close issuegh issue close <number>
Reopen issuegh issue reopen <number>
Comment on issuegh issue comment <number> --body "..."
Edit issue labelsgh issue edit <number> --add-label "bug" --remove-label "wip"

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

Repositories

OperationCommand
Clone a repogh repo clone owner/repo
Fork a repogh repo fork owner/repo
View repo infogh repo view --json nameWithOwner,description,defaultBranch
List releasesgh release list
View releasegh release view v1.0.0
Create releasegh release create v1.0.0 --title "..." --notes "..."

Workflows & CI

OperationCommand
List workflowsgh workflow list
View workflow runsgh run list --workflow "CI" --limit 10
Watch a rungh run watch <run-id>
View run logsgh run view <run-id> --log
Re-run failedgh run rerun <run-id> --failed
Cancel a rungh run cancel <run-id>
Download artifactsgh run download <run-id>

Search

OperationCommand
Search issuesgh search issues "query" --owner org --repo repo
Search PRsgh search prs "query" --owner org --repo repo
Search codegh search code "term" --owner org --repo repo

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