github-projects

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

Gates (destructive and high-impact)

Commands like project close, project unlink, item-archive, item-delete, and field-delete change or remove data. Use a sequenced check, not recall from an earlier turn.

1. Pass: Run gh project view PROJECT_NUM --owner OWNER (or gh project list --owner OWNER --format json) and confirm the title (or title in JSON) matches the project you intend.
2. Pass: For items and fields, set ITEM_ID, FIELD_ID, PROJECT_ID, and option IDs only from gh project item-list … --format json or gh project field-list … --format json in this session—not guessed, truncated, or copied from unrelated output.
3. Then run the destructive subcommand.

Bulk add (pipelines)

1. Pass: Run gh project item-add once for a single --url and confirm the item appears in gh project item-list … --format json (or the UI) before using xargs or loops on many URLs.

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