网淘吧来吧，欢迎您！

返回首页 微信
微信
手机版
手机版
  • 当前位置：
  • 网淘吧
  • >
  • openclaw小龙虾
    • Github Cli

    Github Cli

    2026-03-27 新闻来源：网淘吧 围观:9
    电脑广告
    手机广告

    GitHub CLI (gh) — 全面掌握

    版本: gh 2.66.1+
    认证:gh auth login或设置GH_TOKEN环境变量
    当不在 git 仓库目录内时，始终使用--repo OWNER/REPO(或-R)。

    目录

    1. 认证与配置
    2. 仓库
    3. 议题
    4. 拉取请求
    5. GitHub Actions (运行与工作流)
    6. 发布
    7. 代码片段
    8. 搜索
    9. 标签
    10. 密钥与变量
    11. 缓存
    12. 项目 V2
    13. API（REST 与 GraphQL）
    14. 扩展功能
    15. 代码空间
    16. Copilot
    17. 其他命令
    18. JSON 输出与格式化
    19. 环境变量
    20. 高级模式
    21. 技巧与注意事项

    1. 身份验证与配置

    身份验证

    # Interactive login (browser-based OAuth)
gh auth login

# Login with a PAT from stdin
echo "$MY_TOKEN" | gh auth login --with-token

# Login to GitHub Enterprise
gh auth login --hostname enterprise.example.com

# Add extra scopes (e.g., project scope for Projects V2)
gh auth refresh -s project

# Add delete_repo scope
gh auth refresh -s delete_repo

# Check auth status (shows active account, scopes, token validity)
gh auth status
gh auth status --show-token

# Switch active account (when multiple accounts configured)
gh auth switch

# Print the active token (useful for piping to other tools)
gh auth token

# Logout
gh auth logout

    各功能所需权限范围：

    功能所需权限范围
    基础仓库/PR/问题操作repo
    代码片段gist
    读取组织成员资格read:org
    项目 V2project
    删除仓库delete_repo
    Actions 工作流工作流
    读取用户资料用户

    配置

    # List all config
gh config list

# Get/set individual values
gh config get git_protocol        # https or ssh
gh config set git_protocol ssh
gh config set editor "code --wait"
gh config set pager "less -R"
gh config set prompt disabled     # disable interactive prompts (good for scripts)
gh config set browser "firefox"

# Clear CLI cache
gh config clear-cache

    Git 凭证设置

    # Configure git to use gh for HTTPS auth
gh auth setup-git

    2. 仓库

    创建

    # Interactive
gh repo create

# Public repo, clone locally
gh repo create my-project --public --clone

# In an org
gh repo create my-org/my-project --private

# From local directory
gh repo create my-project --private --source=. --remote=upstream --push

# From template
gh repo create my-project --template owner/template-repo --clone

# With options
gh repo create my-project --public --description "My project" \
  --license mit --gitignore Node --add-readme

    克隆

    gh repo clone owner/repo
gh repo clone owner/repo my-dir
gh repo clone owner/repo -- --depth=1    # shallow clone

# Clone your own repo (owner defaults to you)
gh repo clone my-repo

    复刻

    # Fork current repo
gh repo fork

# Fork and clone
gh repo fork owner/repo --clone

# Fork into an org
gh repo fork owner/repo --org my-org --fork-name new-name

# Fork default branch only
gh repo fork owner/repo --default-branch-only

    查看

    # View current repo (README + description)
gh repo view
gh repo view owner/repo

# Open in browser
gh repo view --web

# JSON output
gh repo view --json name,description,stargazerCount,url
gh repo view --json name,stargazerCount --jq '.stargazerCount'

    仓库的 JSON 字段： archivedAt, assignableUsers, codeOfConduct, createdAt, defaultBranchRef, deleteBranchOnMerge, description, diskUsage, forkCount, hasDiscussionsEnabled, hasIssuesEnabled, hasProjectsEnabled, hasWikiEnabled, homepageUrl, id, isArchived, isEmpty, isFork, isPrivate, isTemplate, languages, latestRelease, licenseInfo, name, nameWithOwner, owner, parent, primaryLanguage, pullRequests, pushedAt, sshUrl, stargazerCount, updatedAt, url, visibility, watchers

    列表

    # Your repos
gh repo list
gh repo list --limit 100

# Another user/org's repos
gh repo list my-org

# Filter
gh repo list --language go --visibility public
gh repo list --topic cli --no-archived
gh repo list --fork        # only forks
gh repo list --source      # only non-forks

# JSON output
gh repo list --json name,stargazerCount --jq '.[] | "\(.name): \(.stargazerCount) stars"'

    编辑

    # Edit settings
gh repo edit --description "New description"
gh repo edit --homepage "https://example.com"
gh repo edit --enable-issues --enable-wiki
gh repo edit --enable-projects=false
gh repo edit --default-branch main
gh repo edit --enable-auto-merge
gh repo edit --delete-branch-on-merge
gh repo edit --add-topic "cli,automation"
gh repo edit --remove-topic "old-topic"
gh repo edit --template    # make it a template repo

# Change visibility (DANGEROUS — requires acknowledgment)
gh repo edit --visibility public --accept-visibility-change-consequences

    删除 / 归档

    gh repo delete owner/repo --yes          # requires delete_repo scope
gh repo archive owner/repo --yes
gh repo unarchive owner/repo --yes

    重命名

    gh repo rename new-name                  # renames current repo
gh repo rename new-name -R owner/repo

    设置默认

    # Set which remote is used for gh commands in this local clone
