gh-cli

GitHub CLI - リモート分析と探索

クローンせずに、リモートリポジトリの操作、コードベースの比較、コードの探索を行います。

使用する場面

• クローンせずにリポジトリを分析する
• コードベースを並べて比較する
• 任意のリポジトリから特定のファイルを取得する
• トレンドのリポジトリやコードパターンを見つける
• GitHub 全体でコードを検索する

クイック操作

リモートからファイルを取得する

gh repo read-file path/file.ts --repo OWNER/REPO

gh repo read-file（プレビュー版）が推奨される方法です。生の内容を出力し、任意のブランチ／タグ／コミットを指定する --ref を受け付け、大きなファイルも処理できます。--output PATH はディスクに書き込みます（上書きするには --clobber を指定）。--json はメタデータ（content, downloadUrl, encoding, gitSHA, gitUrl, htmlUrl, name, path, size, type, url）を返します。このコマンドを利用できない場合は、gh api を代わりに使用してください。

gh api repos/OWNER/REPO/contents/path/file.ts -H "Accept: application/vnd.github.raw"

base64decode テンプレート関数はありません。--template '{{.content | base64decode}}' は function "base64decode" not defined というエラーになります。デフォルトの JSON レスポンスをデコードするには、パイプで渡します。

gh api repos/OWNER/REPO/contents/path/file.ts --jq '.content' | base64 -d

Contents API がインラインで返すのは、最大 1MB までのファイルのみです。それを超えると、.content は空の文字列（encoding: "none"）になり、上記のパイプでは何も出力されません。read-file または raw Accept ヘッダーを使用してください。

ターミナルエスケープシーケンス（gh 2.97.0 以降）

gh は、ターミナルエスケープシーケンスを含むリモートコンテンツ（ANSI アート、一部のテスト用フィクスチャなど）をターミナルに渡さず、出力を拒否します。

• gh repo read-file：file contains terminal escape sequences; use --allow-escape-sequences to read anyway
• gh api の raw 本文：the response contains terminal escape sequences; pass --allow-escape-sequences to output it anyway
• パイプで渡した場合の gh pr diff：the diff contains terminal escape sequences; pass --allow-escape-sequences to output it anyway

バイト列をそのまま取得する必要がある場合は、--allow-escape-sequences を指定してください（gh release download --output - と gh gist view でも指定できます）。または、常に生のバイト列を保持する gh repo read-file --output でディスクに書き込んでください。このチェックは GHSA-3m3g-3wcr-px46 の修正に伴って追加されました。この修正と、ほかの 2.97／2.98 のセキュリティ修正を適用するには、gh 2.98.0 以降を実行してください。

ディレクトリ一覧を取得する

gh repo read-dir PATH --repo OWNER/REPO    # omit PATH to list the repo root

# Or via the API
gh api repos/OWNER/REPO/contents/PATH

gh repo read-dir --json は配列ではなく、{"entries":[...]} というオブジェクトを返します。そのため、.entries[] でフィルタリングしてください。

gh repo read-dir src --repo OWNER/REPO --json name,type --jq '.entries[] | select(.type=="file") | .name'

スクリプト化されたワークフローでリポジトリを固定する

gh は現在の作業ディレクトリからリポジトリを推定します。エージェントや CI のワークフローでは、cd の結果が保持されることがあるため、意図しない作業ディレクトリによってコマンドの対象が気付かないうちに変わらないよう、常に --repo OWNER/REPO を指定してください。--repo の指定漏れを示す例は次のとおりです。

• Git リポジトリの外：failed to run git: fatal: not a git repository
• リモートのないリポジトリ内：no git remotes found
• 別の リポジトリ内：エラーは発生しません。そのリポジトリが対象になり、別の場所から取得した ID は 404 になります

コードを検索する

gh search code "pattern" --language=typescript

トレンドのリポジトリを見つける

gh search repos --language=rust --sort stars --order desc

2 つのコードベースを比較する

リポジトリを比較して、類似点と相違点を特定するための体系的なワークフローです。

使用例：「solana-fm/explorer-kit と tenequm/solana-idls を比較する」

ステップ 1：ディレクトリ構造を取得する

gh repo read-dir PATH --repo OWNER-A/REPO-A
gh repo read-dir PATH --repo OWNER-B/REPO-B

モノレポのパッケージを比較する場合は、パスを指定してください（例：packages/explorerkit-idls）。

ステップ 2：ファイル一覧を比較する

diff <(gh repo read-dir PATH --repo OWNER-A/REPO-A --json name --jq '.entries[].name') \
     <(gh repo read-dir PATH --repo OWNER-B/REPO-B --json name --jq '.entries[].name')

< が先頭に付いた行はリポジトリ A のみに存在し、> が先頭に付いた行はリポジトリ B のみに存在します。

ステップ 3：比較する主要ファイルを取得する

パッケージの依存関係を比較します。

gh repo read-file package.json --repo OWNER-A/REPO-A
gh repo read-file package.json --repo OWNER-B/REPO-B

