gh label list --search returning odd results

[gilzow]

Describe the bug

using gh label list --search "search-term" returns labels that do not contain "search-term"

Affected version

❯ gh version
gh version 2.82.0 (2025-10-15)

Steps to reproduce the behavior

1. Type this: gh label list --search "prose" --json name,description
2. View the output

[
  {
    "description": "",
    "name": "markdown/prose"
  },
  {
    "description": "",
    "name": "automated pr"
  }
]

3. See error - "automated pr" does not contain the string "prose" and does not contain a single "s" character.

Expected vs actual behavior

In this case I expect only those labels that contain the string "prose" in either the label name or description to be returned. Actual behavior is I'm seeing completely unrelated labels being returned.

Logs

Paste the activity from your command line. Redact if needed.

❯ export GH_DEBUG=true; gh label list --search "prose" --json name,description
[git remote -v]
[git config --get-regexp ^remote\..*\.gh-resolved$]
* Request at 2025-10-20 15:45:58.050019 -0500 CDT m=+0.135239702
* Request to https://api.github.com/graphql
* Request took 460.837393ms
⣾* Request at 2025-10-20 15:45:58.554024 -0500 CDT m=+0.639229895
* Request to https://api.github.com/graphql
⣻* Request took 263.224654ms
[
  {
    "description": "",
    "name": "markdown/prose"
  },
  {
    "description": "",
    "name": "automated pr"
  }
]

I can replicate this behavior by misspelling the search phrase, or by trying other search strings that should match a given number of labels but the actual results contains results that do not contain the search phrase.

[gilzow]

Another example, using the term "upcom" i would expect labels that contain the string "upcom" to match (e.g. upcoming, upcoming-q425, etc) but I'm getting completely unrelated matches:

  {
    "description": "",
    "name": "upsun-mvp"
  }

[gilzow]

Another example where I purposely misspell a term so that there should be zero matches:

❯ gh label list --search "pruse"

Showing 1 of 1 label in platformsh/platformsh-docs

NAME          DESCRIPTION  COLOR  
automated pr               #ededed

[babakks]

Hi @gilzow! 👋 Interesting find. 🤔

However, as I checked, this is how GitHub API behaves and gh has no control over it. I mean there's no option to select a less fuzzy search backend or something. As of the API docs, the labels that best match the query appear first in the search results. So, if you're looking for an exact match, it's probably the first entry you should look at; although I'm not sure how prefixed/suffixed matches will be ranked.

Anyway, I'm going to remove the bug Something isn't working label. But before closing this, may I ask if this behavior is causing troubles/blockers at your end? If so, please share more context with me so that we can see if there's any workaround for it.

[gilzow]

I'm not seeing a search option in the REST API for labels for the list endpoint: https://docs.github.com/en/rest/issues/labels?apiVersion=2022-11-28#list-labels-for-a-repository
Can you point me to the docs for the search option?

It's causing an issue, but not necessarily a blocker.

Specifically, in a job I'm checking to make sure a label(s) exists before attempting to add it to a PR. If it doesn't exist, I create it first.

For this, I guess I retrieve all the labels, and then use jq to filter the list back down to those that match, or an empty set.

[babakks]

Thanks for more context. 🙏

I'm going to close this issue as it's how API performs search on labels.

But, I can see a command like label view is missing in gh, and that would be helpful in your use case here. Feel free to create an issue for it.

For this, I guess I retrieve all the labels, and then use jq to filter the list back down to those that match, or an empty set.

Yeah, you can definitely use label list as you said. However, if the repo has so many labels that would require gh to go through paginated API calls, and you just need an exact-match comparison, then you can directly use any of these REST or GraphQL API endpoints:

# REST API; exits with zero if label exists
gh api /repos/OWNER/REPO/labels/LABEL

# GraphQL API; prints the label name if label exists
gh api graphql \
  --jq '.data.repository.label.name' \
  -F owner='OWNER' -F name='REPO' -F label='LABEL' -f query='
    query($name: String!, $owner: String!, $label: String!) {
      repository(owner: $owner, name: $name) {
        label(name: $label) {
          name
          description
        }
      }
    }
  '

I'm not seeing a search option in the REST API for labels for the list endpoint: https://docs.github.com/en/rest/issues/labels?apiVersion=2022-11-28#list-labels-for-a-repository Can you point me to the docs for the search option?

gh uses a GraphQL query similar to this (note the query parameter):

{
  repository(owner: "cli", name: "cli") {
    labels(first: 100, query: "project") {
      nodes {
        name
        description
      }
    }
  }
}

Here you can find the Label type docs. There's also a REST API endpoint for searching labels (here), which is a bit hard to use since it needs the repository ID, which would probably need another API call to fetch.