Create a GitHub Project Safely with gh project create

Spinning up a new GitHub Project without leaving the terminal is what gh project create is for, and the owner has to be right first time. The examples match GitHub CLI 2.87.3, installed here from package gh version 2.45.0-1ubuntu0.3+esm3; the package and CLI release versions are different, so record both when troubleshooting.

Allow about ten minutes. You need GitHub CLI installed, an authenticated account with permission to create a project for the chosen owner, and the exact owner login. This operation changes remote GitHub state, so do not run the creation example until the title and owner are correct.

1. Confirm the installed command

Start with read-only checks. They need no elevated privileges and do not contact GitHub:

$ gh version
gh version 2.87.3 (2026-02-23)
$ gh project create --help
Create a project

The local manpage describes the command as gh project create [flags]. Its relevant options are --owner, --title, --format json, --jq and --template. There is no need for sudo; using it would only risk selecting a different configuration or credential environment.

Checkpoint: if the help text does not show --title and --owner, stop and inspect the command on the host you are actually using. Do not copy examples from a different CLI release into an older installation.

2. Check authentication and choose the owner

Check the account before creating anything:

$ gh auth status
Logged in to github.com account YOUR_LOGIN

The exact status output depends on the account and host. The command should identify the GitHub account you intend to use. If it reports that authentication is required, authenticate with gh auth login and return to this step. Treat the login flow as security-sensitive: use the official GitHub host, review the requested scopes, and never paste a token into a shell history or article.

Choose an explicit owner login. The command accepts @me for the current user, which is useful when the account is unambiguous:

$ OWNER='YOUR_GITHUB_LOGIN'
$ TITLE='Quarterly platform work'
$ printf 'owner: %s\ntitle: %s\n' "$OWNER" "$TITLE"
owner: YOUR_GITHUB_LOGIN
title: Quarterly platform work

Replace both placeholders before continuing. An organisation owner is not interchangeable with your personal login. Confirm that your account can create projects for that organisation. If you are unsure, stop here and ask an organisation administrator rather than testing by creating an unwanted project.

3. Review the state-changing command

The smallest explicit command is:

$ gh project create --owner "$OWNER" --title "$TITLE"

--title supplies the project title. --owner supplies the login that owns it, or can be @me. Quoting both shell variables keeps spaces in the title as data rather than argument separators. Do not put untrusted text directly into an unquoted command.

Checkpoint: read the line once before pressing Enter. Check the owner, spelling, and whether a project with the same purpose already exists. This is the final checkpoint before a remote object is created, and the command does not offer a dry-run flag in the installed interface.

4. Create the project and capture the result

Run the reviewed command only when you are ready to create the remote project:

$ gh project create --owner "$OWNER" --title "$TITLE"
[output varies by CLI release]

The final line is deliberately shown as a placeholder because the exact normal output is returned by the installed CLI and can vary with terminal and release details. Treat a zero exit status as success and retain the command output if you need to find the new project in a script or audit log. A non-zero result means the creation did not complete successfully: inspect the error before trying again, because a transient display or network failure is different from a project that was already created.

Immediately record the status of the command:

$ status=$?
$ printf 'gh project create exit status: %s\n' "$status"
gh project create exit status: 0

Only 0 confirms that the command reported success. The documented general exit codes include 1 for an error, 2 for cancellation and 4 when authentication is required. The command may also have a more specific failure code.

5. Request JSON when a script needs structured output

For automation, ask this subcommand for JSON rather than scraping human-readable text:

$ gh project create --owner "$OWNER" --title "$TITLE" --format json
[JSON output varies by CLI release]

The command-specific option is --format json. The local formatting help explains that --jq filters the JSON with jq syntax and --template formats it with a Go template. The formatting flags belong to the JSON result, so keep --format json in the command when using either:

$ gh project create --owner "$OWNER" --title "$TITLE" --format json --jq '.'
[JSON output varies by CLI release]

Use --jq only after checking the fields returned by the CLI version on your host. Do not invent a field name and assume it is the project URL. If you need a stable field for a larger integration, inspect the actual JSON, pin the CLI version, and add a test for the field you consume.

6. Verify the project exists

List projects for the same owner:

$ gh project list --owner "$OWNER"
[project list output including your title]

Confirm that the new title appears under the intended owner. The list command defaults to a maximum of 30 projects and excludes closed projects unless --closed is supplied. If you cannot see the project, first check the owner, title and authentication account, then repeat the list with --closed if the project was closed by a separate workflow.

For a browser-based check, the list command also has --web, but opening a browser is not necessary for verification. Keep the terminal check in deployment or onboarding scripts.

Common failure modes and recovery

Recovery: there is no local undo command for a project created by this guide. If you created the wrong project, use GitHub's project management interface or the separately documented gh project delete workflow only after confirming the exact project. Deletion is irreversible enough to deserve its own review.

Done means