GitHub CLI（gh）の使い方｜逆引きコマンド一覧とjqレシピ

GitHub CLI（gh）とは、プルリクエスト・Issue・Actions の実行・リリース・API 呼び出しといった GitHub 上の操作を、ブラウザを開かずにターミナルから行う公式コマンドラインツールです。 git が「リポジトリの中身」を扱うのに対し、gh は「GitHub というサービス側」を扱います。2026年10月1日時点の最新版は v2.102.0（2026-09-30 公開）、Ubuntu 24.04 の標準 apt からは 2.45.0 が入ります。

この記事は 「やりたいこと → gh コマンド」の逆引き表を軸に、--json / --jq / --template のレシピ、GitHub Actions 内で GH_TOKEN を使う YAML 例、認証、インストール、エラー文の読み方までをまとめました。コマンドは apt の gh 2.45.0 で実行し、出力をそのまま載せています（GitHub への通信が要る gh api の例は、同じ形式の JSON を返すローカルのモックで実行。データは架空です）。

gh コマンドの早見表（やりたいこと → コマンド）

-R OWNER/REPO を付ければ、カレントディレクトリが git リポジトリでなくても動きます。

インストールと最新版の確認

Ubuntu / Debian の公式リポジトリ登録手順（公式ドキュメント install_linux.md の記載どおり）:

