Archive a GitHub Project Item Safely with gh

You will archive one item from a GitHub Project with the installed gh project item-archive command, then know how to reverse that change. Allow about ten minutes if you already know the project number and item ID. The command changes remote project state, so spend an extra minute checking the identifiers before you run it.

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. The command accepts a project number, an item ID, and an owner. It also has an --undo flag for unarchiving.

$ 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

Only the help command is a harmless check. Do not test the archive command with a real ID until you have identified the exact item you mean to change.

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. For a project belonging to your current user, the documented value is @me. Use a named organisation or account when that is 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. The project command family requires a token with the project scope. If authentication is missing, check it with gh auth status; do not add credentials to a shell script.

Checkpoint: you have a confirmed project number and owner. No remote state has changed yet.

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

The value above is deliberately not a usable ID. Replace it with the value returned for your item. Do not guess an ID from an issue or pull request number.

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. Before continuing, warn anyone relying on the project view if the item is part of a shared workflow.

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

The installed manual documents exit status 0 as successful execution. This 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

If you need to distinguish an empty response from a shell mistake, run the command as a separate invocation and check $? immediately afterwards. Do not put an unrelated command between the archive command and the status check.

5. Undo an archive

If you selected 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. 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. If the item was archived by another workflow after your first command, stop and confirm the current project state before changing it again.

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.

• If authentication is 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.
• If the project cannot be found, check the number and owner with gh project view. @me means the current user, not an organisation.
• If the item cannot be 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.
• If the operation is cancelled, do not immediately repeat it. Check whether the project view changed first, then rerun only after confirming the intended state.

Do not use --undo as a general recovery for a guessed ID. It can change a different item just as readily as the archive form can.