gh repo set-default owner/repo
gh repo set-default --view     # see current default
gh repo set-default --unset

    同步（复刻 ↔ 上游）

    # Sync local repo from remote parent
gh repo sync

# Sync specific branch
gh repo sync --branch v1

# Sync remote fork from its parent
gh repo sync owner/my-fork

# Sync from a specific source
gh repo sync owner/repo --source owner2/repo2

# Force sync (hard reset)
gh repo sync --force

    3. 议题

    创建

    gh issue create --title "Bug report" --body "Description here"
gh issue create --title "Bug" --label "bug,urgent" --assignee "@me"
gh issue create --title "Feature" --project "Roadmap" --milestone "v2.0"
gh issue create --template "Bug Report"       # use issue template
gh issue create --body-file description.md    # body from file
gh issue create -R owner/repo --title "Bug"   # different repo

    列表

    gh issue list
gh issue list --state closed
gh issue list --state all --limit 100
gh issue list --label "bug" --assignee "@me"
gh issue list --author monalisa
gh issue list --milestone "v2.0"
gh issue list --search "error no:assignee sort:created-asc"

# JSON output
gh issue list --json number,title,labels,state --jq '.[] | "#\(.number) \(.title)"'

    问题的JSON字段： assignees, author, body, closed, closedAt, comments, createdAt, id, isPinned, labels, milestone, number, projectCards, projectItems, reactionGroups, state, stateReason, title, updatedAt, url

    查看

    gh issue view 123
gh issue view 123 --web           # open in browser
gh issue view 123 --comments      # include comments
gh issue view 123 --json title,body,labels,assignees

# View by URL
gh issue view https://github.com/owner/repo/issues/123

    编辑

    gh issue edit 123 --title "New title" --body "New body"
gh issue edit 123 --add-label "bug,help wanted" --remove-label "core"
gh issue edit 123 --add-assignee "@me" --remove-assignee monalisa
gh issue edit 123 --add-project "Roadmap" --remove-project "v1"
gh issue edit 123 --milestone "v2.0"
gh issue edit 123 --remove-milestone
gh issue edit 123 --body-file body.md

# Bulk edit multiple issues
gh issue edit 123 456 789 --add-label "help wanted"

    关闭 / 重新打开

    gh issue close 123
gh issue close 123 --comment "Fixed in PR #456"
gh issue close 123 --reason "not planned"     # completed | not planned
gh issue reopen 123

    评论

    gh issue comment 123 --body "Hello from CLI"
gh issue comment 123 --body-file comment.md
gh issue comment 123 --edit-last              # edit your last comment

    置顶 / 取消置顶

    gh issue pin 123
gh issue unpin 123

    转移

    gh issue transfer 123 owner/other-repo

    锁定 / 解锁

    gh issue lock 123
gh issue unlock 123

    开发（关联分支）

    # Create a branch linked to issue
gh issue develop 123 --checkout
gh issue develop 123 --name "fix-bug-123" --base develop

# List linked branches
gh issue develop 123 --list

    删除

    gh issue delete 123 --yes

    4. 拉取请求

    创建

    gh pr create --title "Fix bug" --body "Description"
gh pr create --fill                    # auto-fill title/body from commits
gh pr create --fill-first              # use first commit only
gh pr create --fill-verbose            # use commit messages + bodies
gh pr create --draft                   # create as draft
gh pr create --base develop            # target branch
gh pr create --head owner:feature-branch
gh pr create --reviewer monalisa,hubot --reviewer myorg/team-name
gh pr create --label "bug" --assignee "@me"
gh pr create --project "Roadmap"
gh pr create --milestone "v2.0"
gh pr create --template "pull_request_template.md"
gh pr create --no-maintainer-edit      # prevent maintainers from pushing
gh pr create --dry-run                 # preview without creating

    列表

    gh pr list
gh pr list --state merged --limit 50
gh pr list --state all
gh pr list --author "@me"
gh pr list --assignee monalisa
gh pr list --label "bug" --label "priority"
gh pr list --base main
gh pr list --head feature-branch
gh pr list --draft                     # only drafts
gh pr list --search "status:success review:required"
gh pr list --search "<SHA>" --state merged   # find PR for a commit

# JSON output
gh pr list --json number,title,author,state --jq '.[].title'

    拉取请求的JSON字段： additions, assignees, author, autoMergeRequest, baseRefName, body, changedFiles, closed, closedAt, comments, commits, createdAt, deletions, files, headRefName, headRefOid, id, isDraft, labels, latestReviews, maintainerCanModify, mergeCommit, mergeStateStatus, mergeable, mergedAt, mergedBy, milestone, number, projectItems, reviewDecision, reviewRequests, reviews, state, statusCheckRollup, title, updatedAt, url

    查看

    gh pr view 123
gh pr view 123 --web
gh pr view 123 --comments
gh pr view 123 --json title,body,reviews,mergeable
gh pr view feature-branch              # by branch name

    检出

    gh pr checkout 123
gh pr checkout 123 --branch local-name
gh pr checkout 123 --force             # reset existing local branch
gh pr checkout 123 --recurse-submodules
gh co 123                              # alias

    差异

    gh pr diff 123
gh pr diff 123 --name-only             # list changed files
gh pr diff 123 --patch                 # patch format

    合并

    gh pr merge 123 --merge                # merge commit
gh pr merge 123 --squash               # squash merge
gh pr merge 123 --rebase               # rebase merge
gh pr merge 123 --squash --delete-branch
gh pr merge 123 --auto --squash        # enable auto-merge
gh pr merge 123 --disable-auto         # disable auto-merge
gh pr merge 123 --admin                # bypass merge queue / requirements
gh pr merge 123 --squash --subject "feat: new feature" --body "Details"

    评审

    gh pr review 123 --approve
