Back to Details

gh-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitHub CLI (
gh
) — Agent Skill

GitHub CLI (
gh
) — Agent Skill

Use the 
gh
CLI for ALL GitHub operations. Always use 
--json
for structured output and 
--jq
for field selection to minimize token usage.
对所有 GitHub 操作使用 
gh
CLI。始终使用 
--json
获取结构化输出，并使用 
--jq
进行字段选择，以最小化 token 使用。

Authentication

认证

Already configured via 
gh auth
. Verify with:
bash
gh auth status
已通过 
gh auth
配置。验证方式：
bash
gh auth status

Core Principle

核心原则

Always request only the fields you need to minimize output tokens:
bash
undefined
始终只请求你需要的字段，以最小化输出 token：
bash
undefined

❌ Bad — returns everything

❌ Bad — returns everything

gh pr view 123
gh pr view 123

✅ Good — returns only what's needed

✅ Good — returns only what's needed

gh pr view 123 --json title,state,body,url --jq '{title,state,body,url}'

---
gh pr view 123 --json title,state,body,url --jq '{title,state,body,url}'

---

Quick Reference

快速参考

Pull Requests

拉取请求

bash
undefined
bash
undefined

List open PRs

List open PRs

gh pr list --json number,title,author,updatedAt --jq '.[] | {number,title,author:.author.login}'
gh pr list --json number,title,author,updatedAt --jq '.[] | {number,title,author:.author.login}'

View PR details

View PR details

gh pr view <number> --json title,state,body,headRefName,baseRefName,additions,deletions,changedFiles
gh pr view <number> --json title,state,body,headRefName,baseRefName,additions,deletions,changedFiles

View PR diff

View PR diff

gh pr diff <number>
gh pr diff <number>

View PR files changed

View PR files changed

gh pr diff <number> --name-only
gh pr diff <number> --name-only

Create PR

Create PR

gh pr create --title "title" --body "description" --base main --head feature-branch
gh pr create --title "title" --body "description" --base main --head feature-branch

Create draft PR

Create draft PR

gh pr create --title "title" --body "description" --draft
gh pr create --title "title" --body "description" --draft

Merge PR

Merge PR

gh pr merge <number> --squash --delete-branch
gh pr merge <number> --squash --delete-branch

Review PR

Review PR

gh pr review <number> --approve gh pr review <number> --request-changes --body "feedback" gh pr review <number> --comment --body "looks good"
gh pr review <number> --approve gh pr review <number> --request-changes --body "feedback" gh pr review <number> --comment --body "looks good"

PR review comments

PR review comments

gh api repos/{owner}/{repo}/pulls/{number}/comments --jq '.[].body'
gh api repos/{owner}/{repo}/pulls/{number}/comments --jq '.[].body'

Add review comment on specific line

Add review comment on specific line

gh api repos/{owner}/{repo}/pulls/{number}/comments
-f body="comment" -f path="file.py" -F line=42 -f side="RIGHT"
-f commit_id="$(gh pr view <number> --json headRefOid --jq .headRefOid)"
gh api repos/{owner}/{repo}/pulls/{number}/comments
-f body="comment" -f path="file.py" -F line=42 -f side="RIGHT"
-f commit_id="$(gh pr view <number> --json headRefOid --jq .headRefOid)"

Check PR CI status

Check PR CI status

gh pr checks <number>
gh pr checks <number>

Update PR branch

Update PR branch

gh pr update-branch <number>
undefined
gh pr update-branch <number>
undefined

Issues

Issues（问题）

bash
undefined
bash
undefined

List issues

List issues

gh issue list --json number,title,labels,assignees --jq '.[] | {number,title,labels:[.labels[].name]}'
gh issue list --json number,title,labels,assignees --jq '.[] | {number,title,labels:[.labels[].name]}'

View issue

View issue

gh issue view <number> --json title,body,state,labels,assignees,comments
gh issue view <number> --json title,body,state,labels,assignees,comments

Create issue

Create issue

gh issue create --title "title" --body "description" --label "bug"
gh issue create --title "title" --body "description" --label "bug"

Comment on issue

Comment on issue

gh issue comment <number> --body "comment text"
gh issue comment <number> --body "comment text"

