List and Search Labels with gh label list

Before you create, rename or delete a label, run gh label list and actually look at what is already there. This is a read-only guide: nothing here creates, edits or deletes a label, and no elevated privileges are needed.

You will finish with commands for inspecting a repository's labels, searching by name or description, and producing output a script can consume. Checked against GitHub CLI 2.87.3. Allow about ten minutes. Replace OWNER/REPO with a repository you can access, such as cli/cli.

1. Check the command and pick a repository

Read the local help first. It shows the flags your installed binary actually supports, rather than one copied from a different release:

$ gh label list --help

From another directory, GitHub CLI uses its current repository when it can detect one. Make the target explicit whenever the command ends up in a note, script or incident record:

$ gh label list --repo OWNER/REPO

For a host other than github.com, use the documented HOST/OWNER/REPO form. The flag only selects a target: it does not clone anything or change your working directory.

2. Read the first page

The default cap is 30 labels, sorted by creation time, oldest first:

$ gh label list --repo cli/cli
NAME        DESCRIPTION                         COLOR
bug         Something isn't working             d73a4a
blocked                                           d93f0b
needs-design An engineering task needs design    fef2c0

Rows depend on the repository and can change over time. A short list on screen is not proof of a short list in the repository: the command only fetches up to the limit you ask for.

Ask for more when you need the complete picture:

$ gh label list --repo OWNER/REPO --limit 100

--limit is a ceiling, not a target. It will not invent rows to hit the number.

3. Sort for a human, not a script

Reach for name order when scanning a big list or comparing two captures:

$ gh label list --repo OWNER/REPO --sort name --order asc

Sort keys are created or name; order is asc or desc. Both only affect an ordinary fetch.

4. Search names and descriptions

Search both fields at once with --search:

$ gh label list --repo OWNER/REPO --search bug

Results are relevance-ranked, so treat the output as a shortlist rather than an alphabetical inventory. Need every match for a script? Fetch a generous limit and inspect the data, do not assume the top result is the only one.

Search still crosses the network under your CLI session's permissions even though it only reads. Keep private repository names and sensitive search terms out of shared shell history.

5. Get stable JSON for a script

Columns suit a terminal. JSON suits anything downstream. Ask only for the fields you actually need:

$ gh label list --repo OWNER/REPO --limit 100 \
    --json name,description,color,isDefault

The documented fields are:

color, createdAt, description, id, isDefault, name, updatedAt, url

Naming fields explicitly keeps a script honest about what it depends on. Filter the JSON with --jq for a compact, shell-friendly report:

$ gh label list --repo OWNER/REPO --limit 100 \
    --json name,description \
    --jq '.[] | [.name, .description] | @tsv'

Keep the unfiltered JSON command close by when troubleshooting; a filter can hide whether nothing matched or the query itself failed.

6. Reach for templates only when you need custom text

--template formats JSON with a Go template, good for a deliberately shaped terminal report but clumsier than JSON for downstream tools:

$ gh label list --repo OWNER/REPO --limit 20 \
    --json name,color \
    --template '{{range .}}{{.name}} {{.color}}{{"\n"}}{{end}}'

Run gh help formatting when a template needs more control. Do not parse the default table by splitting on spaces: descriptions contain spaces, and the table is built for people, not for interchange.

7. Open the labels page when the terminal is not enough

--web opens the repository's label view in a browser:

$ gh label list --repo OWNER/REPO --web

It is a convenience for visual review, not a doorway into editing. Reaching for a create, edit or delete subcommand next? Stop and review its target and undo path first: those change repository state, and this guide is deliberately read-only.