gh pr review 123 --comment --body "LGTM"
gh pr review 123 --request-changes --body "Please fix the tests"
gh pr review                           # review current branch's PR

    检查（CI 状态）

    gh pr checks 123
gh pr checks 123 --watch               # live-update until done
gh pr checks 123 --watch --fail-fast   # stop on first failure
gh pr checks 123 --required            # only required checks
gh pr checks 123 --json name,state,bucket
gh pr checks 123 --web

# Exit codes: 0=pass, 1=fail, 8=pending

    检查的 JSON 字段： 存储桶、完成时间、描述、事件、链接、名称、开始时间、状态、工作流程

    编辑

    gh pr edit 123 --title "New title" --body "New body"
gh pr edit 123 --add-label "bug" --remove-label "wip"
gh pr edit 123 --add-reviewer monalisa --remove-reviewer hubot
gh pr edit 123 --add-assignee "@me"
gh pr edit 123 --add-project "Roadmap"
gh pr edit 123 --base develop          # change target branch
gh pr edit 123 --milestone "v2.0"

    关闭 / 重新打开

    gh pr close 123
gh pr close 123 --comment "Superseded by #456" --delete-branch
gh pr reopen 123

    就绪 / 草稿

    gh pr ready 123           # mark ready for review
gh pr ready 123 --undo    # convert back to draft (requires plan support)

    更新分支

    gh pr update-branch 123              # merge base into head
gh pr update-branch 123 --rebase    # rebase head onto base

    评论

    gh pr comment 123 --body "Comment text"
gh pr comment 123 --body-file comment.md

    锁定 / 解锁

    gh pr lock 123
gh pr unlock 123

    5. GitHub Actions（运行与工作流程）

    工作流程运行

    # List runs
gh run list
gh run list --limit 50
gh run list --workflow build.yml
gh run list --branch main
gh run list --status failure
gh run list --user monalisa
gh run list --event push
gh run list --commit abc123
gh run list --json name,status,conclusion,url

# View a run
gh run view 12345
gh run view 12345 --verbose            # show job steps
gh run view 12345 --log                # full log output
gh run view 12345 --log-failed         # only failed step logs
gh run view 12345 --job 456789         # specific job
gh run view 12345 --job 456789 --log   # specific job logs
gh run view 12345 --attempt 3          # specific attempt
gh run view 12345 --web

# Watch a run (live progress)
gh run watch 12345
gh run watch 12345 --exit-status       # exit non-zero on failure

# Rerun
gh run rerun 12345                     # rerun entire run
gh run rerun 12345 --failed            # rerun only failed jobs
gh run rerun 12345 --debug             # rerun with debug logging
gh run rerun 12345 --job 456789        # rerun specific job

# ⚠️ GOTCHA: --job needs databaseId, NOT the number from the URL!
# Get the right ID:
gh run view 12345 --json jobs --jq '.jobs[] | {name, databaseId}'

# Cancel
gh run cancel 12345

# Delete
gh run delete 12345

# Download artifacts
gh run download 12345                  # all artifacts
gh run download 12345 --name "build-output"
gh run download 12345 --dir ./artifacts
gh run download --name "coverage" --pattern "*.xml"

    运行的 JSON 字段： 尝试次数、结论、创建时间、数据库 ID、显示标题、事件、头部分支、头部 SHA、名称、编号、开始时间、状态、更新时间、URL、工作流程数据库 ID、工作流程名称

    工作流程

    # List workflows
gh workflow list
gh workflow list --all                  # include disabled

# View a workflow
gh workflow view build.yml
gh workflow view build.yml --web

# Run a workflow (workflow_dispatch)
gh workflow run build.yml
gh workflow run build.yml --ref my-branch
gh workflow run build.yml -f name=value -f env=prod
echo '{"name":"value"}' | gh workflow run build.yml --json

# Enable / disable
gh workflow enable build.yml
gh workflow disable build.yml

    6. 发布

    创建

    # Interactive
gh release create

# With tag + notes
gh release create v1.2.3 --notes "Bug fix release"
gh release create v1.2.3 --generate-notes            # auto-generated notes
gh release create v1.2.3 --notes-from-tag             # from annotated tag
gh release create v1.2.3 -F CHANGELOG.md              # notes from file
gh release create v1.2.3 --draft                      # save as draft
gh release create v1.2.3 --prerelease
gh release create v1.2.3 --latest=false               # don't mark as latest
gh release create v1.2.3 --target release-branch      # tag from specific branch
gh release create v1.2.3 --verify-tag                 # abort if tag doesn't exist
gh release create v1.2.3 --discussion-category "General"