メインのエントリーポイントを比較します。

gh repo read-file src/index.ts --repo OWNER-A/REPO-A
gh repo read-file src/index.ts --repo OWNER-B/REPO-B

同じファイルを繰り返し確認する場合は、gh api の呼び出しに --cache 1h を追加して、レート制限を再度消費しないようにしてください。

同じリポジトリの 2 つの ref（またはそのフォーク）を比較する場合は、compare API を 1 回呼び出すだけで済みます。ただし、上限は 250 コミット、300 ファイルです。

gh api repos/OWNER/REPO/compare/v1.0.0...v2.0.0 --jq '{ahead_by, files: [.files[].filename]}'

ステップ 4：差分を分析する

取得したファイルを比較し、以下を特定します。

API サーフェス

• どの関数／クラスがエクスポートされていますか？
• API は似ていますか、それともまったく異なりますか？

依存関係

• 共通する依存関係（同じアプローチ）
• 異なる依存関係（異なる実装）

独自の機能

• repo1 だけにある機能
• repo2 だけにある機能

詳細な比較方法については、references/comparison.md を参照してください。

トレンドコンテンツを見つける

トレンドのリポジトリを見つける

# Most starred repos - a bare `--sort` with no query or filter flag fails: Invalid search query ""
gh search repos "stars:>10000" --sort stars --order desc --limit 20

# Trending in specific language
gh search repos --language=rust --sort stars --order desc

# Recently popular (created in the last 30 days; works with BSD and GNU date)
SINCE=$(date -v-30d +%F 2>/dev/null || date -d '30 days ago' +%F)
gh search repos "created:>$SINCE" --sort stars --order desc

# Trending in specific topic
gh search repos "topic:machine-learning" --sort stars --order desc

人気のコードパターンを見つける

# Find popular implementations (code search has no sorting - scope with filters)
gh search code "function useWallet" --language=typescript

# Scope to a known repo (code search can't filter by stars - stars:>N is literal text)
gh search code "implementation" --repo=honojs/hono

# Search specific organization
gh search code "authentication" --owner=anthropics

すべての検索クエリとパターンについては、references/discovery.md を参照してください。

検索の基本

コード検索

# Search across all repositories
gh search code "API endpoint" --language=python

# Search in specific organization
gh search code "auth" --owner=anthropics

# Exclude results with negative qualifiers
gh search issues -- "bug report -label:wontfix"

Issue と PR の検索

# Find open bugs (--state takes only open|closed here; omit it for both)
gh search issues --label=bug --state=open

# Search assigned issues
gh search issues --assignee=@me --state=open

# Meaning-based issue search (gh 2.98.0+): relevance-ranked, issues only, one page, no --sort/--order
gh search issues worktree checkout --repo cli/cli --search-type hybrid

単語を個別に指定すると、AND 検索されます。複数の単語を 1 つの引数として引用符で囲むと完全一致のフレーズとして送信されるため、gh search issues "worktree checkout" は終了コード 0 で何も返さない場合があります。

検索のレート制限

検索の予算はコア API の 5000/hr よりも大幅に厳しくなっています。gh api rate_limit で確認してください。

リソース	制限（認証済み）
core（gh api、gh repo read-file を含む）	5000/hr
search（リポジトリ、Issue、PR、コミット）	30/min
code_search	10/min
semantic_search（--search-type semantic|hybrid）	10/min - gh api rate_limit には表示されません

高度な検索構文については、references/search.md を参照してください。

特殊な構文

フィールド名の不一致

重要： GitHub CLI では、コマンドによってフィールド名が一貫していません。

フィールド	gh repo view	gh search repos
スター数	stargazerCount	stargazersCount
フォーク数	forkCount	forksCount
トピック	repositoryTopics	利用不可
ウォッチャー	watchers（{totalCount}）	watchersCount - 実際にはスター数

例：

# ✅ Correct for gh repo view
gh repo view owner/repo --json stargazerCount,forkCount

# ✅ Correct for gh search repos
gh search repos "query" --json stargazersCount,forksCount

想定する場所に存在しないフィールドはほかにもあります。gh pr view に merged はありません（mergedAt または state を使用してください）。gh search prs に mergedAt はありません（closedAt を使用してください）。また、gh run list に jobs はありません（gh run view <id> --json jobs を使用してください）。フィールドを間違えると、利用可能なフィールドの一覧とともに Unknown JSON field: "X" が表示されます。

引数ごとに指定できる修飾子は 1 つ

gh search（gh 2.97.0 以降）では、各引数を最初の : で分割し、残りの部分にスペースが含まれている場合は引用符で囲みます。複数の修飾子を 1 つの引用符付き文字列にまとめると、フィルターが気付かないうちに機能しなくなります。

# ❌ Sent as language:"go stars:>500" - the language filter is lost
gh search repos "rate limiting middleware language:go stars:>500"