Close issue

Close issue

gh issue close <number> --reason completed
gh issue close <number> --reason completed

Edit issue

Edit issue

gh issue edit <number> --title "new title" --add-label "priority"
gh issue edit <number> --title "new title" --add-label "priority"

Search issues

Search issues

gh issue list --search "keyword in:title,body" --json number,title
undefined
gh issue list --search "keyword in:title,body" --json number,title
undefined

Repository & Files

仓库与文件

bash
undefined
bash
undefined

View repo info

View repo info

gh repo view --json name,description,defaultBranchRef --jq '{name,description,branch:.defaultBranchRef.name}'
gh repo view --json name,description,defaultBranchRef --jq '{name,description,branch:.defaultBranchRef.name}'

Get file contents (use gh api to avoid raw output issues)

Get file contents (use gh api to avoid raw output issues)

gh api repos/{owner}/{repo}/contents/{path} --jq '.content' | base64 -d
gh api repos/{owner}/{repo}/contents/{path} --jq '.content' | base64 -d

Or with ref:

Or with ref:

gh api repos/{owner}/{repo}/contents/{path}?ref={branch} --jq '.content' | base64 -d
gh api repos/{owner}/{repo}/contents/{path}?ref={branch} --jq '.content' | base64 -d

List directory

List directory

gh api repos/{owner}/{repo}/contents/{path} --jq '.[].name'
gh api repos/{owner}/{repo}/contents/{path} --jq '.[].name'

Create/update file

Create/update file

gh api repos/{owner}/{repo}/contents/{path}
-X PUT
-f message="commit message"
-f content="$(echo -n 'file content' | base64)"
-f branch="branch-name"
gh api repos/{owner}/{repo}/contents/{path}
-X PUT
-f message="commit message"
-f content="$(echo -n 'file content' | base64)"
-f branch="branch-name"

For update, include sha:

For update, include sha:

-f sha="<blob_sha>"
-f sha="<blob_sha>"

Delete file

Delete file

gh api repos/{owner}/{repo}/contents/{path}
-X DELETE
-f message="delete file"
-f sha="<blob_sha>"
-f branch="branch-name"
gh api repos/{owner}/{repo}/contents/{path}
-X DELETE
-f message="delete file"
-f sha="<blob_sha>"
-f branch="branch-name"

Push multiple files — use git directly

Push multiple files — use git directly

git add file1 file2 && git commit -m "message" && git push
git add file1 file2 && git commit -m "message" && git push

Create branch

Create branch

gh api repos/{owner}/{repo}/git/refs
-f ref="refs/heads/new-branch"
-f sha="$(gh api repos/{owner}/{repo}/git/ref/heads/main --jq '.object.sha')"
gh api repos/{owner}/{repo}/git/refs
-f ref="refs/heads/new-branch"
-f sha="$(gh api repos/{owner}/{repo}/git/ref/heads/main --jq '.object.sha')"

List branches

List branches

gh api repos/{owner}/{repo}/branches --jq '.[].name'
gh api repos/{owner}/{repo}/branches --jq '.[].name'

Fork repo

Fork repo

gh repo fork {owner}/{repo}
gh repo fork {owner}/{repo}

Create repo

Create repo

gh repo create {name} --public --description "desc"
undefined
gh repo create {name} --public --description "desc"
undefined

Search

搜索

bash
undefined
bash
undefined

Search code

Search code

gh search code "query" --repo {owner}/{repo} --json path,repository,textMatches gh search code "query language:python" --json path,repository
gh search code "query" --repo {owner}/{repo} --json path,repository,textMatches gh search code "query language:python" --json path,repository

Search repos

Search repos

gh search repos "query" --json fullName,description,stargazersCount --jq '.[] | {name:.fullName,stars:.stargazersCount}'
gh search repos "query" --json fullName,description,stargazersCount --jq '.[] | {name:.fullName,stars:.stargazersCount}'

Search issues across GitHub

Search issues across GitHub

gh search issues "query" --json number,title,repository
gh search issues "query" --json number,title,repository

Search PRs

Search PRs

gh search prs "query" --json number,title,repository
undefined
gh search prs "query" --json number,title,repository
undefined

Commits & History

