Delete a GitHub Project Safely with gh project delete

gh project delete removes a GitHub Project for good, with no --yes flag and no undo, so the checking happens before you type it. Allow about five minutes if the project is easy to identify, and longer if you need to check ownership or preserve its contents.

Before you start

Use an account that can manage the project, and make sure GitHub CLI is authenticated. Project commands require the project token scope. You can check the current session without changing anything:

gh auth status

The examples use 123 as a deliberately obvious project number and example-org as an organisation placeholder. Replace both values before running a command that changes state. --owner "@me" means the currently authenticated user. For an organisation or another user, use that owner's login instead.

1. Find the project number

List projects for the intended owner and include closed projects when they might be relevant:

gh project list --owner example-org --closed

Read the number, title and owner from the result. The list command fetches up to 30 projects by default, so a project beyond that limit may not appear. Increase the limit when necessary:

gh project list --owner example-org --closed --limit 100

For a personal project, omit --owner or set it explicitly:

gh project list --owner "@me" --closed

Expected output is a list of projects with their numbers and titles. Do not infer the number from a browser URL or from an item inside the project. The delete command expects the project number itself.

2. Inspect before deleting

View the candidate project using the same owner value you used for the list:

gh project view 123 --owner example-org

Check the title, owner and visible contents. If the project is valuable, save the information you need before continuing. A JSON view can make a local record easier to review:

gh project view 123 --owner example-org --format json > project-123-before-delete.json

This creates a file in the current directory. It is not a backup that can restore the project, but it can preserve the displayed project data for reference. Treat it as potentially sensitive if the project contains private work.

3. Choose deletion or a reversible state

Delete only when the project itself is no longer needed. If you merely want it out of active work, closing it is a safer alternative because the separate gh project close command supports --undo:

gh project close 123 --owner example-org

Checkpoint: do not substitute closing for deletion in automation without deciding what that change means for your team. If you choose deletion, stop here and confirm the number and owner one more time. There is no confirmation switch documented for gh project delete, and the command's option list contains output-formatting flags only, so an accidental number or owner is the main safety boundary.

4. Delete the project

Warning: run the deletion command only with the verified number and owner. This cannot be undone:

gh project delete 123 --owner example-org

The command removes the project identified by that number for that owner. It does not accept a project title, and it does not provide a documented restore operation. Do not run this command with a value copied from an untrusted issue, chat message or script argument unless you have checked both the number and owner.

Success may produce little or no human-readable output. Judge the result by its exit status and the follow-up query rather than by guessing from an empty terminal. In a shell, save the status immediately if a script needs to act on it:

gh project delete 123 --owner example-org
delete_status=$?
if [ "$delete_status" -eq 0 ]; then
    printf '%s\n' 'Delete command completed'
else
    printf 'Delete command failed with status %s\n' "$delete_status" >&2
fi

5. Verify the result

List the owner's projects again, including closed projects, and check that the deleted number is no longer returned:

gh project list --owner example-org --closed --limit 100

If the project still appears, check that you used the intended owner and number. If the list command fails, treat that as an authentication or connectivity problem, not proof that deletion failed. You can also try the direct view command:

gh project view 123 --owner example-org

A failed view after a successful delete is consistent with the project no longer being available. Record the command's exit status and the owner in an operational log if the deletion matters for an audit trail.

Common traps

• Wrong owner. Project numbers are not sufficient on their own. Always pair the number with --owner when working across personal and organisation projects.
• Closed is not deleted. gh project list omits closed projects unless --closed is supplied. A missing project from the default list does not prove deletion.
• Too small a list. The list command defaults to 30 projects. Use an explicit --limit when searching a busy owner.
• Confusing project items with projects. gh project item-delete removes an item by item ID. It is a different command from gh project delete, which removes the project.
• Assuming a title is accepted. The delete syntax takes an optional numeric project number, not a title or URL.

Done means

• Access checked. You checked authentication and the required project scope.
• Target identified. You identified the numeric project number and confirmed its owner.
• Contents saved. You viewed the project and saved any information you still need.
• Deletion chosen deliberately. Not used as a way to hide an active project.
• Result confirmed. The delete command returned success and a follow-up list no longer shows that project number.