Archive a GitHub Project Item Safely with gh

The board is cluttered with finished cards, and gh project item-archive tidies them away without deleting a thing. You will archive one item, then learn how to reverse it. Allow about ten minutes if you already know the project number and item ID, plus an extra minute to check the identifiers, because the command changes remote project state.

1. Check the installed command

This guide follows GitHub CLI 2.87.3, installed on the machine used for these examples. Its manual page describes gh project item-archive as archiving an item in a project.

• Takes three things. A project number, an item ID and an owner.
• Has an undo. The --undo flag unarchives.

$ gh --version
gh version 2.87.3 (2026-02-23)
https://github.com/cli/cli/releases/tag/v2.87.3

$ gh project item-archive --help
Archive an item in a project

2. Set the project owner and number

The positional number is the project number, not the item ID. The owner selects the account or organisation that owns the project.

• Your own project: the documented value is @me.
• Anyone else's: use a named organisation or account, which is also clearer in a script.

$ OWNER='@me'
$ PROJECT_NUMBER='1'
$ gh project view "$PROJECT_NUMBER" --owner "$OWNER"

Read the project details and confirm that the title and owner are the ones you expect. Replace both placeholder values before running the command.

3. Find the item's exact ID

Archive operates on the project's item ID, supplied with --id. This is not the issue number, pull request number, URL or visible title. List the project as JSON and inspect the item whose title or content matches your intended target.

$ gh project item-list "$PROJECT_NUMBER" --owner "$OWNER" --format json

Save the exact value from that item's id field in a variable. A project can contain similarly named items, so compare the title and content as well as the ID. If the list is long, use the command's JSON output with a local JSON tool to narrow your inspection, but review the resulting ID before using it.

$ ITEM_ID='PVTI_REPLACE_WITH_THE_EXACT_ITEM_ID'
$ test -n "$ITEM_ID" && printf 'selected item ID: %s\n' "$ITEM_ID"
selected item ID: PVTI_REPLACE_WITH_THE_EXACT_ITEM_ID

4. Archive the item

Archiving is a remote state change. It is not the same as deleting the item, closing the issue, or removing the issue from GitHub. If the item is part of a shared workflow, warn anyone relying on the project view before you continue.

$ gh project item-archive "$PROJECT_NUMBER" --owner "$OWNER" --id "$ITEM_ID"

The installed manual documents exit status 0 as successful execution. The command normally needs no sudo: it makes an authenticated GitHub API request and does not change local system files. A successful run may produce no useful human-readable confirmation, so use the exit status as the immediate check:

$ status=$?
$ printf 'archive exit status: %s\n' "$status"
archive exit status: 0

5. Undo an archive

Picked the wrong item, or the item needs to return to the project view? Use the same project, owner and ID with --undo. This is another remote state change, so check the values before running it.

$ gh project item-archive "$PROJECT_NUMBER" --owner "$OWNER" --id "$ITEM_ID" --undo
$ printf 'unarchive exit status: %s\n' "$?"
unarchive exit status: 0

There is no need to recreate the issue or pull request. The undo operation reverses the archived state for the project item identified by --id.

6. Diagnose a failed command

Keep the error text and exit status. The manual lists exit status 1 for an error, 2 when the command is cancelled, and 4 when authentication is required. Specific commands can have additional exit codes.

• Authentication required. Run gh auth status and confirm that the account and GitHub host are correct. Refresh the project scope through your normal authentication process if it is missing.
• Project not found. Check the number and owner with gh project view. @me means the current user, not an organisation.
• Item not found. Obtain a fresh item list and compare the exact ID. An issue number or content URL is not a substitute for the project item ID.
• Cancelled. Do not immediately repeat it. Check whether the project view changed first, then rerun only after confirming the intended state.