List GitHub Project Items Reliably with gh project item-list

You will finish with a repeatable way to list the items in a GitHub Project, choose the correct owner, limit the amount returned, and filter the result without changing project data. Allow about ten minutes. You need GitHub CLI 2.87.3 or a compatible release, an authenticated account with access to the project, and the project's numeric number.

The examples use the installed gh package on this machine. The local manual documents the core options; the installed command also reports --query, --field and --field-id. Check your own help if you are on an older release.

1. Check the installed command

Start with a read-only version and help check. Neither needs elevated privileges:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh project item-list --help

Look for the synopsis gh project item-list [<number>] [flags]. The project number is optional in the syntax, but supplying it makes the command unambiguous and is the practical form for a project-specific report.

Checkpoint: if your help does not contain an option you plan to use, stop and adapt the example to the version actually installed. Do not assume that a flag from a current web page exists in an older package.

2. List a project owned by your account

Set the number as a shell variable, then list project 1 owned by the current user:

$ PROJECT_NUMBER=1
$ gh project item-list "$PROJECT_NUMBER" --owner '@me'
TYPE  TITLE                         NUMBER  REPOSITORY
Issue Fix the upload timeout       42      example/service
Draft Add retention documentation  -       -

The columns and rows depend on the project. The output is a human-readable table, not a stable interface for scripts. An issue or pull request can have a repository and number; a draft item can show different identifying fields.

--owner '@me' means the authenticated current user. For an organisation or another user, replace it with the exact login:

$ gh project item-list 7 --owner example-org

Quote the owner value when it contains shell-significant characters. The quoted @me form is clear and safe to paste. There is no reason to use sudo; elevated privileges do not grant GitHub API access.

3. Control how much data is fetched

The default limit is 30 items. Use --limit when a project is larger or when a small smoke test is enough:

$ gh project item-list 7 --owner '@me' --limit 10

--limit is a maximum number of items to fetch. It is not a promise that ten rows exist, and it does not sort the project for you. If you need a complete inventory, choose a limit large enough for the project and verify that the returned count matches what you expect.

Checkpoint: repeat the command without changing project state. If the result stops at the limit, increase it deliberately rather than treating a partial list as a complete report.

4. Filter items with the Projects query syntax

On GitHub.com and GitHub Enterprise Server 3.20 or newer, current gh releases support --query for Projects filter expressions. For example, list open issues assigned to yourself:

$ gh project item-list 7 --owner '@me' \
    --query 'assignee:@me is:issue is:open'

To find bugs that are not done, use a quoted expression so the shell does not interpret the spaces or the leading minus:

$ gh project item-list 7 --owner example-org \
    --query 'label:bug -status:Done'

The query is sent as a Projects filter, not as a local grep. Its supported fields and behaviour belong to GitHub Projects, so consult the GitHub Projects filtering documentation when composing a new expression. If the API host does not support the feature, remove --query and filter the structured output after fetching it.

5. Produce output for a script

For automation, request JSON and filter it with jq. This example prints each item's title as JSON strings:

$ gh project item-list 7 --owner '@me' --format json \
    --jq '.items[] | .content.title'

The exact fields available can vary by item type. A draft item does not necessarily have the same content fields as an issue or pull request. Inspect the raw shape before writing a production filter:

$ gh project item-list 7 --owner '@me' --format json | jq .

For a one-off display, --template formats JSON with a Go template instead, and --jq accepts a jq expression. These are output transformations only. They do not edit, archive or delete items.

Keep a command's exit status separate from its output. An empty result may mean that no items match, while a non-zero status usually means the request or authentication failed:

$ if ! gh project item-list 7 --owner '@me' --format json > project-items.json; then
    printf 'Could not read the project\n' >&2
    exit 1
  fi
$ jq 'length, (.items | length)' project-items.json

If this command fails, check authentication and access before changing the project. Do not paste tokens into the command line or put them in a repository. Use the normal gh auth workflow for account management.

6. Add useful project fields when supported

Installed gh 2.87.3 also accepts repeated --field options to show extra columns, such as Status and Priority:

$ gh project item-list 7 --owner '@me' \
    --field Status --field Priority

Field names must match fields available in that project. If a field is missing or its spelling differs, remove it or inspect the project in GitHub before retrying. --field-id is available when an ID is more reliable than a display name. These options affect presentation, not project configuration.

Common traps and recovery

A project number is not a repository issue number. If the rows look unrelated to the project you meant, check both the number and --owner. A project belonging to an organisation will not be found by using --owner '@me' unless your account is actually the owner.

A truncated table is not an error: the default maximum is 30. A zero-row result is also not proof that the project is empty if you used a restrictive query. Remove the query, raise the limit, and compare the unfiltered result.

This command is read-only. There is no undo step because the examples do not alter project items. Do not switch to item-edit, item-delete or another mutating subcommand while troubleshooting a listing error; verify the read command first.