Edit GitHub Project Fields Safely with gh project item-edit

Dragging cards around a board is fine until you need to change forty of them, or do it from a script. gh project item-edit sets one field value on a Project item, or edits the title and body of a draft issue item, straight from your shell. The examples match GitHub CLI 2.87.3, installed on this machine. Allow about fifteen minutes if you already have the item, project and field IDs.

• You need: the gh package and an authenticated GitHub CLI session with permission to edit the project.
• Also needed: IDs copied from the project, not guessed.
• No sudo. Elevated local privileges do not grant GitHub permission.

1. Confirm the command you will run

Read the installed command help before preparing a change:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh project item-edit --help
Edit either a draft issue or a project item. Both usages require the ID of the item to edit.

The command has two paths:

• Draft issue. Needs its item ID and the new --title or --body.
• Normal project item. Needs its item ID, the project ID, the field ID, and exactly one field value per invocation.

2. Gather exact IDs

Replace the placeholders in the examples with IDs copied from your project tooling or GitHub's project data. Keep them quoted so a copied value remains one shell argument:

$ ITEM_ID='PVTI_REPLACE_WITH_ITEM_ID'
$ PROJECT_ID='PVT_REPLACE_WITH_PROJECT_ID'
$ FIELD_ID='PVTF_REPLACE_WITH_FIELD_ID'

• Item ID: identifies the row being edited.
• Project ID: identifies the project that owns a normal item's field.
• Field ID: identifies the column. It is a different value from the item ID.

There is no safe generic example that can discover your IDs without also depending on your account, organisation and project visibility. Use the exact identifiers from your own project, then review the complete command before pressing Enter.

3. Set a text field

Pass one field value option. This example changes a text field to a new string:

$ gh project item-edit \
    --id "$ITEM_ID" \
    --field-id "$FIELD_ID" \
    --project-id "$PROJECT_ID" \
    --text 'Ready for review'

A successful edit normally returns no useful human-readable record. Verify the value in the GitHub project interface or with the project listing command you already use. If the command prints an error, treat the edit as unconfirmed and inspect the IDs and permission before retrying.

4. Set a number, date or select value

Use the value flag matching the field type. The date format is explicitly YYYY-MM-DD:

$ gh project item-edit --id "$ITEM_ID" --field-id "$FIELD_ID" --project-id "$PROJECT_ID" --number 3
$ gh project item-edit --id "$ITEM_ID" --field-id "$FIELD_ID" --project-id "$PROJECT_ID" --date '2026-10-15'
$ gh project item-edit --id "$ITEM_ID" --field-id "$FIELD_ID" --project-id "$PROJECT_ID" --single-select-option-id 'OPTION_REPLACE_WITH_OPTION_ID'
$ gh project item-edit --id "$ITEM_ID" --field-id "$FIELD_ID" --project-id "$PROJECT_ID" --iteration-id 'ITERATION_REPLACE_WITH_ITERATION_ID'

Run only the line that matches the target field. Do not combine --text, --number, --date, --single-select-option-id or --iteration-id in one invocation. For a single-select or iteration field, the option or iteration ID is not the label shown to people.

5. Clear a field value carefully

--clear removes the field value:

$ gh project item-edit \
    --id "$ITEM_ID" \
    --field-id "$FIELD_ID" \
    --project-id "$PROJECT_ID" \
    --clear

Use --clear instead of supplying an empty string. It is a separate operation and still needs the item, field and project IDs.

6. Edit a draft issue item

Draft issues use the item ID and the draft fields. They do not use the normal field-value flags for title and body:

$ gh project item-edit --id "$ITEM_ID" --title 'Release notes to review'
$ gh project item-edit --id "$ITEM_ID" --body 'Add the verified upgrade notes before publishing.'

Use one draft change at a time while checking the result. The title and body are remote content, so preserve the old text if you may need to restore it. A normal project item is not converted into a draft by this command.

7. Make scripted edits observable

For scripts, keep the command's exit status and log the identifiers without logging confidential project content. The command supports JSON output, jq filtering and Go templates through --format json, --jq and --template. Ask the installed help for the exact output shape before depending on it:

$ gh project item-edit --help | sed -n '/--format/,/--title/p'
      --format string                    Output format: {json}
  -q, --jq expression                    Filter JSON output using a jq expression
  -t, --template string                  Format JSON output using a Go template

Do not assume that an output field has the same name as the visible project label. First run a harmless, already-approved edit in a test project and inspect its JSON output. Then pin the fields your script needs and fail on a non-zero exit status.

8. Diagnose failures without guessing

• The command rejects the invocation. Re-read gh project item-edit --help and check that the chosen value flag is present.
• GitHub rejects the request. Check the item, project and field IDs together, then check that your account can edit that project.
• Date failure. Use a four-digit year, two-digit month and two-digit day.
• Single-select or iteration failure. Obtain the option or iteration ID from the same project rather than copying a display label.
• Draft edit failure. Remove the normal field flags and keep only --id plus --title or --body.