提交与历史

bash
undefined
bash
undefined

List commits

List commits

gh api repos/{owner}/{repo}/commits --jq '.[].commit.message' | head -20 gh api repos/{owner}/{repo}/commits?sha={branch}&per_page=10 --jq '.[] | {sha: .sha[:7], message: .commit.message}'
gh api repos/{owner}/{repo}/commits --jq '.[].commit.message' | head -20 gh api repos/{owner}/{repo}/commits?sha={branch}&per_page=10 --jq '.[] | {sha: .sha[:7], message: .commit.message}'

View specific commit

View specific commit

gh api repos/{owner}/{repo}/commits/{sha} --jq '{message:.commit.message,files:[.files[].filename],stats:.stats}'
gh api repos/{owner}/{repo}/commits/{sha} --jq '{message:.commit.message,files:[.files[].filename],stats:.stats}'

Get commit diff

Get commit diff

gh api repos/{owner}/{repo}/commits/{sha} -H "Accept: application/vnd.github.diff"
undefined
gh api repos/{owner}/{repo}/commits/{sha} -H "Accept: application/vnd.github.diff"
undefined

Releases & Tags

发布与标签

bash
undefined
bash
undefined

List releases

List releases

gh release list --json tagName,name,publishedAt
gh release list --json tagName,name,publishedAt

View latest release

View latest release

gh release view --json tagName,name,body
gh release view --json tagName,name,body

View specific release

View specific release

gh release view {tag} --json tagName,name,body
gh release view {tag} --json tagName,name,body

List tags

List tags

gh api repos/{owner}/{repo}/tags --jq '.[].name'
gh api repos/{owner}/{repo}/tags --jq '.[].name'

Create release

Create release

gh release create {tag} --title "title" --notes "release notes"
undefined
gh release create {tag} --title "title" --notes "release notes"
undefined

Advanced API Access

高级 API 访问

For any operation not covered above, use 
gh api
directly:
bash
undefined
对于上述未涵盖的任何操作，请直接使用 
gh api
：
bash
undefined

GET request

GET request

gh api repos/{owner}/{repo}/actions/runs --jq '.workflow_runs[:3] | .[].conclusion'
gh api repos/{owner}/{repo}/actions/runs --jq '.workflow_runs[:3] | .[].conclusion'

POST request

POST request

gh api repos/{owner}/{repo}/issues/{number}/comments -f body="comment"
gh api repos/{owner}/{repo}/issues/{number}/comments -f body="comment"

With pagination

With pagination

gh api repos/{owner}/{repo}/issues --paginate --jq '.[].number'
gh api repos/{owner}/{repo}/issues --paginate --jq '.[].number'

Get authenticated user

Get authenticated user

gh api user --jq '{login,name,email}'
gh api user --jq '{login,name,email}'

Team members

Team members

gh api orgs/{org}/teams/{team}/members --jq '.[].login'
undefined
gh api orgs/{org}/teams/{team}/members --jq '.[].login'
undefined

Output Optimization

输出优化

Always minimize output for agent consumption:
  1. Use 
    --json
    + 
    --jq
     for structured, minimal output
  2. Limit results with 
    --limit
    or API 
    per_page
    parameter
  3. Select fields — never dump full objects
  4. Pipe to 
    head
     for long outputs: 
    | head -50
始终最小化输出以供 Agent 使用：
  1. 使用 
    --json
    + 
    --jq
     获得结构化、最小化输出
  2. 使用 
    --limit
    或 API 的 
    per_page
    参数限制结果数量
  3. 选择字段 — 不要倾倒完整对象
  4. 将长输出通过管道传给 
    head
    ：
    | head -50

Error Handling

错误处理

bash
undefined
bash
undefined

Check if command succeeded

Check if command succeeded

gh pr view 999 --json state 2>/dev/null && echo "exists" || echo "not found"
gh pr view 999 --json state 2>/dev/null && echo "exists" || echo "not found"

Safe API call with error handling

Safe API call with error handling

gh api repos/{owner}/{repo}/contents/{path} 2>/dev/null || echo "file not found"
undefined
gh api repos/{owner}/{repo}/contents/{path} 2>/dev/null || echo "file not found"
undefined