Manage a GitHub Project Safely with gh project

You will finish with a practical command-line workflow for finding a GitHub Project, inspecting its fields and items, and adding work to it. The examples match GitHub CLI 2.87.3, the installed command version on this machine.

Allow about fifteen minutes. You need GitHub CLI, a login to the relevant GitHub host, and a project owner and number. The token needs the project scope, which is not granted by default. The commands that inspect data are ordinary user commands. Creating, editing, linking, closing or deleting a project changes remote state, so read the warning before running those examples.

1. Check the installed CLI and token

Confirm the executable before relying on a flag. This does not contact GitHub:

$ gh --version
gh version 2.87.3 (2026-02-23)

Now check the active account and its scopes:

$ gh auth status
github.com
  ✓ Logged in to github.com account YOUR_LOGIN
  - Active account: true
  - Token scopes: 'project', ...

The account name and the rest of the scope list vary. If project is absent, refresh the login before using project commands:

$ gh auth refresh -s project

This changes the stored authorisation for your GitHub CLI login. Complete the browser or device flow that GitHub presents, then run gh auth status again. Do not paste a token into a shell command or put it in a script.

2. Find the project owner and number

List the current user's open Projects. The default limit is 30:

$ gh project list --owner "@me"
NUMBER  TITLE                 STATE  ID
1       Release planning      open   PVT_...
2       Internal backlog      open   PVT_...

The table is illustrative: titles, numbers and IDs depend on the account. Add --closed when you need closed projects, or --limit 100 when more than 30 projects could match. For an organisation, replace @me with its login:

$ gh project list --owner ORGANISATION_LOGIN --limit 100

Record the numeric NUMBER, not the opaque ID, for the commands in this guide. If the command reports an authentication or permission error, return to step 1. A different owner can have a project number with the same value.

3. Inspect the project before changing it

View the project using its owner and number:

$ gh project view PROJECT_NUMBER --owner OWNER_LOGIN
Title: Release planning
Number: 1
State: open

For a machine-readable result, request JSON and select fields with the CLI's jq option:

$ gh project view PROJECT_NUMBER --owner OWNER_LOGIN --format json \
    --jq '{title,number,state}'
{"title":"Release planning","number":1,"state":"open"}

Before adding an issue, inspect the fields and current items:

$ gh project field-list PROJECT_NUMBER --owner OWNER_LOGIN
$ gh project item-list PROJECT_NUMBER --owner OWNER_LOGIN --limit 100

These commands fetch up to 30 fields or items by default. Increase the limit deliberately; a large project can produce enough output to become a distraction. Item filtering is available on supported API hosts, including GitHub.com and GHES 3.20 or newer:

$ gh project item-list PROJECT_NUMBER --owner OWNER_LOGIN \
    --query 'assignee:@me is:issue is:open'

4. Create a project only when you need one

Creation is a remote change. Check the owner and title carefully first:

$ gh project create --owner OWNER_LOGIN --title "Release planning"
Created project 3

Capture the number from the real output, then immediately inspect it with gh project view. If you created the wrong project, deletion is permanent and may remove project data. Prefer closing it while you investigate:

$ gh project close PROJECT_NUMBER --owner OWNER_LOGIN

To undo that particular close, reopen it:

$ gh project close PROJECT_NUMBER --owner OWNER_LOGIN --undo

Do not use gh project delete as a general undo. It deletes the project and has no corresponding --undo flag. Treat deletion as irreversible unless you have confirmed a separate recovery plan.

5. Add existing work to the project

Adding an issue or pull request changes the project but does not create a new issue. Use its complete URL and quote it:

$ gh project item-add PROJECT_NUMBER --owner OWNER_LOGIN \
    --url https://github.com/OWNER/REPOSITORY/issues/123
Added item to project

Verify that the item now appears:

$ gh project item-list PROJECT_NUMBER --owner OWNER_LOGIN --limit 100

If the URL is wrong, stop and check the repository and issue number rather than repeatedly adding it. The command is for an issue or pull request URL, not an arbitrary web page.

6. Edit or link with a clear rollback

Editing can replace the title, description or README, so save the current values with gh project view --format json before changing them. A visibility change also affects who can see the project:

$ gh project edit PROJECT_NUMBER --owner OWNER_LOGIN \
    --title "Release planning 2026" --visibility PRIVATE

To undo this example, restore the previous title and visibility explicitly after checking the saved values. Do not guess the old README or description.

Linking associates a project with a repository or team. Supply exactly one target and verify the result in GitHub afterwards:

$ gh project link PROJECT_NUMBER --owner OWNER_LOGIN --repo REPOSITORY_NAME

The corresponding recovery command is gh project unlink with the same owner and target. Linking or unlinking does not move issues between repositories.