Back to Details

using-gh-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Using the GitHub CLI (
gh
)

使用GitHub CLI（
gh
）

When to Use

适用场景

  • Browsing or reading code from a GitHub repository — clone it and use Read/Glob/Grep
  • Viewing or creating pull requests, issues, releases, or gists
  • Fetching repo metadata or any GitHub API data
  • Interacting with GitHub Actions (runs, workflows)
  • Any task involving GitHub that you might otherwise use 
    curl
    , 
    wget
    , or 
    WebFetch
    for
  • 从GitHub仓库浏览或查看代码——克隆仓库后使用Read/Glob/Grep工具
  • 查看或创建拉取请求（PR）、议题（issues）、版本发布（releases）或Gist
  • 获取仓库元数据或任何GitHub API数据
  • 与GitHub Actions交互（工作流运行、工作流管理）
  • 任何原本可能使用
    curl
    、
    wget
    或
    WebFetch
    处理的GitHub相关任务

When NOT to Use

不适用场景

  • Non-GitHub URLs (use 
    WebFetch
    or 
    curl
    for those)
  • Public web content that happens to be hosted on GitHub Pages (
    *.github.io
    ) — those are regular websites
  • Local git operations (
    git commit
    , 
    git push
    ) — use 
    git
    directly
  • 非GitHub的URL（此类情况使用
    WebFetch
    或
    curl
    ）
  • 托管在GitHub Pages（
    *.github.io
    ）上的公开网页内容——这些属于常规网站
  • 本地Git操作（
    git commit
    、
    git push
    ）——直接使用
    git
    命令

Key Principle

核心原则

Always use 
gh
instead of 
curl
, 
wget
, or 
WebFetch
for GitHub URLs. The 
gh
CLI uses the user's authenticated token automatically, so it:
  • Works with private repositories
  • Avoids GitHub API rate limits (unauthenticated: 60 req/hr; authenticated: 5,000 req/hr)
  • Handles pagination correctly
  • Provides structured output and filtering
针对GitHub相关的URL，始终使用
gh
而非
curl
、
wget
或
WebFetch
。 
gh
CLI会自动使用用户的已认证令牌，因此它：
  • 可访问私有仓库
  • 避免GitHub API速率限制（未认证：60次请求/小时；已认证：5000次请求/小时）
  • 正确处理分页
  • 提供结构化输出和过滤功能

Browsing Repository Code

浏览仓库代码

To read or browse files from a GitHub repo, clone it locally and use normal file tools (Read, Glob, Grep). This is much faster and more natural than fetching files one-by-one via the API.
bash
undefined
要读取或浏览GitHub仓库中的文件，请将其克隆到本地后使用常规文件工具（Read、Glob、Grep）。这比通过API逐个获取文件要快得多，也更符合使用习惯。
bash
undefined

Clone to a session-scoped temp directory (cleaned up automatically on session end)

Clone to a session-scoped temp directory (cleaned up automatically on session end)

clonedir="$TMPDIR/gh-clones-${CLAUDE_SESSION_ID}" mkdir -p "$clonedir" gh repo clone owner/repo "$clonedir/repo" -- --depth 1

After cloning, use the **Explore agent** (via the Task tool with `subagent_type=Explore`) to investigate the cloned repo. The Explore agent can use Read, Glob, and Grep across the clone efficiently — much better than calling them one at a time:
Task(subagent_type="Explore", prompt="In $clonedir/repo/, find how authentication is implemented")

For targeted lookups on a clone you already understand, use Read/Glob/Grep directly.

- `gh repo clone` uses the user's authenticated token — works with private repos
- `--depth 1` keeps the clone fast (only latest commit)
- No cleanup needed — a SessionEnd hook removes the clone directory automatically
- Use `gh api` only when you need a quick single-file lookup without cloning
clonedir="$TMPDIR/gh-clones-${CLAUDE_SESSION_ID}" mkdir -p "$clonedir" gh repo clone owner/repo "$clonedir/repo" -- --depth 1

克隆完成后，使用**Explore Agent**（通过Task工具，设置`subagent_type=Explore`）来研究克隆后的仓库。Explore Agent可以高效地在克隆仓库中使用Read、Glob和Grep——比逐个调用这些工具要好得多：
Task(subagent_type="Explore", prompt="In $clonedir/repo/, find how authentication is implemented")

对于已熟悉的克隆仓库，若只需针对性查找内容，可直接使用Read/Glob/Grep工具。

- `gh repo clone`会使用用户的已认证令牌——可访问私有仓库
- `--depth 1`参数确保克隆速度快（仅获取最新提交）
- 无需手动清理——SessionEnd钩子会自动删除克隆目录
- 仅当需要快速单个文件查找且无需克隆时，才使用`gh api`

Quick Start

快速入门

bash
undefined
bash
undefined

View a repo

View a repo

gh repo view owner/repo
gh repo view owner/repo

List and view PRs

List and view PRs

gh pr list --repo owner/repo gh pr view 123 --repo owner/repo
gh pr list --repo owner/repo gh pr view 123 --repo owner/repo

List and view issues

List and view issues

gh issue list --repo owner/repo gh issue view 456 --repo owner/repo
gh issue list --repo owner/repo gh issue view 456 --repo owner/repo

Call any REST API endpoint

Call any REST API endpoint

gh api repos/owner/repo/contents/README.md
gh api repos/owner/repo/contents/README.md

Call with pagination and jq filtering

Call with pagination and jq filtering

gh api repos/owner/repo/pulls --paginate --jq '.[].title'
undefined
gh api repos/owner/repo/pulls --paginate --jq '.[].title'
undefined

Common Patterns

常见用法对比

Instead ofUse
WebFetch
on 
github.com/owner/repo
gh repo view owner/repo
WebFetch
on a blob/tree URL		Clone with 
gh repo clone
and use Read/Glob/Grep
WebFetch
on 
raw.githubusercontent.com/...
Clone with 
gh repo clone
and use Read
WebFetch
on 
api.github.com/...
gh api <endpoint>
curl https://api.github.com/...
gh api <endpoint>
curl
with 
-H "Authorization: token ..."
gh api <endpoint>
(auth is automatic)
wget
to download a release asset
gh release download --repo owner/repo
替代方案推荐用法
WebFetch
访问 
github.com/owner/repo
gh repo view owner/repo
WebFetch
访问blob/tree URL		使用
gh repo clone
克隆后，使用Read/Glob/Grep
WebFetch
访问 
raw.githubusercontent.com/...
使用
gh repo clone
克隆后，使用Read
WebFetch
访问 
api.github.com/...
gh api <endpoint>
curl https://api.github.com/...
gh api <endpoint>
curl
携带 
-H "Authorization: token ..."
gh api <endpoint>
（认证自动完成）
wget
下载版本发布资产
gh release download --repo owner/repo

References

参考文档

  • Pull Requests — list, view, create, merge, review PRs
  • Issues — list, view, create, close, comment on issues
  • Repos and Files — view repos, browse files, clone
  • API — raw REST/GraphQL access, pagination, jq filtering
  • Releases — list, create, download releases
  • Actions — view runs, trigger workflows, check logs
  • Pull Requests — 列出、查看、创建、合并、评审PR
  • Issues — 列出、查看、创建、关闭、评论议题
  • Repos and Files — 查看仓库、浏览文件、克隆
  • API — 原生REST/GraphQL访问、分页、jq过滤
  • Releases — 列出、创建、下载版本发布
  • Actions — 查看运行记录、触发工作流、检查日志