GitHub Projects CLI

GitHub Projects (v2) management via

gh project

commands. Requires the

project

scope which can be added with

gh auth refresh -s project

.

通过

gh project

命令管理GitHub Projects (v2)。需要

project

权限范围，可通过

gh auth refresh -s project

添加。

Prerequisites

前提条件

Verify authentication includes project scope:

bash

gh auth status  # Check current scopes
gh auth refresh -s project  # Add project scope if missing

验证身份验证是否包含project权限范围：

bash

gh auth status  # 检查当前权限范围
gh auth refresh -s project  # 若缺失则添加project权限范围

Quick Reference

快速参考

List & View Projects

列出与查看项目

bash

undefined

bash

undefined

List your projects

列出你的项目

gh project list

List org projects (including closed)

列出组织项目（包括已关闭的）

gh project list --owner ORG_NAME --closed

View project details

查看项目详情

gh project view PROJECT_NUM --owner OWNER

Open in browser

在浏览器中打开

gh project view PROJECT_NUM --owner OWNER --web

JSON output with jq filtering

结合jq过滤的JSON输出

gh project list --format json | jq '.projects[] | {number, title}'

undefined

gh project list --format json | jq '.projects[] | {number, title}'

undefined

Create & Edit Projects

创建与编辑项目

bash

undefined

bash

undefined

Create project

创建项目

gh project create --owner OWNER --title "Project Title"

Edit project

编辑项目

gh project edit PROJECT_NUM --owner OWNER --title "New Title" gh project edit PROJECT_NUM --owner OWNER --description "New description" gh project edit PROJECT_NUM --owner OWNER --visibility PUBLIC

Close/reopen project

关闭/重新打开项目

gh project close PROJECT_NUM --owner OWNER gh project close PROJECT_NUM --owner OWNER --undo # Reopen

undefined

gh project close PROJECT_NUM --owner OWNER gh project close PROJECT_NUM --owner OWNER --undo # 重新打开

undefined

Link Projects to Repos

关联项目与仓库

bash

undefined

bash

undefined

Link to repo

关联到仓库

gh project link PROJECT_NUM --owner OWNER --repo REPO_NAME

Link to team

关联到团队

gh project link PROJECT_NUM --owner ORG --team TEAM_NAME

Unlink

取消关联

gh project unlink PROJECT_NUM --owner OWNER --repo REPO_NAME

undefined

gh project unlink PROJECT_NUM --owner OWNER --repo REPO_NAME

undefined

Project Items

项目事项

Add Existing Issues/PRs

添加现有议题/拉取请求

bash

undefined

bash

undefined

Add issue to project

向项目添加议题

gh project item-add PROJECT_NUM --owner OWNER --url https://github.com/OWNER/REPO/issues/123

Add PR to project

向项目添加拉取请求

gh project item-add PROJECT_NUM --owner OWNER --url https://github.com/OWNER/REPO/pull/456

undefined

gh project item-add PROJECT_NUM --owner OWNER --url https://github.com/OWNER/REPO/pull/456

undefined

Create Draft Items

创建草稿事项

bash

gh project item-create PROJECT_NUM --owner OWNER --title "Draft item" --body "Description"

bash

gh project item-create PROJECT_NUM --owner OWNER --title "Draft item" --body "Description"

List Items

列出事项

bash

undefined

bash

undefined

List items (default 30)

列出事项（默认30条）

gh project item-list PROJECT_NUM --owner OWNER

List more items

列出更多事项

gh project item-list PROJECT_NUM --owner OWNER --limit 100

JSON output

JSON输出

gh project item-list PROJECT_NUM --owner OWNER --format json

undefined

gh project item-list PROJECT_NUM --owner OWNER --format json

undefined

Edit Items

编辑事项

Items are edited by their ID (obtained from

item-list --format json

).

bash

undefined

事项需通过其ID（从

item-list --format json

获取）进行编辑。

bash

undefined

Edit draft issue title/body

编辑草稿议题的标题/正文

gh project item-edit --id ITEM_ID --title "New Title" --body "New body"

Update field value (requires field-id and project-id)

更新字段值（需要field-id和project-id）

gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --text "value" gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --number 42 gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --date "2024-12-31" gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --single-select-option-id OPTION_ID gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --iteration-id ITER_ID

Clear field value

清空字段值

gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --clear

undefined

gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --clear

undefined

Archive/Delete Items

归档/删除事项

bash

gh project item-archive PROJECT_NUM --owner OWNER --id ITEM_ID
gh project item-delete PROJECT_NUM --owner OWNER --id ITEM_ID

bash

gh project item-archive PROJECT_NUM --owner OWNER --id ITEM_ID
gh project item-delete PROJECT_NUM --owner OWNER --id ITEM_ID

Project Fields

项目字段

List Fields

列出字段

bash

gh project field-list PROJECT_NUM --owner OWNER
gh project field-list PROJECT_NUM --owner OWNER --format json

bash

gh project field-list PROJECT_NUM --owner OWNER
gh project field-list PROJECT_NUM --owner OWNER --format json

Create Fields

创建字段

bash

undefined

bash

undefined

Text field

文本字段

gh project field-create PROJECT_NUM --owner OWNER --name "Notes" --data-type TEXT

Number field

数字字段

gh project field-create PROJECT_NUM --owner OWNER --name "Points" --data-type NUMBER

Date field

日期字段

