Create a GitHub Project Draft with gh project item-create

A half-formed idea does not deserve a repository issue yet, but it does deserve a card on the board. gh project item-create adds a draft issue item to a GitHub Project from the shell, and you can read the result back as JSON. This guide uses GitHub CLI 2.87.3, installed here on 23 September 2026, and the matching gh-project-item-create(1) manpage. Allow about ten minutes.

Warning: this command changes GitHub state as soon as it succeeds. Read the title and body in your command before pressing Enter. No elevated Linux privileges are needed, and sudo will not help with a GitHub permission error.

1. Confirm the project number and owner

The command takes a Project number as its optional positional argument. The number is not the repository number and not the issue number. The owner is the account or organisation that owns the Project. For your own Project, --owner "@me" is the clearest choice.

If you do not already know the number, list your Projects first:

$ gh project list --owner "@me"

For an organisation-owned Project, replace the owner placeholder with its login:

$ gh project list --owner ACME

Keep the number from the row you intend to change. The gh project commands use the Project number to identify the board and --owner to identify who owns it.

Checkpoint: you have a Project number from a listing. If the list is empty or access is denied, stop here and fix authentication or Project access before attempting creation.

2. Create the draft issue

Pass the Project number, owner, title and body explicitly. The following creates a draft item in your own Project number 1:

$ gh project item-create 1 \
    --owner "@me" \
    --title "Document the release rollback" \
    --body "Write the rollback steps, required permissions, and verification commands."

The result is a draft issue item, not an issue in a repository. That distinction matters: this command is useful for planning work that is not ready to become a repository issue. The title and body are the draft issue's content. There is no option in this command to attach an existing issue, pull request, label, assignee or Project field.

For an organisation-owned Project, change only the owner and number:

$ gh project item-create 42 \
    --owner ACME \
    --title "Review the backup runbook" \
    --body "Check the restore test and record its evidence."

A successful run means GitHub accepted the write. Save the output if you need to find the new item later.

Warning: if you see an authentication, scope or permission error, do not repeat the command blindly. First check whether the first request actually created the item.

3. Ask for machine-readable output

Use --format json when another command or a log needs to consume the response. This also avoids depending on the human-readable layout, which can change between CLI versions:

$ gh project item-create 1 \
    --owner "@me" \
    --title "Document the release rollback" \
    --body "Write the rollback steps, required permissions, and verification commands." \
    --format json

The manpage guarantees JSON as the available format for this command, but it does not promise a fixed example payload in its output section. Treat the returned object as data rather than copying a guessed field name into a script. First inspect it:

$ gh project item-create 1 --owner "@me" \
    --title "Short-lived test draft" \
    --body "Delete this item after checking the response." \
    --format json | jq

Once you have confirmed the field names in your installed version, --jq can select a value using the same jq expression language supported by other GitHub CLI formatting options. For example, this checks that the response is valid JSON without assuming its schema:

$ gh project item-create 1 --owner "@me" \
    --title "Short-lived test draft" \
    --body "Delete this item after checking the response." \
    --format json | jq -e 'type == "object"'

Checkpoint: expected output is true and a zero exit status. This creates another item, so use a real title and body or remove the test item afterwards.

4. Use templates only after inspecting the response

The command also accepts -t or --template for a Go template. Templates are useful for stable, narrow output, but a wrong field expression can produce empty output while the write has already succeeded. Start with JSON during development, then consult gh help formatting and test your template against a non-critical draft.

$ gh project item-create 1 --owner "@me" \
    --title "Review the backup runbook" \
    --body "Check the restore test and record its evidence." \
    --format json \
    --jq '.'

Warning: -q and --jq filter JSON output. They do not preview the operation and they do not make creation read-only. Put the write command behind your own review step if automation is calling it.

5. Check, correct or remove the item

List the Project after creation to confirm that the new draft appears:

$ gh project item-list 1 --owner "@me"

Use the title and body to identify the item, then note its item ID if you need to remove it. Deleting a Project item is destructive and cannot be recovered by this create command, so check the ID carefully before running a deletion:

$ gh project item-delete 1 --owner "@me" --id ITEM_ID

Replace ITEM_ID with the ID for the mistaken item. If the item should remain but its text is wrong, use the separate item-edit command instead of creating a duplicate.

Recovery: if a create command reports a network failure, inspect the Project first. Retrying may create two drafts if GitHub processed the request before the connection failed.

Common traps

Done means