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 .
Prerequisites
Verify authentication includes project scope:
gh auth status # Check current scopes gh auth refresh -s project # Add project scope if missing
Quick Reference
List & View Projects
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
gh project list --format json | jq '.projects[] | {number, title}'
Create & Edit Projects
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
Link Projects to Repos
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
Project Items
Add Existing Issues/PRs
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
Create Draft Items
gh project item-create PROJECT_NUM --owner OWNER --title "Draft item" --body "Description"
List Items
List items (default 30)
gh project item-list PROJECT_NUM --owner OWNER
List more items
gh project item-list PROJECT_NUM --owner OWNER --limit 100
JSON output
gh project item-list PROJECT_NUM --owner OWNER --format json
Edit Items
Items are edited by their ID (obtained from item-list --format json ).
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)
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
Archive/Delete Items
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
gh project field-list PROJECT_NUM --owner OWNER gh project field-list PROJECT_NUM --owner OWNER --format json
Create Fields
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"
Delete Fields
gh project field-delete --id FIELD_ID
Common Workflows
Add Issue and Set Status
1. Add issue to project
gh project item-add 1 --owner "@me" --url https://github.com/owner/repo/issues/123
2. Get item ID and field IDs
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
gh project item-edit --id ITEM_ID --project-id PROJECT_ID
--field-id STATUS_FIELD_ID --single-select-option-id OPTION_ID
Bulk Add Issues
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 {}
JSON Output & jq Patterns
Get project IDs
gh project list --format json | jq '.projects[] | {number, id, title}'
Get field IDs and options
gh project field-list 1 --owner "@me" --format json | jq '.fields[] | {id, name, options}'
Get item IDs with field values
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")'
Reference Files
-
items.md: Item management, editing field values, bulk operations
-
fields.md: Field types, creating custom fields, option management
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