(type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \
  && sudo mkdir -p -m 755 /etc/apt/keyrings \
  && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
  && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
  && sudo mkdir -p -m 755 /etc/apt/sources.list.d \
  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
  && sudo apt update \
  && sudo apt install gh -y

検証環境（Ubuntu 24.04、外部通信なし）で標準 apt から入れた結果です。

$ sudo apt-get install -y gh && gh --version
gh version 2.45.0 (2025-07-18 Ubuntu 2.45.0-1ubuntu0.3)
https://github.com/cli/cli/releases/tag/v2.45.0

公式ドキュメントは「ディストリビューション配布の 2.45.x / 2.46.x は廃止された API に依存して問題が起きるため、公式 Debian パッケージを強く推奨」と明記しています。最新版はリリースページ（github.com/cli/cli/releases）で確認できます。

本記事の実行結果は 2.45.0 のものです。新機能は gh <command> --help で手元の版にフラグがあるかを確認してください。シェル補完は eval "$(gh completion -s bash)"（zsh は -s zsh）を起動スクリプトに書きます。

認証：gh auth login・GH_TOKEN・複数アカウント

トークン方式に必要な最小スコープは repo・read:org・gist（gh auth login --help より）。後から足すときは gh auth refresh -s project,workflow です。

トークンは GH_TOKEN → GITHUB_TOKEN → 保存済み資格情報（OS のキーチェーンか hosts.yml）の順に使われます（gh help environment より）。GitHub Enterprise Server には GH_ENTERPRISE_TOKEN と GH_HOST を組で使います。

未ログインで gh auth status を実行すると終了コード 1 で次の表示です（gh 2.45.0）。

You are not logged into any GitHub hosts. To log in, run: gh auth login

ログイン後はホストごとにアカウント・プロトコル・スコープが並びます。下は検証環境でローカルのモックホスト（github.localhost）に 2 アカウント（sato、suzuki）をトークン方式でログインし、切り替え・ログアウトした実行結果の抜粋です（表示形式は github.com でも同じ。パスは短く置き換えています）。

echo "$TOKEN_SUZUKI" | gh auth login --hostname github.localhost --with-token
gh auth status
gh auth switch --hostname github.localhost --user sato
gh auth logout --hostname github.localhost --user suzuki

github.localhost
  ✓ Logged in to github.localhost account suzuki (/home/dev/.config/gh/hosts.yml)
  - Active account: true
  - Git operations protocol: https
  - Token: ghp_second_*****
  - Token scopes: 'gist', 'read:org', 'repo'
✓ Switched active account for github.localhost to sato
✓ Logged out of github.localhost account suzuki

後からログインしたアカウントが Active になります。いま有効なトークンは gh auth token で取り出せます。GH_TOKEN が設定されていると gh auth status は環境変数の方を評価するため、検証環境では無効な値が入っていて X Failed to log in to github.com using token (GH_TOKEN) と表示されました。「ログインしたはずなのに通らない」ときは env | grep -E 'GH_|GITHUB_' の確認が早道です。

gh pr create の使い方

gh pr create のフラグ（2.45.0 の --help より）

gh pr create --fill --base main                     # push 済みブランチなら最短
gh pr create --title "注文一覧のページネーションを追加" --body "Closes #39" \
  --base main --draft --reviewer suzuki --assignee @me --label enhancement

本文に Closes #39 や Fixes #39 と書くと、マージ時に Issue が自動で閉じます。--fill と --title を同時に指定したときは --title が優先されます。

gh release download はタグを省略すると最新リリースが対象になり、その場合は --pattern か --archive が必須です（--help より）。gh run list --status には failure success in_progress cancelled timed_out などを渡せます。

--json・--jq・--template の仕組みと使い分け

ルールは 2 つ。(1) --jq と --template は --json と一緒に指定する（gh api は --json 不要）。(2) jq は gh に内蔵されているので、jq コマンドが無くても動きます（gh help formatting より）。

--json にフィールド名を渡さずに実行すると、使えるフィールドの一覧が表示されます（通信なしで動く。2.45.0 の実行結果を 1 行にまとめたもの）。

gh pr list -R acme/orders --json

Specify one or more comma-separated fields for `--json`:
  additions assignees author autoMergeRequest baseRefName body changedFiles closed closedAt comments
  commits createdAt deletions files headRefName headRefOid headRepository headRepositoryOwner id
  isCrossRepository isDraft labels latestReviews maintainerCanModify mergeCommit mergeStateStatus
  mergeable mergedAt mergedBy milestone number potentialMergeCommit projectCards projectItems
  reactionGroups reviewDecision reviewRequests reviews state statusCheckRollup title updatedAt url

同じ方法で gh issue list --json（labels, assignees など）、gh run list --json（databaseId, conclusion, workflowName など）、gh release list --json（tagName, isLatest など）のフィールドも確認できます。

--template で使える gh 独自の関数（gh help formatting より）は、tablerow / tablerender（表）、timeago / timefmt（時刻）、pluck / join（配列）、truncate、color / autocolor、hyperlink です。

jq レシピ集（実行結果つき）

実行環境の注記：この検証環境は GitHub へ接続できないため、gh api の例は REST API と同じ形式の JSON を返すローカルのモックサーバー（ホスト名 github.localhost、固定のサンプルデータ）に対して gh 2.45.0 を実際に実行した結果です。構文・--jq / --template / --paginate の挙動・出力形式は本物と同じですが、PR 番号や名前は架空です。gh pr list --json のように GraphQL を使うコマンドは未実行で、その jq 式は同じ形のサンプル JSON に対して jq 1.7 で確認しています。

レシピ1：レビュー待ちの PR を一覧にする

# GitHub 上で実行する形（未実行）
gh pr list --search "review-requested:@me" --json number,title,author \
  --jq '.[] | "#\(.number)\t\(.author.login)\t\(.title)"'

# REST 版（モックで実行）：レビュアー指名があり、ドラフトでない PR
gh api repos/acme/orders/pulls --jq '.[] | select(.draft | not)
  | select((.requested_reviewers | length) > 0)
  | "#\(.number) \(.title) / reviewer: \(.requested_reviewers | map(.login) | join(","))"'

#42 注文一覧のページネーションを追加 / reviewer: suzuki
#40 READMEに環境構築手順を追記 / reviewer: sato,suzuki

select(条件) で絞り、"#\(.number) ..." の文字列補間で 1 行に整えるのが基本形です（タブ区切りは [.number, .title] | @tsv）。

レシピ2：自分に割り当てられた Issue（ラベル付き）

# GitHub 上で実行する形（未実行）
gh issue list --assignee @me --json number,title,labels \
  --jq '.[] | "#\(.number)\t\(.labels | map(.name) | join(","))\t\(.title)"'

# REST 版（モックで実行）
gh api -X GET repos/acme/orders/issues -f assignee=sato \
  --jq '.[] | "#\(.number)\t\(.labels | map(.name) | join(","))\t\(.title)"'

#39 enhancement 会員登録フォームのバリデーション追加
#38 bug タスク一覧の並び順が保存されない

gh api に -f key=value を付けると既定で POST になるため、検索条件付きの GET では -X GET を明示します（gh api --help より）。

レシピ3：失敗した run を見つけて、失敗ジョブだけ再実行

# 失敗した run の ID（REST 版、モックで実行）
gh api repos/acme/orders/actions/runs --jq '.workflow_runs[] | select(.conclusion == "failure") | .id'

9001

# GitHub 上で実行する形（未実行）：main で失敗した直近 3 件を失敗ジョブだけ再実行
gh run list --status failure --branch main --limit 3 --json databaseId --jq '.[].databaseId' \
  | xargs -n1 gh run rerun --failed

レシピ4：直近のリリース資産をダウンロードする

# 資産の一覧（REST 版、モックで実行）
gh api repos/acme/orders/releases/latest --jq '.tag_name, (.assets[] | "\(.name)\t\(.size)\t\(.download_count)")'

v1.4.0
orders_1.4.0_linux_amd64.tar.gz 10485760    12
orders_1.4.0_darwin_arm64.tar.gz    10240000    7
checksums.txt   256 19

ダウンロードは gh release download --pattern '*linux_amd64*' --dir ./dist（最新リリース）、gh release download v1.4.0 --pattern '*.tar.gz' --skip-existing（特定タグ）です（未実行）。

レシピ5：PR がマージできる状態かを 1 行で判定する

mergeable（MERGEABLE / CONFLICTING）、mergeStateStatus（CLEAN / BLOCKED / DIRTY / BEHIND など）、reviewDecision（APPROVED / CHANGES_REQUESTED / REVIEW_REQUIRED）、statusCheckRollup を組み合わせます。

# GitHub 上で実行する形（未実行）
gh pr view 42 --json number,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup \
  --jq '{number, mergeable, mergeStateStatus, reviewDecision,
         checks: (.statusCheckRollup
                  | map(.conclusion // .state | if . == "" then "PENDING" else . end)
                  | group_by(.) | map({(.[0]): length}) | add)}'

上の jq 式を、gh pr view --json が返す形のサンプル JSON（チェック 4 件：成功 2・失敗 1・実行中 1）に対して jq 1.7 で実行した結果です。

{"number":42,"mergeable":"MERGEABLE","mergeStateStatus":"BLOCKED","reviewDecision":"REVIEW_REQUIRED","checks":{"FAILURE":1,"PENDING":1,"SUCCESS":2}}

statusCheckRollup は Actions のチェック（conclusion）と外部ステータス（state）が混在するので .conclusion // .state で片方を拾います。

レシピ6：ラベルを一括で付ける

# GitHub 上で実行する形（未実行）：bug ラベルの open Issue すべてに triage を追加
gh issue list --label bug --state open --limit 200 --json number --jq '.[].number' \
  | xargs -I{} gh issue edit {} --add-label triage

# REST 版（モックで実行）：配列は key[]=value を繰り返して渡す
gh api repos/acme/orders/issues/39/labels -f 'labels[]=bug' -f 'labels[]=triage' --jq 'map(.name)'

["bug","triage"]

レシピ7：複数リポジトリを横断して集計する

# 組織内で自分がレビューを頼まれている PR（未実行）
gh search prs --owner acme --state open --review-requested @me --json repository,number,title \
  --jq '.[] | "\(.repository.nameWithOwner)#\(.number)\t\(.title)"'

# リポジトリごとの open PR 数（ループ部分はモックで実行）
for r in acme/orders acme/stock acme/members; do
  printf '%s\t' "$r"; gh api "repos/$r/pulls" --jq 'length'
done

acme/orders 3
acme/stock  1
acme/members    2

対象リポジトリの一覧は gh repo list acme -L 100 --json nameWithOwner --jq '.[].nameWithOwner' で作れます。

レシピ8：--template で表やレポートを作る

gh api repos/acme/orders/pulls --template \
  '{{range .}}{{tablerow (printf "#%v" .number) .title .user.login (timeago .updated_at)}}{{end}}'

#42  注文一覧のページネーションを追加  sato    18 hours ago
#41  在庫数の表示崩れを修正            suzuki  2 days ago
#40  READMEに環境構築手順を追記        tanaka  9 days ago

見出し行つきの表は {{tablerow "ASSET" "SIZE"}}{{range .assets}}{{tablerow .name .size}}{{end}}{{tablerender}} のように tablerow を並べて最後に tablerender、ラベル名の連結は {{.labels | pluck "name" | join ", "}} です（いずれもモックで動作確認）。改行やタブは {{"\n"}} {{"\t"}} と書きます（\t を直接書くと文字として出力されます）。

レシピ9：--paginate と --jq の評価単位、--slurp

--paginate と --jq を同時に指定すると、2.45.0 では jq がページごとに実行されます。3 件を 2 件ずつ取得した例です（モックで実行）。

gh api -X GET repos/acme/orders/issues -F per_page=2 --paginate --jq 'length'
gh api -X GET repos/acme/orders/issues -F per_page=2 --paginate | jq length

2
1
3

1〜2 行目がページごとの件数、3 行目は --jq を外して外部 jq に渡した結果（配列が結合されて届く）です。最新版には --slurp（全ページを外側の配列にまとめる）があり、--paginate --slurp --jq 'add | length' と内蔵 jq だけで集計できます（公式マニュアル記載。2.45.0 にはありません）。

GraphQL は gh api graphql -F owner=acme -F name=orders -f query='query($owner: String!, $name: String!) { ... }' の形で、query 以外の -F/-f が変数になります（-F は数値・真偽・{owner} を型変換、-f は常に文字列）。シェル変数を jq 式で使うときは LOGIN=suzuki gh api ... --jq 'map(select(.user.login == env.LOGIN)) | length' のように env.NAME で参照すると、クォートの入れ子を避けられます（いずれもモックで動作確認）。

GitHub Actions のワークフロー内で gh を使う

GitHub ホストのランナーには gh がプリインストールされており、必要なのは GH_TOKEN と permissions だけです。${{ github.token }} と ${{ secrets.GITHUB_TOKEN }} は同じトークンを指します。

例1：PR が開いたらコメントとラベルを付ける

name: pr-helper
on:
  pull_request:
    types: [opened, synchronize]
permissions:
  contents: read
  pull-requests: write
jobs:
  comment-and-label:
    runs-on: ubuntu-latest
    env:
      GH_TOKEN: ${{ github.token }}        # gh が使うトークン
      GH_REPO: ${{ github.repository }}    # checkout しなくても対象リポジトリが決まる
      PR: ${{ github.event.pull_request.number }}
    steps:
      - name: 変更ファイル数をコメント
        run: |
          files=$(gh pr view "$PR" --json changedFiles --jq .changedFiles)
          gh pr comment "$PR" --body "変更ファイル数: ${files}（自動コメント）"
      - name: ラベルを付ける
        run: gh pr edit "$PR" --add-label needs-review

例2：タグを push したらリリースを作って資産を添付する

name: release
on:
  push:
    tags: ['v*']
permissions:
  contents: write
jobs:
  release:
    runs-on: ubuntu-latest
    env:
      GH_TOKEN: ${{ github.token }}
    steps:
      - uses: actions/checkout@v4
      - run: tar czf "app_${GITHUB_REF_NAME}.tar.gz" README.md
      - run: gh release create "$GITHUB_REF_NAME" "app_${GITHUB_REF_NAME}.tar.gz" --generate-notes --verify-tag

permissions: は最小限に（コメント・ラベルは pull-requests: write、Issue は issues: write、リリースは contents: write）。GH_REPO: ${{ github.repository }} を置くと actions/checkout なしで動きます。GITHUB_TOKEN で行った操作（PR 作成や push）は新しいワークフローを起動しない仕様なので、連鎖させたい場合は PAT か GitHub App のトークンを GH_TOKEN に渡します。

alias と extension で自分用に拡張する

gh alias set rv 'pr list --search "review-requested:@me"'
gh alias set --shell igrep 'gh issue list --label="$1" | grep "$2"'   # シェル経由（引数は $1 $2）
gh alias list
gh alias delete rv

- Creating alias for rv: pr list --search "review-requested:@me"
✓ Added alias rv
co: pr checkout
igrep: '!gh issue list --label="$1" | grep "$2"'
rv: pr list --search "review-requested:@me"
✓ Deleted alias rv; was pr list --search "review-requested:@me"

co は最初から入っている alias（pr checkout）で、--shell を付けると ! 付きで保存され、パイプや引数が使えます。拡張機能は gh extension browse で探し、gh extension install OWNER/gh-NAME で入れると gh NAME として呼べます（更新は gh extension upgrade --all。通信が必要なため未実行）。

よくあるエラーと対処

実際に出力されたエラー文（gh 2.45.0）と、意味・直し方です。

HTTP 401 / HTTP 404 の行はモックに対して実行した出力で、API の応答本文のあとに gh: メッセージ (HTTP ステータス) が付きます。

原因が分からないときは GH_DEBUG=api gh ... を付けると、リクエスト先 URL・ヘッダー・応答ステータスが標準エラーに出ます（トークンは伏せ字）。gh help exit-codes によれば終了コードは 0＝成功、1＝失敗、2＝キャンセル、4＝認証の問題で、gh run watch --exit-status や gh pr checks の結果で分岐するスクリプトに使えます。

よくある質問

Q. --jq を使うのに jq のインストールは必要ですか？ A. 不要です。jq の処理系が gh に内蔵されています。ただし --paginate で全ページをまとめて集計したい場合など、外部の jq にパイプした方が簡単なケースはあります（レシピ9）。

Q. CI で gh を使うとき、PAT を発行しないといけませんか？ A. 同じリポジトリへの操作なら GH_TOKEN: ${{ github.token }} で足ります。別リポジトリへの書き込みや、gh の操作で別のワークフローを起動したい場合は、PAT か GitHub App のトークンを Secret に入れて GH_TOKEN に渡します。

Q. Ubuntu の apt install gh で入る 2.45.0 のままで問題ありませんか？ A. 基本操作は動きますが、公式ドキュメントは配布版の 2.45.x / 2.46.x について公式パッケージへの切り替えを推奨しており、--slurp などの新機能も入っていません。本記事の apt リポジトリ登録手順で最新版に更新するのがおすすめです。

まとめ

• gh は GitHub のサービス側（PR・Issue・Actions・リリース・API）をターミナルから扱う公式 CLI。git と組み合わせて使う
• 逆引き表の形で覚える：gh <分野> <動詞> に -R OWNER/REPO を付ければどこからでも実行できる
• --json を空で実行するとフィールド一覧が出る。--jq は内蔵、--template は tablerow で表が作れる
• gh api は -f（文字列）／-F（型変換）で引数を渡し、-f を付けた GET は -X GET を明示
• --paginate --jq は 2.45 ではページごとに評価される。全体集計は外部 jq か最新版の --slurp
• Actions では GH_TOKEN: ${{ github.token }} と permissions を書けば、プリインストールの gh がそのまま動く
• トークンの優先順位は GH_TOKEN → GITHUB_TOKEN → 保存済み資格情報。認証エラーは終了コード 4、まず gh auth status と環境変数を確認する

株式会社RJCでは、GitHub CLI のようなツールで日々の開発フローを少しずつ軽くする工夫を、プロジェクトの中で仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。