Close a GitHub Project Safely with gh project close

A finished GitHub Project cluttering the active list is a one-command fix: gh project close takes it out of the way without deleting anything. The examples use GitHub CLI 2.87.3, installed here on 23 September 2026. Allow about ten minutes, plus the time needed to confirm the project number and owner.

You need the gh command, an authenticated GitHub CLI session, and permission to manage Projects for the owner. The GitHub CLI documentation says the parent gh project command requires the project token scope. Check that before you start:

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

The exact authentication status varies by account and host. If the command reports that you are not logged in or lack the required scope, stop there and fix authentication through your normal GitHub CLI process. Do not paste a token into a command line or into a guide.

1. Confirm the project number and owner

A project number is not enough on its own. The owner can be your account or an organisation, and the same number can be meaningful in a different owner context. List the projects for the intended owner:

$ gh project list --owner OWNER

Replace OWNER with the GitHub login that owns the project. For your own projects, the close command accepts the special owner value @me. The list command does not document that shorthand in its own options, so use your actual login there if @me is not accepted by your installed version.

Write down both the number and the visible project title. If the project is already closed, include closed projects in the search:

$ gh project list --owner OWNER --closed

Checkpoint: do not continue until the number, owner and title match the change you intend to make. Closing a project changes GitHub state; it is not a local archive operation, and deleting a project is a different command entirely.

2. Inspect the project immediately before closing it

View the project using the same owner and number:

$ gh project view PROJECT_NUMBER --owner OWNER

Replace the uppercase placeholders, for example:

$ gh project view 17 --owner acme-tools

Read the returned title and other details rather than relying on a remembered number. This command is a read-only check. If it fails, investigate the owner, number, login and token scope. Do not switch to a different account merely because it is quicker unless that account is deliberately authorised to manage this project.

3. Close the project

Warning: this is the state-changing step. It closes the project on GitHub. Check the command line once more before pressing Enter:

$ gh project close 17 --owner acme-tools

The installed manual describes the positional argument as the project number and --owner as the owner's login. The command has no documented option for a repository, title or local project file, so those values do not select the target. Use a project number from the intended owner.

On success, the command normally completes without a useful report beyond its exit status. Capture that status straight away if you are using it in a script:

$ gh project close 17 --owner acme-tools
$ printf '%s\n' "$?"
0

A zero status means the CLI command completed successfully. It does not protect you from having supplied the wrong owner or number, which is why the view and list checks matter.

4. Verify the closed state

Ask the owner for its projects again, this time including closed projects:

$ gh project list --owner acme-tools --closed

Find the project number and title in the returned list. The list command's ordinary view excludes closed projects unless --closed is supplied, so an apparently missing project can be expected after a successful close. For a fuller inspection, view the same number again:

$ gh project view 17 --owner acme-tools

Use the output from your installed CLI as the authority for the current state. Do not infer success from a cached browser tab or from a shell prompt that merely returned.

5. Reopen the project if the close was premature

The close command has an explicit undo operation. It reopens the project; it does not create a copy or restore a deleted project:

$ gh project close 17 --owner acme-tools --undo

Recovery: verify the result by listing closed projects again and checking the project view. If the project is no longer shown in the closed list, confirm it with the normal list command:

$ gh project list --owner acme-tools
$ gh project view 17 --owner acme-tools

Keep the original number and owner when undoing. Do not omit --owner and hope the current repository or account selects the same project: project ownership is part of the target.

6. Use output formatting only when a script needs it

The close command accepts --format json, --jq and --template for output handling. The command is still a close operation; formatting does not make it read-only or add a confirmation layer. For a human-run change, the plain command is easier to review. If a script needs structured output, test that script against a non-production project first and keep the number and owner as explicit inputs.

Do not add flags from another gh project subcommand by memory. --closed belongs to gh project list, while --undo belongs to gh project close. Check the installed help for the exact subcommand before adapting a command:

$ gh project close --help

The installed command documents --format, --jq, --owner, --template and --undo. It does not document a force or confirmation-bypass flag. If authentication, ownership or project access fails, resolve that underlying issue rather than guessing at an option.

Done means