# With assets
gh release create v1.2.3 ./dist/*.tar.gz
gh release create v1.2.3 'binary.zip#Linux Build'     # with display label

    列表 / 查看

    gh release list
gh release list --limit 50
gh release view v1.2.3
gh release view v1.2.3 --web
gh release view --json tagName,publishedAt,assets

    下载

    gh release download v1.2.3                    # all assets
gh release download v1.2.3 --pattern '*.deb'
gh release download v1.2.3 -p '*.deb' -p '*.rpm'
gh release download v1.2.3 --archive zip      # source code archive
gh release download v1.2.3 --dir ./downloads
gh release download v1.2.3 --output single-file.tar.gz
gh release download --pattern '*.AppImage'    # latest release (no tag arg)

    编辑 / 上传 / 删除

    gh release edit v1.2.3 --title "New Title" --notes "Updated notes"
gh release edit v1.2.3 --draft=false          # publish a draft
gh release edit v1.2.3 --prerelease=false
gh release upload v1.2.3 ./new-asset.zip
gh release upload v1.2.3 'asset.tar.gz#Display Label'
gh release delete v1.2.3 --yes
gh release delete-asset v1.2.3 asset-name

    7. Gists

    # Create
gh gist create file.py                        # secret gist
gh gist create --public file.py               # public gist
gh gist create file.py -d "My Python snippet"
gh gist create file1.py file2.js              # multi-file gist
echo "hello" | gh gist create -               # from stdin
cat data.json | gh gist create --filename data.json

# List
gh gist list
gh gist list --public
gh gist list --secret
gh gist list --limit 50

# View
gh gist view GIST_ID
gh gist view GIST_ID --raw                    # raw content
gh gist view GIST_ID --filename file.py       # specific file

# Edit
gh gist edit GIST_ID
gh gist edit GIST_ID --add newfile.txt
gh gist edit GIST_ID --filename file.py       # edit specific file

# Rename
gh gist rename GIST_ID old-name.py new-name.py

# Clone
gh gist clone GIST_ID

# Delete
gh gist delete GIST_ID

    8. 搜索

    仓库

    gh search repos "vim plugin"
gh search repos --owner=microsoft --visibility=public
gh search repos --language=go --stars=">1000"
gh search repos --topic=cli,automation
gh search repos --good-first-issues=">=10"
gh search repos --archived=false
gh search repos cli shell --sort stars --limit 10
gh search repos --json fullName,stargazersCount,description

    议题

    gh search issues "memory leak"
gh search issues --assignee=@me --state=open
gh search issues --owner=cli --label="bug"
gh search issues --comments=">100"
gh search issues --repo owner/repo "error"
gh search issues -- -label:bug                # exclude label
gh search issues --json number,title,repository,state

    拉取请求

    gh search prs "fix bug"
gh search prs --repo=cli/cli --draft
gh search prs --review-requested=@me --state=open
gh search prs --assignee=@me --merged
gh search prs --checks=success --review=approved
gh search prs --json number,title,repository,state

    提交

    gh search commits "bug fix"
gh search commits --author=monalisa
gh search commits --committer-date="<2024-01-01"
gh search commits --repo=cli/cli --hash=abc123
gh search commits --json sha,commit,repository

    代码

    gh search code "TODO" --repo=owner/repo
gh search code "import React" --language=typescript
gh search code "api_key" --filename=".env"
gh search code panic --owner=cli --extension=go
gh search code --json path,repository,textMatches

    9. 标签

    # List
gh label list
gh label list -R owner/repo
gh label list --json name,color,description

# Create
gh label create "priority:high" --color FF0000 --description "High priority"

# Edit
gh label edit "bug" --name "bug 🐛" --color 00FF00 --description "Something broken"

# Delete
gh label delete "old-label" --yes

# Clone labels from one repo to another
gh label clone source-owner/source-repo --repo dest-owner/dest-repo

    10. 密钥与变量

    密钥（加密）

    # Set (repo-level, for Actions)
gh secret set MY_SECRET --body "secret-value"
gh secret set MY_SECRET < secret-file.txt
echo "value" | gh secret set MY_SECRET

# Set for specific app
gh secret set MY_SECRET --app dependabot --body "value"
gh secret set MY_SECRET --app codespaces --body "value"

# Set environment secret
gh secret set MY_SECRET --env production --body "value"

# Set org-level secret
gh secret set MY_SECRET --org my-org --visibility all --body "value"
gh secret set MY_SECRET --org my-org --visibility selected --repos repo1,repo2

# Set user secret (for Codespaces)
gh secret set MY_SECRET --user --body "value"

# Bulk set from .env file
gh secret set -f .env

# List
gh secret list
gh secret list --env production
gh secret list --org my-org

# Delete
gh secret delete MY_SECRET
gh secret delete MY_SECRET --env production
gh secret delete MY_SECRET --org my-org

    变量（明文）

    # Set
gh variable set MY_VAR --body "value"
gh variable set MY_VAR --env staging --body "value"
gh variable set MY_VAR --org my-org --visibility all --body "value"

# Bulk set from .env file
gh variable set -f .env

# Get
gh variable get MY_VAR

# List
gh variable list
gh variable list --env production
gh variable list --org my-org

# Delete
gh variable delete MY_VAR
gh variable delete MY_VAR --env production

    11. 缓存

    # List Actions caches
gh cache list
gh cache list --limit 100
gh cache list --sort size --order desc

# Delete
gh cache delete CACHE_KEY
gh cache delete --all

    12. 项目 V2

    ⚠️ 需要项目范围：gh auth refresh -s project

    项目 V2 使用基于 GraphQL 的 ProjectsV2 API。CLI 为大多数操作提供了命令，但一些高级字段变更需要通过gh api graphql直接使用 GraphQL。

    列出项目

    gh project list                           # your projects
gh project list --owner my-org            # org projects
gh project list --owner my-org --closed   # include closed
gh project list --format json             # JSON output

    创建

    gh project create --owner "@me" --title "My Roadmap"
gh project create --owner my-org --title "Sprint Board"

    查看

    gh project view 1                         # by number
gh project view 1 --owner my-org
gh project view 1 --web                   # open in browser
gh project view 1 --format json

    编辑

    gh project edit 1 --owner "@me" --title "New Title"
gh project edit 1 --description "Updated description"
gh project edit 1 --readme "Project README content"
gh project edit 1 --visibility PUBLIC     # PUBLIC or PRIVATE

    关闭 / 重新打开 / 删除

    gh project close 1 --owner "@me"
gh project close 1 --owner "@me" --undo   # reopen
gh project delete 1 --owner "@me"

    复制

    gh project copy 1 --source-owner monalisa --target-owner my-org --title "Copied Project"
gh project copy 1 --source-owner monalisa --target-owner my-org --drafts  # include drafts

    关联/取消关联到仓库或团队

    gh project link 1 --owner monalisa --repo my-repo
gh project link 1 --owner my-org --team my-team
gh project unlink 1 --owner monalisa --repo my-repo

    标记为模板

    gh project mark-template 1 --owner my-org
gh project mark-template 1 --owner my-org --undo

    字段

    # List fields (shows IDs needed for item-edit)
gh project field-list 1 --owner "@me"
gh project field-list 1 --owner "@me" --format json

# Create field
gh project field-create 1 --owner "@me" --name "Priority" --data-type "SINGLE_SELECT" \
  --single-select-options "Low,Medium,High,Critical"
gh project field-create 1 --owner "@me" --name "Points" --data-type "NUMBER"
gh project field-create 1 --owner "@me" --name "Notes" --data-type "TEXT"
gh project field-create 1 --owner "@me" --name "Due Date" --data-type "DATE"

# Delete field
gh project field-delete --id FIELD_NODE_ID

    字段数据类型： 文本、单选、日期、数字
    （迭代字段必须通过网页界面或GraphQL创建）

    项目条目

    # List items
gh project item-list 1 --owner "@me"
gh project item-list 1 --owner "@me" --limit 100
gh project item-list 1 --owner "@me" --format json

# Add an existing issue/PR to project
gh project item-add 1 --owner "@me" --url https://github.com/owner/repo/issues/123

# Create a draft issue in project
gh project item-create 1 --owner "@me" --title "Draft task" --body "Details"

# Edit a draft issue (title/body)
gh project item-edit --id ITEM_NODE_ID --title "Updated title" --body "Updated body"

# Edit a field value on an item
gh project item-edit --id ITEM_NODE_ID --field-id FIELD_ID --project-id PROJECT_ID \
  --text "some value"
gh project item-edit --id ITEM_NODE_ID --field-id FIELD_ID --project-id PROJECT_ID \
  --number 5
gh project item-edit --id ITEM_NODE_ID --field-id FIELD_ID --project-id PROJECT_ID \
  --date "2024-12-31"
gh project item-edit --id ITEM_NODE_ID --field-id FIELD_ID --project-id PROJECT_ID \
  --single-select-option-id OPTION_ID
gh project item-edit --id ITEM_NODE_ID --field-id FIELD_ID --project-id PROJECT_ID \
  --iteration-id ITERATION_ID

# Clear a field value
gh project item-edit --id ITEM_NODE_ID --field-id FIELD_ID --project-id PROJECT_ID --clear

# Archive / unarchive item
gh project item-archive 1 --owner "@me" --id ITEM_NODE_ID
gh project item-archive 1 --owner "@me" --id ITEM_NODE_ID --undo

# Delete item from project
gh project item-delete 1 --owner "@me" --id ITEM_NODE_ID

    获取节点ID（编辑条目所必需）

    编辑条目命令需要条目、字段、项目和选项的节点ID。获取方法如下：通过GraphQL操作Projects V2（用于CLI无法完成的功能）

    # Get project ID and item IDs
gh project item-list 1 --owner "@me" --format json | jq '.'

# Get field IDs and single-select option IDs
gh project field-list 1 --owner "@me" --format json | jq '.'

# Via GraphQL (more control)
gh api graphql -f query='
  query {
    user(login: "USERNAME") {
      projectV2(number: 1) {
        id
        fields(first: 50) {
          nodes {
            ... on ProjectV2SingleSelectField {
              id
              name
              options { id name }
            }
            ... on ProjectV2IterationField {
              id
              name
              configuration {
                iterations { id title startDate duration }
              }
            }
            ... on ProjectV2Field {
              id
              name
              dataType
            }
          }
        }
      }
    }
  }
'

    某些操作需要使用GraphQL直接执行：

    Projects V2工作流（完整示例）

    # Update a field value (equivalent to item-edit but more flexible)
gh api graphql -f query='
  mutation {
    updateProjectV2ItemFieldValue(input: {
      projectId: "PVT_xxxx"
      itemId: "PVTI_xxxx"
      fieldId: "PVTF_xxxx"
      value: { singleSelectOptionId: "option_id" }
    }) {
      projectV2Item { id }
    }
  }
'

# Add issue/PR to project via GraphQL
gh api graphql -f query='
  mutation {
    addProjectV2ItemById(input: {
      projectId: "PVT_xxxx"
      contentId: "I_xxxx"
    }) {
      item { id }
    }
  }
'

# Update draft issue
gh api graphql -f query='
  mutation {
    updateProjectV2DraftIssue(input: {
      draftIssueId: "DI_xxxx"
      title: "New Title"
      body: "New body"
    }) {
      draftIssue { id title }
    }
  }
'

# Convert draft to real issue
gh api graphql -f query='
  mutation {
    convertProjectV2DraftIssueItemToIssue(input: {
      projectId: "PVT_xxxx"
      itemId: "PVTI_xxxx"
      repositoryId: "R_xxxx"
    }) {
      item {
        id
        content {
          ... on Issue { id number url }
        }
      }
    }
  }
'

# Get all items with field values
gh api graphql -f query='
  query {
    user(login: "USERNAME") {
      projectV2(number: 1) {
        items(first: 100) {
          nodes {
            id
            content {
              ... on Issue { title number url }
              ... on PullRequest { title number url }
              ... on DraftIssue { title body }
            }
            fieldValues(first: 20) {
              nodes {
                ... on ProjectV2ItemFieldTextValue { text field { ... on ProjectV2Field { name } } }
                ... on ProjectV2ItemFieldNumberValue { number field { ... on ProjectV2Field { name } } }
                ... on ProjectV2ItemFieldDateValue { date field { ... on ProjectV2Field { name } } }
                ... on ProjectV2ItemFieldSingleSelectValue { name field { ... on ProjectV2SingleSelectField { name } } }
                ... on ProjectV2ItemFieldIterationValue { title field { ... on ProjectV2IterationField { name } } }
              }
            }
          }
        }
      }
    }
  }
'

    13. API（REST与GraphQL）

    # 1. Create a project
gh project create --owner "@me" --title "Sprint 1"

# 2. Add fields
gh project field-create 1 --owner "@me" --name "Status" \
  --data-type SINGLE_SELECT --single-select-options "Todo,In Progress,Done"
gh project field-create 1 --owner "@me" --name "Priority" \
  --data-type SINGLE_SELECT --single-select-options "Low,Medium,High"
gh project field-create 1 --owner "@me" --name "Points" --data-type NUMBER

# 3. Get field IDs
FIELDS=$(gh project field-list 1 --owner "@me" --format json)
echo "$FIELDS" | jq '.'

# 4. Add issues to project
gh project item-add 1 --owner "@me" --url https://github.com/owner/repo/issues/1
gh project item-add 1 --owner "@me" --url https://github.com/owner/repo/issues/2

# 5. Create draft issues
gh project item-create 1 --owner "@me" --title "Research task" --body "Investigate X"

# 6. Set field values on items (need IDs from steps 3-5)
gh project item-edit --id ITEM_ID --field-id STATUS_FIELD_ID \
  --project-id PROJECT_ID --single-select-option-id TODO_OPTION_ID

# 7. Link project to repo
gh project link 1 --owner "@me" --repo my-repo

    REST API

    占位符

    # GET request (default)
gh api repos/{owner}/{repo}
gh api repos/cli/cli/releases --jq '.[].tag_name'

# With query parameters
gh api -X GET search/issues -f q='repo:cli/cli is:open label:bug'

# POST request
gh api repos/{owner}/{repo}/issues -f title="New Issue" -f body="Description"
gh api repos/{owner}/{repo}/issues/123/comments -f body='Comment text'

# PATCH / PUT / DELETE
gh api -X PATCH repos/{owner}/{repo} -f description="Updated"
gh api -X DELETE repos/{owner}/{repo}/issues/123/labels/bug

# With typed fields (-F for auto-type-conversion, -f for raw strings)
gh api repos/{owner}/{repo}/issues -f title="Bug" -F private=true -F number:=42

# Request body from file
gh api repos/{owner}/{repo}/issues --input issue.json

# Custom headers
gh api -H 'Accept: application/vnd.github.v3.raw+json' repos/{owner}/{repo}/readme

# Include response headers
gh api -i repos/{owner}/{repo}

# Verbose output (shows full HTTP request/response)
gh api --verbose repos/{owner}/{repo}

# Silent (no output)
gh api --silent repos/{owner}/{repo}/issues/123/labels -f labels[]=bug

# Caching
gh api --cache 3600s repos/{owner}/{repo}/releases

    Placeholders

    这些特殊占位符{owner}、{repo}和{branch}会根据当前的git目录或GH_REPO自动填充。

    分页

    # Auto-paginate REST results
gh api --paginate repos/{owner}/{repo}/issues --jq '.[].title'

# Slurp all pages into single array
gh api --paginate --slurp repos/{owner}/{repo}/issues | jq 'flatten | length'

    GraphQL API

    # Basic query
gh api graphql -f query='{ viewer { login } }'

# With variables
gh api graphql -F owner='{owner}' -F name='{repo}' -f query='
  query($owner: String!, $name: String!) {
    repository(owner: $owner, name: $name) {
      releases(last: 5) {
        nodes { tagName publishedAt }
      }
    }
  }
'

# Mutation
gh api graphql -f query='
  mutation {
    addStar(input: {starrableId: "MDEwOlJlcG9zaXRvcnkxMjM="}) {
      starrable { stargazerCount }
    }
  }
'

# Paginated GraphQL (requires $endCursor variable and pageInfo)
gh api graphql --paginate -f query='
  query($endCursor: String) {
    viewer {
      repositories(first: 100, after: $endCursor) {
        nodes { nameWithOwner }
        pageInfo { hasNextPage endCursor }
      }
    }
  }
'

# GraphQL with JQ filtering
gh api graphql -f query='{ viewer { repositories(first: 10) { nodes { nameWithOwner stargazerCount } } } }' \
  --jq '.data.viewer.repositories.nodes[] | "\(.nameWithOwner): \(.stargazerCount) ⭐"'

    常见GraphQL模式

    # Get repository ID (needed for many mutations)
gh api graphql -f query='query { repository(owner: "OWNER", name: "REPO") { id } }' \
  --jq '.data.repository.id'

# Get issue/PR node ID
gh api graphql -f query='
  query {
    repository(owner: "OWNER", name: "REPO") {
      issue(number: 123) { id }
    }
  }
' --jq '.data.repository.issue.id'

# Get user/org ID
gh api graphql -f query='query { user(login: "USERNAME") { id } }' --jq '.data.user.id'

# Check rate limit
gh api graphql -f query='{ rateLimit { limit remaining resetAt } }'
gh api rate_limit --jq '.rate'

    14. 扩展

    # Search for extensions
gh extension search "copilot"
gh extension search --limit 30

# Browse extensions in TUI
gh extension browse

# Install
gh extension install owner/gh-extension-name
gh extension install https://github.com/owner/gh-extension-name

# List installed
gh extension list

# Upgrade
gh extension upgrade extension-name
gh extension upgrade --all

# Remove
gh extension remove extension-name

# Execute (useful if name conflicts with core command)
gh extension exec extension-name

# Create a new extension
gh extension create my-extension
gh extension create my-extension --precompiled=go

    15. Codespaces

    # List
gh codespace list

# Create
gh codespace create --repo owner/repo
gh codespace create --repo owner/repo --branch feature --machine largePremiumLinux

# SSH into codespace
gh codespace ssh

# Open in VS Code
gh codespace code

# Copy files
gh codespace cp local-file.txt remote:~/path/
gh codespace cp remote:~/path/file.txt ./local/

# View details
gh codespace view

# Port forwarding
gh codespace ports

# Rebuild
gh codespace rebuild

# Stop / Delete
gh codespace stop
gh codespace delete

    16. Copilot

    （需要gh-copilot扩展）

    # Suggest a command
gh copilot suggest "find large files in current directory"

# Explain a command
gh copilot explain "find . -type f -size +100M -exec ls -lh {} +"

# Configure
gh copilot config

    17. 其他命令

    浏览（在浏览器中打开）

    gh browse                          # repo home
gh browse 123                      # issue or PR #123
gh browse src/main.go              # specific file
gh browse src/main.go:42           # file at line
gh browse --settings               # repo settings
gh browse --projects                # repo projects
gh browse --releases                # repo releases
gh browse --branch feature src/    # specific branch
gh browse --commit abc123          # specific commit
gh browse -n                       # print URL instead of opening

    状态（跨仓库概览）

    gh status                          # assigned issues, PRs, review requests, mentions
gh status --org my-org             # limit to org
gh status -e owner/repo            # exclude repo

    别名

    gh alias set pv 'pr view'
gh alias set bugs 'issue list --label=bug'
gh alias set --shell igrep 'gh issue list --label="$1" | grep "$2"'
gh alias list
gh alias delete pv
gh alias import aliases.yml

    SSH密钥 / GPG密钥

    gh ssh-key list
gh ssh-key add ~/.ssh/id_ed25519.pub --title "My Laptop"
gh ssh-key delete KEY_ID

gh gpg-key list
gh gpg-key add pubkey.gpg
gh gpg-key delete KEY_ID

    规则集

    gh ruleset list
gh ruleset view RULESET_ID
gh ruleset check branch-name      # what rules apply to this branch

    证明

    gh attestation verify artifact.tar.gz --owner owner
gh attestation download --owner owner artifact.tar.gz

    组织

    gh org list

    18. JSON输出与格式化

    大多数列表/查看命令支持--json、--jq和--template参数。

    基础JSON

    # Discover available fields (pass --json with no value)
gh pr list --json

# Select specific fields
gh pr list --json number,title,author

# JQ filtering
gh pr list --json number,title,author --jq '.[].author.login'
gh issue list --json number,title,labels --jq '
  map(select(.labels | length > 0))
  | map(.labels = (.labels | map(.name)))
  | .[:5]
'

    Go模板格式化

    # Table output
gh pr list --json number,title,headRefName,updatedAt --template \
  '{{range .}}{{tablerow (printf "#%v" .number | autocolor "green") .title .headRefName (timeago .updatedAt)}}{{end}}'

# Hyperlinks
gh issue list --json title,url --template \
  '{{range .}}{{hyperlink .url .title}}{{"\n"}}{{end}}'

# Color
gh pr list --json title,state --template \
  '{{range .}}{{.title}} ({{.state | color "green"}}){{"\n"}}{{end}}'

    模板函数

    函数描述
    autocolor <样式> <输入>智能着色（终端感知）
    color <样式> <输入>强制着色
    join <分隔符> <列表>连接列表值
    pluck <字段> <列表>从列表项提取字段
    tablerow <字段>...对齐表格列
    tablerender渲染累积的表格行
    timeago <时间>相对时间戳
    timefmt <格式> <时间>格式化时间戳
    truncate <长度> <输入>截断文本
    hyperlink <网址> <文本>终端超链接

    19. 环境变量

    变量用途
    GH_TOKEN/GITHUB_TOKENgithub.com 的认证令牌（优先于存储的凭据）
    GH_ENTERPRISE_TOKEN/GITHUB_ENTERPRISE_TOKENGHES 的认证令牌
    GH_HOST默认 GitHub 主机名
    GH_REPO[主机名/]所有者/仓库名 中的默认仓库 [HOST/]OWNER/REPO格式
    GH_EDITOR用于撰写文本的编辑器
    GH_BROWSER/BROWSER用于打开链接的网页浏览器
    GH_PAGER/PAGER终端分页器（例如，less）
    GH_DEBUG启用详细输出（1或api用于HTTP流量）
    GH_FORCE_TTY强制终端输出（值 = 列数或百分比）
    GH_PROMPT_DISABLED禁用交互式提示
    GH_NO_UPDATE_NOTIFIER禁用更新通知
    GH_CONFIG_DIR自定义配置目录
    NO_COLOR禁用彩色输出
    GLAMOUR_STYLEMarkdown 渲染样式

    20. 高级模式

    脚本编写最佳实践

    # Disable prompts for non-interactive use
GH_PROMPT_DISABLED=1 gh pr create --fill

# Use GH_TOKEN for CI/automation
GH_TOKEN=${{ github.token }} gh pr list

# Use GH_REPO to avoid -R everywhere
export GH_REPO=owner/repo
gh issue list   # targets owner/repo

    批量操作

    # Close all issues with a label
gh issue list --label "wontfix" --json number --jq '.[].number' | \
  xargs -I{} gh issue close {} --reason "not planned"

# Add label to all open PRs
gh pr list --json number --jq '.[].number' | \
  xargs -I{} gh pr edit {} --add-label "needs-review"

# Download all artifacts from recent failed runs
gh run list --status failure --json databaseId --jq '.[].databaseId' | \
  xargs -I{} gh run download {}

    多账户操作

    # List configured accounts
gh auth status

# Switch active account
gh auth switch

# Use a specific token for one command
GH_TOKEN=ghp_xxx gh api user --jq '.login'

# Login to multiple hosts
gh auth login --hostname github.com
gh auth login --hostname github.enterprise.com

    速率限制

    # Check current rate limit
gh api rate_limit --jq '.rate | "\(.remaining)/\(.limit) (resets \(.reset | strftime("%H:%M:%S")))"'

# GraphQL rate limit (separate pool)
gh api graphql -f query='{ rateLimit { limit remaining resetAt } }'

# Use caching to reduce API calls
gh api --cache 3600s repos/{owner}/{repo}/releases

    复杂 API 模式

    # Nested parameters
gh api gists -F 'files[myfile.txt][content]=@myfile.txt'

# Array parameters
gh api -X PATCH /orgs/{org}/properties/schema \
  -F 'properties[][property_name]=env' \
  -F 'properties[][allowed_values][]=staging' \
  -F 'properties[][allowed_values][]=production'

# Combine REST pagination with JQ
gh api --paginate repos/{owner}/{repo}/issues --jq '[.[] | select(.labels | length > 0)] | length'

# GraphQL with slurp for aggregation
gh api graphql --paginate --slurp -f query='
  query($endCursor: String) {
    viewer {
      repositories(first: 100, after: $endCursor) {
        nodes { isFork stargazerCount }
        pageInfo { hasNextPage endCursor }
      }
    }
  }
' | jq '[.[].data.viewer.repositories.nodes[]] | map(.stargazerCount) | add'

    21. 技巧与注意事项

    常见错误

    1. --json字段名称与 API 字段名称不同。例如，PR 文件使用files（而非changed_files），作者使用author.login（而非user.login）。请始终运行gh <cmd> --json不带参数时查看可用字段。

    2. gh run rerun --job需要数据库ID，而非URL中的数字。可通过以下方式获取：

      gh run view RUN_ID --json jobs --jq '.jobs[] | {name, databaseId}'

    3. 项目V2需要project作用域。若遇到权限错误：

      gh auth refresh -s project

    4. gh repo delete需要delete_repo作用域：

      gh auth refresh -s delete_repo

    5. Shell中的子命令引用：PowerShell及某些Shell需要对{owner}进行转义。请使用引号："{owner}"。

    使用时机gh api与特定命令的对比

    在以下情况下使用特定命令...使用gh api当...
    命令行工具存在并满足你的需求没有命令行工具覆盖该端点
    你需要交互式提示你需要细粒度控制
    你想要格式美观的输出你想要原始的JSON响应
    你正在进行简单的增删改查操作你需要GraphQL查询
    你需要设置自定义请求头
    你需要控制分页

    性能优化技巧

    • 使用--limit参数仅获取所需数据
    • 使用--json参数并指定特定字段（减少数据获取量）
    • 使用--cache参数配合gh api命令进行缓存用于频繁访问、变化缓慢的数据
    • 使用--paginate --slurp对所有页面进行聚合操作
    • 设置GH_PAGER=cat在脚本中禁用分页功能

    退出代码

    代码含义
    0成功
    1错误/失败
    2用法错误
    4命令已取消
    8检查待处理（针对gh pr checks命令）

    认证优先级

    1. GH_TOKEN/GITHUB_TOKEN环境变量
    2. GH_ENTERPRISE_TOKEN（针对 GHES 主机）
    3. 来自gh auth login
    4. 的存储凭据仓库中的 .env 文件（仅在配置时）

    实用单行命令

    # My open PRs across all repos
gh search prs --author=@me --state=open --json repository,number,title

# Repos I starred recently
gh api --paginate user/starred --jq '.[].full_name' | head -20

# Who's the top contributor to a repo
gh api --paginate repos/owner/repo/contributors --jq '.[] | "\(.login): \(.contributions)"' | head -10

# Create issue from clipboard
pbpaste | gh issue create --title "From clipboard" --body-file -

# Get latest release tag
gh release view --json tagName --jq '.tagName'

# Watch CI and notify on completion
gh run watch && notify-send "CI done!"

# Export all issues as JSON
gh issue list --state all --limit 9999 --json number,title,state,labels,assignees > issues.json

# Find which PR merged a commit
gh pr list --search "SHA_HERE" --state merged --json number,title,url
    免责申明
    部分文章来自各大搜索引擎，如有侵权，请与我联系删除。
    打赏
    文章底部电脑广告
    手机广告位-内容正文底部
    标签
    上一篇：Smart Model Switching 下一篇：Apollo

    相关文章

    推荐文章
    图片测量软件工具下载链接

    图片测量软件工具下载链接

    图片测量工具使用帮助

    图片测量工具使用帮助

    热门浏览
    标签列表

    您是本站第289863名访客 今日有232篇新文章/评论