List GitHub Project Fields Reliably with gh

You will inspect the fields attached to a GitHub Project from a terminal, choose the correct owner, and make the output useful for either a person or a script. This guide uses GitHub CLI gh 2.87.3, installed here on 23 September 2026. Allow about ten minutes if you already have gh authenticated. The command only reads project metadata, but it sends a request to GitHub and needs an account that can read the project.

There is no sudo step. Do not add elevated privileges to a command that is using your GitHub token. If your token has too little access, fix the token deliberately rather than working around the error with another account.

1. Check the local command

Confirm the executable and inspect the options that are actually installed:

$ 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 useful checkpoint when a script may 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

The normal output is intended for people. It lists the fields returned for that project, subject to the limit. A successful request is the checkpoint: you should see field entries rather than an authentication or GraphQL error.

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. If you need the complete JSON object, omit --jq. Do not assume that a human-readable table and JSON have identical column names: the JSON result is the better input for a script, while the installed command and project API determine the available properties.

4. Fetch more than the default

The default limit is 30. Set it explicitly when a project may 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. If you are writing automation, choose a value that covers the project you support and check the returned count. A result that stops 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}}'

The formatting flags are alternatives for different consumers. For a quick terminal check, leave the format unspecified. For structured data, use JSON and optionally --jq. For a fixed report line, use --template. Read gh help formatting if the template needs conditionals or other Go template features.

6. Diagnose the common failures

If GitHub reports that 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 project scope requirement; the local command's 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 itself works. Recheck the number and owner separately. If the command succeeds without --format json but a filtered command fails, test the unfiltered JSON first, then simplify the --jq or template expression.