# ✅ Keywords and qualifiers as separate arguments; quote only those containing > or <
gh search repos rate limiting middleware language:go "stars:>500"

gh pr list --search と gh issue list --search は文字列をそのまま渡すため、そこでは 1 つの引用符付き文字列を使用できます。

検索結果から除外する

否定修飾子は、単独の引数として指定するか、引用符付き文字列の末尾に指定できます（"bug report -label:wontfix"）。クエリがハイフンで始まる場合に限り、シェルがフラグとして解釈するのを防ぐために -- が必要です。

すべてのフラグを -- より前に置いてください。 -- より後はすべて位置引数となるため、後に続くフラグはクエリ文字列に取り込まれます。

# ✅ Correct - flags first
gh search issues --limit 5 -- -label:wontfix bug

# ❌ Wrong - --limit 5 becomes part of the search query, silently returning 30 results
gh search issues -- -label:wontfix bug --limit 5

構文に関するその他の注意点については、references/syntax.md を参照してください。

スクリプト作成時の注意点

• すべてのコマンドで認証が必要です - トークンがない場合、gh は please run: gh auth login と表示して終了コード 4 で終了します。例外は、パブリックリポジトリでの gh release download です。

• gh api はエラーボディを標準出力に書き込みます。 失敗すると終了コード 1 で終了し、標準エラー出力に gh: Not Found (HTTP 404) を表示するとともに、--jq を適用せずにエラー JSON を標準出力に書き込みます。そのため、$(gh api ...) はエラーをデータとして取り込んでしまいます。終了ステータスを確認してください。

  if sha=$(gh api repos/OWNER/REPO/contents/README.md --jq .sha); then echo "$sha"; else echo "fetch failed" >&2; fi
  

• -f／-F を指定すると gh api は POST に切り替わるため、GET 専用エンドポイントは 404 を返します。フィールドをクエリ文字列として送信するには、-X GET を追加してください。

  gh api -X GET search/issues -f q='repo:cli/cli is:open worktree' --jq '.total_count'
  

• --jq に指定できるのは式 1 つだけで、jq フラグは指定できません（末尾に -r を付けると unknown shorthand flag: 'r' で失敗します）。文字列の結果はすでに生の形式で出力されます。

• --paginate --slurp は --jq／--template と併用できません。 代わりに jq にパイプするか、各ページをフィルタリングする --paginate --jq を使用してください。

• ? を含むエンドポイントは引用符で囲んでください - zsh は引用符で囲まれていない ? をグロブとして扱い、no matches found で失敗します。

• 終了コード（gh help exit-codes）：0 は成功、1 は失敗、2 はキャンセル、4 は認証が必要です。一部のコマンドには独自の終了コードがあります。チェックが保留中の場合、gh pr checks は 8 で終了します。

プレビューコマンド

最近の gh リリースでは、リモート分析とディスカバリーに関連するプレビューコマンドが追加されました。これらは予告なく変更される場合があります。

# Read a repo without cloning (see Quick Operations above)
gh repo read-file PATH --repo OWNER/REPO
gh repo read-dir PATH --repo OWNER/REPO

# GitHub Discussions - often where design rationale lives
gh discussion list --repo OWNER/REPO --search "keyword" --answered
gh discussion view <number> --repo OWNER/REPO --comments

# Agent skills on GitHub
gh skill search <query>
gh skill preview OWNER/REPO <skill>    # print SKILL.md without installing
gh skill install OWNER/REPO <skill>

gh discussion list --json は {"discussions":[...],"next":...,"totalCount":...} を返すため、--jq '.discussions[].title' でフィルタリングしてください。gh discussion view はコメント URL（.../discussions/123#discussioncomment-456）も受け付け、返信スレッド全体を 1 件表示できます。また、--comments と --json は併用できません。

gh pr revert <number>（マージ済みの PR を元に戻す PR を作成）はプレビューではなく通常のコマンドです。pull_requests.md を参照してください。

高度なワークフロー

特定のワークフローの詳細なドキュメントについては、以下を参照してください。

コアワークフロー：

• remote-analysis.md - 高度なファイル取得パターン
• comparison.md - コードベース比較の完全ガイド
• discovery.md - トレンドおよびディスカバリーに関するすべてのクエリ
• search.md - 高度な検索構文
• syntax.md - 特殊な構文とコマンドの特性

GitHub の操作：

• repositories.md - リポジトリ操作
• pull_requests.md - PR ワークフロー、CI チェック、レビュースレッド
• issues.md - Issue 管理
• actions.md - GitHub Actions、実行試行、再実行
• releases.md - リリース管理

セットアップと設定：

• getting_started.md - gh auth setup-git 認証情報ヘルパー
• other.md - 環境変数、認証時の注意点、エイリアス、設定
• extensions.md - CLI 拡張機能

リソース

• 公式ドキュメント：https://cli.github.com/manual/
• GitHub CLI：https://github.com/cli/cli
• 検索構文：https://docs.github.com/en/search-github