List GitHub Project Fields Reliably with gh

Before you create, edit or script against a project field, gh project field-list tells you what is already there. This guide covers picking the right owner, reading the output as a person, and shaping it for a script. It uses GitHub CLI gh 2.87.3, installed here on 23 September 2026. Allow about ten minutes if gh is already authenticated.

The command only reads project metadata, but it still sends a request to GitHub and needs an account that can read the project. There is no sudo step anywhere here: if your token has too little access, fix the token deliberately rather than switching accounts to work around the error.

1. Check the local command

Confirm the executable and inspect the options actually installed on this machine:

$ gh version
$ gh project field-list --help

The subcommand accepts an optional project number and these useful controls: --owner, --limit, --format json, --jq, and --template. The local default is a maximum of 30 fields. The help output is a good checkpoint when a script might run on more than one machine.

2. List fields for a project

Pass the numeric project number and the login that owns it. For a project in your own account, use the documented @me value:

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

Replace 1 with the project number shown by GitHub, or by gh project list --owner "@me". For an organisation-owned project, use its login instead:

$ gh project field-list 1 --owner EXAMPLE-ORG

3. Make the result predictable for scripts

Request JSON when another command needs to process the response:

$ gh project field-list 1 --owner "@me" --format json

Use --jq when you only need selected values. This example prints each field name, one per line:

$ gh project field-list 1 --owner "@me" --format json --jq '.[].name'

Keep the expression quoted so your shell does not interpret its punctuation. Omit --jq if you need the complete JSON object. Do not assume a human-readable table and JSON share identical column names: the JSON result is the better input for a script either way.

4. Fetch more than the default

The default limit is 30. Set it explicitly when a project might contain more fields:

$ gh project field-list 1 --owner "@me" --limit 100 --format json

--limit is a maximum number of fields to fetch, not a request to create fields or alter the project. Choose a value that covers the project you support, and check the returned count: a result that stops exactly at your chosen limit may be incomplete, so do not silently treat it as a full inventory.

5. Choose one presentation format

Use a Go template when you want controlled text output without writing a separate JSON-processing step:

$ gh project field-list 1 --owner "@me" --format json --template '{{range .}}{{.name}}{{"\n"}}{{end}}'

• Quick terminal check: leave the format unspecified.
• Structured data: use JSON, optionally with --jq.
• Fixed report line: use --template.

Read gh help formatting if the template needs conditionals or other Go template features.

Common traps

If GitHub reports the token is missing a project scope, check the current login first:

$ gh auth status

On this installed version, an account without the required read permission was told to request read:project with gh auth refresh -s read:project. That refresh changes the stored GitHub CLI authentication grant, so review the requested scope and your organisation's policy before running it: it is not a repair to apply blindly. The upstream project documentation describes the broader scope requirement, but the local command's own error is the most specific evidence for this installation.

An unknown project number, wrong owner or inaccessible organisation project can produce a request error even when authentication works fine. Recheck the number and owner separately. If the command succeeds without --format json but a filtered version fails, test the unfiltered JSON first, then simplify the --jq or template expression.