GitHub CLI (gh) とは｜GitHub の操作をターミナルで扱う公式ツール

gh は GitHub が公式に提供しているコマンドラインツールです。公式リポジトリには、Pull Request や Issue といった GitHub の概念を、すでに git とコードを触っている場所、つまりターミナルへ持ち込むものだと書かれています。

実装は Go で、MIT ライセンスの OSS として cli/cli で開発されています。動作環境は macOS・Windows・Linux で、接続先は GitHub.com のほか、GitHub Enterprise Cloud とサポート対象の GitHub Enterprise Server が挙げられています。

この記事では、インストールから gh auth login での認証、日常で使うコマンド、スクリプトへの組み込み、そしてコーディングエージェントが gh を呼ぶ前提になっている状況までを扱います。動作確認に使ったのは、2026 年 9 月 3 日にリリースされた v2.100.0 です。

git との違いは、操作する対象が違うこと

最初につまずきやすいのが git との関係です。役割は重なりません。

観点gitgh
操作する対象手元のリポジトリとリモートのリポジトリGitHub 上の PR・Issue・Actions・Releases など
提供元Git プロジェクトGitHub
無いとできないことコミットもプッシュもできないブラウザを開かずに PR を作れない

gh は git の代わりではなく、git が扱わない範囲を埋めるものです。かつて非公式の GitHub 用ツールとして使われていた hub は git のプロキシとして振る舞いましたが、gh は独立したツールとして設計されていると公式 README に明記されています。既存の git の使い方は変えずに済みます。

インストールは OS ごとに公式の入手経路が決まっている

公式のインストール手順では、OS ごとに推奨の入手経路が示されています。

OS公式が案内する方法
macOSHomebrew
WindowsWinGet
Debian・Ubuntu・Raspberry Pi公式 apt リポジトリ
Amazon Linux・CentOS・Fedora・RHEL・openSUSE・SUSE公式 rpm リポジトリ
上記以外Releases のバイナリ

macOS は Homebrew の 1 行で終わります。

brew install gh
gh --version

Windows は WinGet です。インストーラーが PATH を書き換えるため、Windows Terminal では新しいタブではなく新しいウィンドウを開く必要がある、と公式ドキュメントに注記されています。

winget install --id GitHub.cli --source winget

Debian 系は、公式リポジトリの署名鍵を登録してから apt で入れます。

