Delete a GitHub Project Field for Good

Deleting the wrong field on a GitHub Project can quietly strip values off every item that used it, and there is no undo flag to bail you out. This guide removes one field with gh project field-delete, using its node ID rather than its display name, and checks the result before and after. Allow about ten minutes if you already have the ID; longer if you need to find it from a field listing first.

This guide describes the gh 2.87.3 package installed on the reference machine. The local manual documents the command as gh project field-delete [flags] and exposes only an ID flag plus output-formatting flags. It does not provide an undo option.

1. Check the installed command and your session

Confirm the expected executable is first in your path, then check GitHub CLI has an authenticated account. Neither check changes the project:

$ command -v gh
/usr/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh auth status

The version and executable path can differ on your machine. The authentication check should identify an account and host. If it reports you are not logged in, stop and authenticate through your normal GitHub CLI process before continuing. Do not put an access token in this article's command line or in a shell history.

2. Resolve the exact field ID

field-delete accepts --id, a string containing the field ID. It does not accept a project number, field name or field position. Get the ID from a trusted view of the intended project, such as the GitHub Project interface or a separate field-listing workflow, and record it without altering it:

$ FIELD_ID='PVTF_lADOExampleProjectField123'
$ printf 'field ID: %s\n' "$FIELD_ID"
field ID: PVTF_lADOExampleProjectField123

The value above is an example only: replace it with the complete ID for the field you have checked. Do not guess from a field's visible label. Labels can be duplicated, and the wrong ID removes a different field.

3. Review the destructive command before running it

Print the command with the value you intend to use. Keeping the identifier in a shell variable separates it from the option syntax and makes the target visible during review:

$ printf 'about to delete project field: %s\n' "$FIELD_ID"
about to delete project field: PVTF_lADOExampleProjectField123
$ gh project field-delete --id "$FIELD_ID"

There is no sudo requirement here. This is a remote GitHub operation, so local root privileges grant no extra authority and provide no recovery. The account used by gh simply needs permission to change the project.

4. Delete the field and capture the result

Once the checkpoint is complete, run the command with the reviewed ID. Add --format json for machine-readable output you can log or check later:

$ gh project field-delete --id "$FIELD_ID" --format json
{"id":"PVTF_lADOExampleProjectField123"}

The exact JSON fields and spacing are controlled by the installed CLI and may differ from this illustrative output. The useful signals are a successful exit status and output that identifies the deleted field. Preserve it in a shell log for an audit trail if you need one, but review logs before sharing them: project identifiers can be sensitive in some organisations.

For a simple script check, test the exit status immediately:

$ if gh project field-delete --id "$FIELD_ID" --format json; then
>     echo 'field-delete completed'
> else
>     echo 'field-delete failed' >&2
>     exit 1
> fi
field-delete completed

Do not retry blindly after a network timeout. The request may have reached GitHub even if the client never saw the response. Inspect the project first, using a read-only listing or view operation, to establish whether the field still exists.

5. Verify without making another change

Run a read-only check on the same project and confirm the field ID is no longer present. Use whichever field-listing or project-view command suits your project scope, then search its output for the exact ID:

$ gh project field-list PROJECT_NUMBER --owner ORGANISATION_OR_USER --format json | grep -F "$FIELD_ID"
$ test "$?" -eq 1 && echo 'field ID not present in the listing'
field ID not present in the listing

Replace PROJECT_NUMBER and ORGANISATION_OR_USER with the intended project values. The exact field-listing options sit outside this command's local manual, so check gh project field-list --help on your installed version before running the verification. An empty search is the expected result; an error from the listing command is not proof of deletion either way.

6. Handle failure and recovery

A missing or malformed ID, insufficient permission, an unavailable network or a GitHub API error should all produce a non-zero exit status. Read the error, check the active account with gh auth status, and confirm the ID without changing it. Do not switch accounts or repositories until you understand which project the original command actually targeted.