Safely Remove a GitHub Project Item with gh project item-delete

One wrong ID and gh project item-delete removes the wrong card, with no prompt and no undo flag. You will remove one item from a GitHub Project by its Project item ID, with the project selected by number and owner. Allow about ten minutes if you already have the project number and item ID. Allow longer if you still need to identify the item, because this command changes remote state.

1. Check the installed command and your access

This guide describes GitHub CLI 2.87.3, installed on this machine. The local manual is dated March 2026. The command is part of the gh package and normally runs as your unprivileged user. It does not need sudo: authentication and GitHub permissions, rather than local root privileges, control the operation.

$ gh --version
gh version 2.87.3 (2026-02-23)
https://github.com/cli/cli/releases/tag/v2.87.3
$ gh project item-delete --help
Delete an item from a project by ID

Before continuing, make sure the account used by gh can manage the project. The GitHub CLI project command documentation says the minimum token scope is project. Check the current login and scopes without changing anything:

$ gh auth status

Read the result carefully. If the active account or host is wrong, stop. Fix authentication through your normal GitHub CLI process before running a deletion command.

2. Identify the exact project and item

The positional number is the project number, not the item ID. The --owner value identifies the user or organisation that owns the project.

• Your own project: use @me.
• An organisation or another user: use an explicit login, where your permissions allow it.

List the project items before deleting anything. This is a read-only check and helps prevent the common mistake of copying an issue number instead of a Project item ID:

$ gh project item-list 1 --owner "@me"
TYPE  TITLE                    NUMBER  REPOSITORY       ID
Issue Replace old dashboard   42      acme/web          PVTI_lADOB...
Draft Update release notes    -       -                PVTI_lADOB...

Your columns and values will differ. The useful value for deletion is the long ID in the ID column, often beginning with PVTI_. The item ID is not the issue or pull request number, and it is not the project number. If the list is long, use the documented list options to narrow what you inspect, but confirm the title, type and repository before copying the ID.

For an organisation-owned project, make the owner explicit in both the inspection and deletion commands:

$ gh project item-list 7 --owner acme
$ gh project view 7 --owner acme

3. Understand what deletion changes

This command removes the item from the selected Project. It is not the same as deleting the underlying issue, pull request or repository. It is also different from archiving an item: archiving is a reversible project-state operation, while item-delete has no --undo option in the installed command.

If the item is a draft issue, preserve its text somewhere appropriate before deletion if it may be needed later. Do not paste a real token, private issue body or other sensitive material into a shell history or a shared transcript.

4. Delete the confirmed item

After checking the target, run the command with the project number, owner and item ID. Keep the ID quoted so shell metacharacters cannot alter the argument if an unusual identifier is ever returned:

$ gh project item-delete 7 --owner acme --id 'PVTI_lADOBxxxxxxxxxxxxxxxx'
$ printf 'delete exit status: %s\n' "$?"
delete exit status: 0

Treat exit status zero as the primary success signal.

• Do not add sudo. It cannot grant GitHub project access and may use a different configuration or authentication environment.
• Do not use an issue number as a selector. Putting one after the project number will not select that issue. The documented selector for this command is --id.

5. Verify that the item is gone

List the same project again and look for the exact ID. Use a text filter only as a convenience, then inspect the result rather than trusting a partial match:

$ gh project item-list 7 --owner acme | grep -F 'PVTI_lADOBxxxxxxxxxxxxxxxx'
$ printf 'list command exit status: %s\n' "$?"
list command exit status: 1

With ordinary grep, status 1 means that no matching line was found. It does not by itself prove that the intended project was queried, so verify the project number and owner as well. If the command prints the item, stop and investigate instead of repeating deletion.

For a machine-readable check, request JSON output from the list command and use a JSON-aware tool if it is installed. Keep the item ID in a shell variable to reduce transcription errors:

$ ITEM_ID='PVTI_lADOBxxxxxxxxxxxxxxxx'
$ gh project item-list 7 --owner acme --format json | jq --arg id "$ITEM_ID" \
    '[.items[]? | select(.id == $id)] | length'
0

The exact JSON shape can vary with the GitHub CLI version and project data. If this expression reports an error, inspect the raw JSON and adapt the filter to the fields shown by your installed command. A zero result is useful only when the list was obtained for the same project and owner.

6. Use output formatting only when needed

The delete command supports --format json, --jq and --template, but a successful deletion commonly needs only its exit status. These options format output; they do not make the target safer and do not provide a confirmation or undo operation.

For a script, capture the status immediately and stop on failure:

$ set -o errexit
$ gh project item-delete 7 --owner acme --id "$ITEM_ID"
$ printf 'delete request completed\n'
delete request completed

7. Diagnose common failures

• Authentication, permissions or the project scope. The request was rejected before the intended change completed. Check gh auth status, the selected host, the owner and the project number. Re-authenticate or request access through your normal process; do not try sudo.
• Item ID error. Usually the value is not a Project item node ID, the item belongs to another project, or it has already been removed. Re-run gh project item-list for the exact owner and project. Do not substitute an issue number, pull request number or repository node ID.
• Network failure after the request is sent. The final state may be uncertain. Do not blindly retry. First list the project and search for the exact item ID. If it is absent, verification has established the result. If it is still present, confirm the target again before retrying once.