gh project field-create PROJECT_NUM --owner OWNER --name "Due Date" --data-type DATE

Single select with options

带选项的单选字段

gh project field-create PROJECT_NUM --owner OWNER --name "Priority"
--data-type SINGLE_SELECT
--single-select-options "Low,Medium,High,Critical"

undefined

gh project field-create PROJECT_NUM --owner OWNER --name "Priority"
--data-type SINGLE_SELECT
--single-select-options "Low,Medium,High,Critical"

undefined

Delete Fields

删除字段

bash

gh project field-delete --id FIELD_ID

bash

gh project field-delete --id FIELD_ID

Common Workflows

常见工作流

Add Issue and Set Status

添加议题并设置状态

bash

undefined

bash

undefined

1. Add issue to project

1. 向项目添加议题

gh project item-add 1 --owner "@me" --url https://github.com/owner/repo/issues/123

2. Get item ID and field IDs

2. 获取事项ID和字段ID

gh project item-list 1 --owner "@me" --format json | jq '.items[-1]' gh project field-list 1 --owner "@me" --format json

3. Update status field

3. 更新状态字段

gh project item-edit --id ITEM_ID --project-id PROJECT_ID
--field-id STATUS_FIELD_ID --single-select-option-id OPTION_ID

undefined

gh project item-edit --id ITEM_ID --project-id PROJECT_ID
--field-id STATUS_FIELD_ID --single-select-option-id OPTION_ID

undefined

Bulk Add Issues

批量添加议题

bash

undefined

bash

undefined

Add all open issues from a repo

添加仓库中所有开放的议题

gh issue list --repo owner/repo --state open --json url -q '.[].url' |
xargs -I {} gh project item-add 1 --owner "@me" --url {}

undefined

gh issue list --repo owner/repo --state open --json url -q '.[].url' |
xargs -I {} gh project item-add 1 --owner "@me" --url {}

undefined

JSON Output & jq Patterns

JSON输出与jq模式

bash

undefined

bash

undefined

Get project IDs

获取项目ID

gh project list --format json | jq '.projects[] | {number, id, title}'

Get field IDs and options

获取字段ID和选项

gh project field-list 1 --owner "@me" --format json | jq '.fields[] | {id, name, options}'

Get item IDs with field values

获取带有字段值的事项ID

gh project item-list 1 --owner "@me" --format json | jq '.items[] | {id, title, fieldValues}'

Filter items by status

按状态过滤事项

gh project item-list 1 --owner "@me" --format json |
jq '.items[] | select(.status == "In Progress")'

undefined

gh project item-list 1 --owner "@me" --format json |
jq '.items[] | select(.status == "In Progress")'

undefined

Reference Files

参考文件

items.md: Item management, editing field values, bulk operations
fields.md: Field types, creating custom fields, option management

items.md: 事项管理、编辑字段值、批量操作
fields.md: 字段类型、创建自定义字段、选项管理

Command Summary

命令汇总

Command	Purpose
`project list`	List projects
`project view`	View project details
`project create`	Create new project
`project edit`	Modify project settings
`project close`	Close/reopen project
`project link/unlink`	Connect to repo/team
`project item-add`	Add existing issue/PR
`project item-create`	Create draft item
`project item-list`	List project items
`project item-edit`	Update item fields
`project item-archive`	Archive item
`project item-delete`	Remove item
`project field-list`	List project fields
`project field-create`	Add custom field
`project field-delete`	Remove field

命令	用途
`project list`	列出项目
`project view`	查看项目详情
`project create`	创建新项目
`project edit`	修改项目设置
`project close`	关闭/重新打开项目
`project link/unlink`	关联到仓库/团队
`project item-add`	添加现有议题/拉取请求
`project item-create`	创建草稿事项
`project item-list`	列出项目事项
`project item-edit`	更新事项字段
`project item-archive`	归档事项
`project item-delete`	删除事项
`project field-list`	列出项目字段
`project field-create`	添加自定义字段
`project field-delete`	删除字段

github-projects

Original

Translation

GitHub Projects CLI

GitHub Projects CLI

Prerequisites

前提条件

Quick Reference

快速参考

List & View Projects

列出与查看项目

List your projects

列出你的项目

List org projects (including closed)

列出组织项目（包括已关闭的）

View project details

查看项目详情

Open in browser

在浏览器中打开

JSON output with jq filtering

结合jq过滤的JSON输出

Create & Edit Projects

创建与编辑项目

Create project

创建项目

Edit project

编辑项目

Close/reopen project

关闭/重新打开项目

Link Projects to Repos

关联项目与仓库

Link to repo

关联到仓库

Link to team

关联到团队

Unlink

取消关联

Project Items

项目事项

Add Existing Issues/PRs

添加现有议题/拉取请求

Add issue to project

向项目添加议题

Add PR to project

向项目添加拉取请求

Create Draft Items

创建草稿事项

List Items

列出事项

List items (default 30)

列出事项（默认30条）

List more items

列出更多事项

JSON output

JSON输出

Edit Items

编辑事项

Edit draft issue title/body

编辑草稿议题的标题/正文

Update field value (requires field-id and project-id)

更新字段值（需要field-id和project-id）

Clear field value

清空字段值

Archive/Delete Items

归档/删除事项

Project Fields

项目字段

List Fields

列出字段

Create Fields

创建字段

Text field

文本字段

Number field

数字字段

Date field

日期字段

Single select with options

带选项的单选字段

Delete Fields