(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

CI で使う場合、GitHub がホストする Actions ランナーには gh が最初から入っており、週次で更新されると記載されています。追加の導入手順は要りません。Codespaces では devcontainer に feature を足します。

{
  "features": {
    "ghcr.io/devcontainers/features/github-cli:1": {}
  }
}

バージョンの確認と更新

gh --version で現在のバージョンとリリースページの URL が出ます。

gh --version
# gh version 2.100.0 (2026-09-03)
# https://github.com/cli/cli/releases/tag/v2.100.0
 
# 更新する
brew upgrade gh

注意

Linux の APT・RPM リポジトリで使われていた PGP 署名鍵は 2026 年 9 月 5 日に有効期限を迎えました。新旧両方の鍵を含む keyring は 2026 年 4 月 8 日から配布されているため、それ以降に公式手順で入れた環境は影響を受けません。それより前から使っている環境で更新が失敗する場合は、keyring を入れ直す手順がアナウンスにまとまっています。macOS・Windows、および Homebrew や Releases のバイナリから入れた環境は対象外です。

gh auth login で最初に 1 回だけ認証する

インストール直後にやることは認証だけです。手順は次のとおりです。

  1. gh auth login を実行する
  2. 接続先を GitHub.com か、Enterprise のホスト名から選ぶ
  3. git が使うプロトコルを HTTPS と SSH から選ぶ
  4. 認証方法をブラウザとトークンの貼り付けから選ぶ
  5. gh auth status で認証状態を確かめる

ログインが通ると、トークンは OS の資格情報ストアへ保存されます。資格情報ストアが無い環境では平文ファイルへ保存される、とマニュアルに書かれています。

# 対話でログインする
gh auth login
 
# 認証状態を確かめる
gh auth status
 
# 対話できない環境ではトークンを環境変数で渡す
export GH_TOKEN="<personal access token>"

トークンを標準入力から渡す --with-token もあり、その場合に必要な最小スコープは repo・read:org・gist と案内されています。あとから権限が足りなくなったときは gh auth refresh でスコープを追加できます。複数アカウントを切り替えるなら gh auth switch、git 側の認証情報ヘルパーとして使うなら gh auth setup-git です。

コツ

gh auth setup-git を通しておくと、git push の認証も gh が持っているトークンで済みます。個人アクセストークンを別途 .netrc や資格情報ヘルパーへ書き込む手間がなくなります。

日常で使う主要コマンド

コマンドは gh <対象> <操作> の形で並んでいます。よく使うものは次のとおりです。

コマンド何をするか
gh repoリポジトリのクローン・作成・フォーク・閲覧
gh prPull Request の作成・確認・レビュー・マージ
gh issueIssue の作成・一覧・コメント・クローズ
gh runGitHub Actions の実行状況の確認とログ取得
gh workflowワークフローの一覧表示と手動実行
gh releaseリリースの作成と成果物のアップロード・ダウンロード
gh apiREST と GraphQL への認証済みリクエスト
gh searchリポジトリ・Issue・PR・コードの横断検索
gh gistGist の作成と編集
gh codespaceCodespaces への接続と管理
gh extension拡張機能の検索・導入・更新
gh aliasコマンドの短縮形の登録
gh secretActions で使うシークレットの登録と削除

手が覚えるのは、だいたいこのあたりです。

gh repo clone cli/cli
gh issue list --assignee @me --state open
gh pr checkout 321
gh run watch
gh release create v1.2.0 ./dist/app.zip --notes "バグ修正のみ"

gh run watch は実行が終わるまで進捗を出し続けます。CI の結果待ちでブラウザを何度も更新する作業が、そのままコマンド 1 つに置き換わります。

FIXITFIXIT

ブラウザで PR を作るのと、そんなに変わるの？

KanameKaname

現場では、画面を開いて選び直す時間がまるごと消えます。

FIXITFIXIT

えっ、時間だけ？

KanameKaname

もう 1 つあります。作り方を手順として書けるので、誰がやっても同じ形の PR になります。

gh pr create で PR の作成からマージまで進める

gh を入れて最初に効果が出るのが Pull Request 周りです。ブランチを切って変更をコミットしたあと、そのままターミナルで完結します。

flowchart LR
  A["ブランチを切って<br/>変更をコミット"] --> B["gh pr create"]
  B --> C["gh pr checks --watch<br/>で CI を待つ"]
  C --> D["gh pr review<br/>レビューと修正"]
  D --> E["gh pr merge --squash<br/>--delete-branch"]

gh pr create は、フラグを付けなければ対話で聞いてきます。慣れてきたらフラグで先に指定してしまうほうが速くなります。

# コミットメッセージからタイトルと本文を埋める
gh pr create --fill --reviewer octocat --label bug
 
# PR は作らず内容だけ表示する (git の push は走ることがある)
gh pr create --fill --dry-run
 
# 下書きとして作る
gh pr create --fill --draft

作ったあとの確認と操作も揃っています。gh pr status は自分に関係する PR を一覧し、gh pr checks --watch は CI が終わるまで待ちます。--fail-fast を足すと、最初の失敗で待機を打ち切ります。

gh pr status
gh pr checks --watch --fail-fast
gh pr diff
gh pr merge --squash --delete-branch

gh pr view --web のように --web を付ければブラウザへ切り替えられるので、差分を目で追いたいときだけ画面を開く、という使い分けができます。

--json と --jq で出力をスクリプトへ渡す

gh の出力は、既定では人が読む前提の行単位のテキストです。--json にフィールド名を渡すと JSON へ切り替わり、--jq か --template でさらに絞り込めます。マニュアルには、jq コマンドをシステムに入れていなくても --jq を使えると書かれています。

# 指定できるフィールド名を一覧する
gh pr list --json
 
# レビュー待ちの PR を番号とタイトルだけ出す
gh pr list --state open --json number,title,reviewDecision \
  --jq '.[] | select(.reviewDecision == "REVIEW_REQUIRED") | "\(.number) \(.title)"'

gh pr list なら number・title・state・reviewDecision・reviewRequests などが返ります。ドキュメントを探しに行かなくても、コマンド側が教えてくれます。

--template を使えば Go のテンプレート構文で整形でき、tablerow や timeago のような補助関数も用意されています。定期的に見る一覧を自分の形に固定しておくと、確認の手間が減ります。

gh api で REST と GraphQL を直接叩く

サブコマンドが用意されていない操作は、gh api から GitHub API を直接呼べます。認証は gh auth login の結果を使うため、スクリプトにトークンを書かずに済みます。

# 最新リリースのタグ名だけ取る
gh api repos/cli/cli/releases/latest --jq '.tag_name'
 
# 現在のリポジトリの Issue を全ページ取得する
gh api --paginate repos/{owner}/{repo}/issues --jq '.[].number'
 
# パラメーターを付けると自動で POST になる
gh api repos/{owner}/{repo}/issues -f title="不具合の報告" -f body="再現手順は次のとおりです"
 
# GraphQL も同じ認証で叩ける
gh api graphql -f query='query { viewer { login } }'

{owner} {repo} {branch} は、現在のディレクトリのリポジトリから補完されます。--paginate は追加のリクエストを投げて全ページを取り、--slurp を併用すると全ページを 1 つの配列にまとめます。--cache 1h のように応答をキャッシュする指定もあるので、同じ問い合わせを繰り返す集計では回数を抑えられます。

alias と extension で自分の作業に寄せる

よく打つ組み合わせは gh alias set で短縮できます。

gh alias set prm 'pr merge --squash --delete-branch'
gh alias list

チームで共有したい場合は、YAML に書いて gh alias import で配れます。手順書に「このコマンドを打ってください」と書くより、短縮形を配ったほうが、打ち方が揺れません。

機能そのものを足すなら拡張機能です。gh extension search で探し、gh extension install <所有者>/<リポジトリ> で入ります。まとめて更新するなら gh extension upgrade --all です。

gh extension search
gh extension install owner/gh-example
gh extension upgrade --all

コーディングエージェントが gh を呼ぶ前提になっている

ここ 1 年で変わったのは、gh を打つのが人だけではなくなったことです。

Claude Code の公式ドキュメントには、Claude が gh pr create で PR を作成した場合にセッションと PR が紐づくと書かれています。「PR を作って」と頼んだときに実際に走っているのは gh です。つまり、gh が入っていない、あるいは認証が通っていない環境では、PR を作る段階で作業が止まります。エージェントに PR やレビューコメントのやり取りを任せるなら、gh auth login まで先に済ませておくのが前提条件になります。

gh の側も、エージェントから呼ばれる状況に合わせた調整を進めています。2026 年 9 月 1 日の v2.99.0 では、コーディングエージェントから呼び出されたときにスピナーの出力をテキストのみへ切り替えるようになりました。続く 9 月 3 日の v2.100.0 では、コマンドの使い方を誤ったときにヘルプ全文を表示するようになっています。どちらも、画面を人が見ている前提を外し、出力をそのまま読み取る相手に合わせた変更です。

エージェント向けのスキルも用意されています。

gh skill install cli/cli gh --scope user
gh skill update gh

gh agent-task (preview) では、GitHub 側のエージェントに投げたタスクの作成・一覧・閲覧ができます。エージェントの実行状況を、ほかの操作と同じコマンド体系から扱えます。

権限は絞ってください。エージェントに gh を渡すということは、リポジトリへの書き込みを渡すのと同じです。Claude Code なら、許可するコマンドの単位で gh の使い方を限定できます。設定の書き方は Claude Code の権限設定にまとめています。CI 側からエージェントを動かす構成は Claude Code を GitHub Actions に組み込む方法で扱っています。

FIXITFIXIT

じゃあ、人のほうは gh を入れなくていいってこと？

KanameKaname

そうでもないんです。エージェントが PR を作るときに呼んでいるのが gh です。

FIXITFIXIT

先に入れて認証しておかないと、そこで止まっちゃうんだ？

KanameKaname

はい。認証まで済ませておくと、PR 作成の途中で作業が止まりません。

v2.99.0 から画像と動画を添付できる

2026 年 9 月 1 日の v2.99.0 で --attach が追加され、ローカルの画像や動画を Issue・Pull Request・コメントへ直接アップロードできるようになりました。

gh pr create --fill --attach "./shots/after.png#変更後の画面"

対応するのは gh issue create / gh issue edit / gh issue comment / gh pr create / gh pr edit / gh pr comment の 6 つで、GitHub.com と GitHub Enterprise Cloud が対象です。UI の変更を PR で見せるときに、画面を開いて貼り付ける作業が消えます。対応形式やサイズの上限、本文中の参照が書き換わる挙動は GitHub CLI で画像・動画を添付する方法で詳しく扱っています。

FIXIT の運用｜先に gh を通してから AI を足す

私たちがクライアントワークで開発環境を整えるとき、gh の導入と認証は、コーディングエージェントを入れるより前に済ませています。順番を逆にすると、エージェントが PR を作ろうとした時点で認証を求められ、その場で作業が中断するためです。

運用として決めているのは、変更が必ず Pull Request を経由することです。エージェントが書いたコードでも、人が書いたコードでも、レビューを通る経路は同じにします。gh はその経路をターミナルの中で完結させられるので、作成・CI 確認・マージの手順を文章として配れます。

CI の失敗を調べる作業も、gh run でログを手元へ落とせるぶん、状況の共有が速くなります。画面のスクリーンショットを回すより、失敗したジョブのログをそのまま貼ったほうが、原因の特定は早く終わります。

AI 駆動開発の導入では、モデルの選定よりも、ツールの導入と認証が済んでいるかどうかで初速が変わります。ツールの選定から社内での定着まで含めた進め方は AI 開発ツール導入支援で伴走しています。

まとめ｜まず入れて認証まで済ませる

gh は GitHub 側の操作をターミナルへ持ち込む公式ツールで、git の置き換えではありません。両方を併用して、git で変更を積み、gh で GitHub へ渡します。

最初にやることは 2 つだけです。OS ごとの公式手順で入れて、gh auth login を通すこと。ここまでで gh pr create も gh run watch も使えるようになり、ブラウザを開く回数が目に見えて減ります。慣れてきたら --json と --jq、gh api、gh alias の順に手を伸ばすと、日々の確認作業を少しずつスクリプトへ移せます。

コーディングエージェントを使う予定があるなら、優先度はさらに上がります。エージェントが PR を作るときに呼ぶのが gh である以上、入っていない環境では PR 作成の手前で作業が中断するからです。Claude Code をこれから入れる場合の手順は Claude Code の導入ガイドにまとめてあります。

より詳しいコマンドの一覧は 公式マニュアルを、最新のリリース内容は cli/cli のリリースページを参照してください。開発体制ごと見直したい場合のご相談は お問い合わせからお寄せください。