Add `--query` flag to `project item-list` by williammartin · Pull Request #12696 · cli/cli

williammartin · Feb 16, 2026

Description

Acceptance Criteria

Given I am targeting github.com
When I run project item-list with the --query flag
Then the query is respected in the results

➜ ./bin/gh project item-list 9 --owner williammartin --format json --query "assignee:williammartin-cli-triaging"
{
  "items": [
    {
      "assignees": [
        "williammartin-cli-triaging"
      ],
      "content": {
        "body": "test",
        "number": 25,
        "repository": "williammartin-test-org/test-repo",
        "title": "test title",
        "type": "Issue",
        "url": "https://github.com/williammartin-test-org/test-repo/issues/25"
      },
      "id": "PVTI_lAHOABiW9s4A1ms7zgY4CN4",
      "repository": "https://github.com/williammartin-test-org/test-repo",
      "title": "test title"
    }
  ],
  "totalCount": 1
}

➜  ./bin/gh project item-list 9 --owner williammartin --format json --query "assignee:babakks"
{
  "items": [],
  "totalCount": 0
}

Given I am targeting a version of GHES that doesn't support the query flag
When I run project item-list with the --query flag
Then I receive an informative error

➜ ✗ GH_HOST=ghe.io ./bin/gh project item-list 9 --owner williammartin --format json --query "assignee:babakks"
the `--query` flag is not supported on this GitHub host; most likely you are targeting a version of GHES that does not yet have the query field available

Copilot

Pull request overview

This PR adds a --query flag to gh project item-list to allow server-side filtering of project items using the GitHub Projects filter syntax (e.g. assignee:..., -status:...), addressing issue #12664.

Changes:

Extend the project items GraphQL query plumbing to accept a query string and pass it to ProjectV2.items.
Add --query flag parsing + end-to-end command behavior (including output) tests.
Introduce feature detection for whether a host’s schema supports the ProjectV2.items(query:) argument (with mocks/tests).

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pkg/cmd/project/shared/queries/queries.go	Adds `query` arg support to `ProjectItems` GraphQL query and method signature.
pkg/cmd/project/shared/queries/queries_test.go	Updates expected GraphQL variables and call signature for `ProjectItems`.
pkg/cmd/project/item-list/item_list.go	Adds `--query` flag and gates it behind feature detection.
pkg/cmd/project/item-list/item_list_test.go	Adds parsing + runtime tests for `--query` and unsupported-host behavior.
internal/featuredetection/feature_detection.go	Adds `ProjectFeatures()` to detect `ProjectV2.items(query:)` support on enterprise hosts.
internal/featuredetection/feature_detection_test.go	Adds tests validating `ProjectFeatures()` behavior across hosts/schema variants.
internal/featuredetection/detector_mock.go	Updates detector mocks to implement the new interface method.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

pkg/cmd/project/shared/queries/queries.go

pkg/cmd/project/item-list/item_list.go

babakks

Didn't fully test it, but I'm concerned about the query: $queryItems arg add to the GraphQL tag on Project.Items field.

internal/featuredetection/feature_detection.go

internal/featuredetection/feature_detection_test.go

pkg/cmd/project/item-list/item_list.go

babakks · Feb 17, 2026

pkg/cmd/project/item-list/item_list.go

+			if host == "" {
+				host = ghinstance.Default()
+			}
+			config.detector = fd.NewDetector(api.NewCachedHTTPClient(httpClient, time.Hour*24), host)


I think in other places we populate the detector in the runX func, ofc if it's nil.

pkg/cmd/project/shared/queries/queries.go

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

babakks

The code seems okay, although it's getting more complicated.

However, I'm seeing something weird when I run gh project list (in comparison to latest gh):

Seems like the changes have messed up with something.

internal/featuredetection/feature_detection.go

internal/featuredetection/feature_detection_test.go

babakks · Feb 18, 2026

pkg/cmd/project/item-list/item_list.go

+		Long: heredoc.Doc(`
+			List the items in a project.
+
+			If supported by the API host (github.com and GHES 3.20+), the --query option can


question: are we sure about GHES 3.20 support for this?

Well it's not in now in 3.19 and schema changes are always pulled in on release.

pkg/cmd/project/item-list/item_list.go

pkg/cmd/project/shared/queries/queries.go

babakks · Feb 18, 2026

pkg/cmd/project/shared/queries/queries.go

@@ -147,6 +173,27 @@ type Project struct {
 	}
 }

+func newProjectFromWithoutItemQuery(source projectWithoutItemQuery) *Project {
+	project := &Project{
+		Number:           source.Number,
+		URL:              source.URL,
+		ShortDescription: source.ShortDescription,
+		Public:           source.Public,
+		Closed:           source.Closed,
+		Title:            source.Title,
+		ID:               source.ID,
+		Readme:           source.Readme,
+		Fields:           source.Fields,
+	}
+	project.Items.PageInfo = source.Items.PageInfo
+	project.Items.TotalCount = source.Items.TotalCount
+	project.Items.Nodes = source.Items.Nodes
+	project.Owner.TypeName = source.Owner.TypeName
+	project.Owner.User.Login = source.Owner.User.Login
+	project.Owner.Organization.Login = source.Owner.Organization.Login
+	return project
+}
+
 func (p Project) DetailedItems() map[string]interface{} {
 	return map[string]interface{}{
 		"items":      serializeProjectWithItems(&p),
@@ -508,8 +555,10 @@ func (p ProjectItem) ExportData(_ []string) map[string]interface{} {
 }

 // ProjectItems returns the items of a project. If the OwnerType is VIEWER, no login is required.
-// If limit is 0, the default limit is used.
-func (c *Client) ProjectItems(o *Owner, number int32, limit int) (*Project, error) {
+// If limit is 0, the default limit is used. The queryStr parameter is passed as a server-side
+// filter to the items connection, using the same syntax as the GitHub Projects filter bar
+// (e.g. "assignee:octocat", "status:done").
+func (c *Client) ProjectItems(o *Owner, number int32, limit int, queryStr string) (*Project, error) {
 	project := &Project{}
 	if limit == 0 {
 		limit = LimitDefault
@@ -528,20 +577,35 @@ func (c *Client) ProjectItems(o *Owner, number int32, limit int) (*Project, erro
 		"afterFields": (*githubv4.String)(nil),
 		"number":      githubv4.Int(number),
 	}
+	if queryStr != "" {
+		variables["queryItems"] = githubv4.String(queryStr)
+	}

 	var query pager[ProjectItem]
 	var queryName string
 	switch o.Type {
 	case UserOwner:
 		variables["login"] = githubv4.String(o.Login)
-		query = &userOwnerWithItems{} // must be a pointer to work with graphql queries
+		if queryStr == "" {
+			query = &userOwnerWithItemsNoQuery{} // must be a pointer to work with graphql queries
+		} else {
+			query = &userOwnerWithItems{} // must be a pointer to work with graphql queries
+		}
 		queryName = "UserProjectWithItems"
 	case OrgOwner:
 		variables["login"] = githubv4.String(o.Login)
-		query = &orgOwnerWithItems{} // must be a pointer to work with graphql queries
+		if queryStr == "" {
+			query = &orgOwnerWithItemsNoQuery{} // must be a pointer to work with graphql queries
+		} else {
+			query = &orgOwnerWithItems{} // must be a pointer to work with graphql queries
+		}
 		queryName = "OrgProjectWithItems"
 	case ViewerOwner:
-		query = &viewerOwnerWithItems{} // must be a pointer to work with graphql queries
+		if queryStr == "" {
+			query = &viewerOwnerWithItemsNoQuery{} // must be a pointer to work with graphql queries
+		} else {
+			query = &viewerOwnerWithItems{} // must be a pointer to work with graphql queries
+		}


These are getting out of our hands. We already have had 2-3 types per owner type, and we're now adding 3 more.

I'm not blocking this PR, but we should prioritise a follow up to simplify this approach. Perhaps we should fallback to plain text queries?

Sorry, the range is wrong. I meant the last switch statement.

Co-authored-by: Babak K. Shandiz <babakks@github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

BagToad · Feb 18, 2026

pkg/cmd/project/item-list/item_list.go

+			return err
+		}
+		if !features.ProjectItemQuery {
+			return fmt.Errorf("the `--query` flag is not supported on this GitHub host; most likely you are targeting a version of GHES that does not yet have the query field available")


nit: this seems extra for an error message

BagToad · Feb 18, 2026

pkg/cmd/project/shared/queries/queries.go

+		if queryStr == "" {
+			query = &userOwnerWithItemsNoQuery{} // must be a pointer to work with graphql queries
+		} else {
+			query = &userOwnerWithItems{} // must be a pointer to work with graphql queries
+		}
 		queryName = "UserProjectWithItems"
 	case OrgOwner:
 		variables["login"] = githubv4.String(o.Login)
-		query = &orgOwnerWithItems{} // must be a pointer to work with graphql queries
+		if queryStr == "" {
+			query = &orgOwnerWithItemsNoQuery{} // must be a pointer to work with graphql queries
+		} else {
+			query = &orgOwnerWithItems{} // must be a pointer to work with graphql queries
+		}
 		queryName = "OrgProjectWithItems"
 	case ViewerOwner:
-		query = &viewerOwnerWithItems{} // must be a pointer to work with graphql queries
+		if queryStr == "" {
+			query = &viewerOwnerWithItemsNoQuery{} // must be a pointer to work with graphql queries
+		} else {
+			query = &viewerOwnerWithItems{} // must be a pointer to work with graphql queries
+		}


nit: code comments here could probably be just one comment for all of them

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Babak K. Shandiz <babakks@github.com>

Copilot AI review requested due to automatic review settings February 16, 2026 13:05

williammartin requested a review from a team as a code owner February 16, 2026 13:05

williammartin requested a review from BagToad February 16, 2026 13:05

williammartin temporarily deployed to cli-automation February 16, 2026 13:05 — with GitHub Actions Inactive

cliAutomation assigned williammartin Feb 16, 2026

Copilot started reviewing on behalf of williammartin February 16, 2026 13:05 View session

Copilot AI reviewed Feb 16, 2026

View reviewed changes

pkg/cmd/project/shared/queries/queries.go Show resolved Hide resolved

pkg/cmd/project/item-list/item_list.go Outdated Show resolved Hide resolved

williammartin marked this pull request as draft February 16, 2026 13:14

This comment was marked as spam.

Sign in to view

babakks reviewed Feb 17, 2026

View reviewed changes

williammartin marked this pull request as ready for review February 18, 2026 11:32

williammartin requested a review from babakks February 18, 2026 12:05

williammartin and others added 5 commits February 18, 2026 13:06

add --query flag to project item-list

2dabbde

fix project item-list query compatibility

f3481e4

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

refine query checks and tests

8d04abb

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

reduce query owner struct duplication

fc7434f

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

mention GHES version for query flag

40ce0be

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

williammartin force-pushed the wm-filter-assignee branch from 6ab0b3c to 40ce0be Compare February 18, 2026 12:06

babakks requested changes Feb 18, 2026

View reviewed changes

williammartin and others added 7 commits February 18, 2026 14:45

Update internal/featuredetection/feature_detection.go

29fa530

Co-authored-by: Babak K. Shandiz <babakks@github.com>

Update pkg/cmd/project/item-list/item_list.go

bcb85b3

Co-authored-by: Babak K. Shandiz <babakks@github.com>

Update pkg/cmd/project/item-list/item_list.go

78d44f7

Co-authored-by: Babak K. Shandiz <babakks@github.com>

clarify GHES query support error

1ccd453

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

refactor project query dto naming

febfb87

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

rename project query variable

a31ab1a

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

add missing reg.Verify

0953cf9

babakks approved these changes Feb 18, 2026

View reviewed changes

williammartin merged commit 8dcfd33 into trunk Feb 18, 2026
11 checks passed

williammartin deleted the wm-filter-assignee branch February 18, 2026 15:34

BagToad reviewed Feb 18, 2026

View reviewed changes

williammartin added a commit that referenced this pull request Feb 18, 2026

Add --query flag to project item-list (#12696)

ae909c7

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Babak K. Shandiz <babakks@github.com>

williammartin mentioned this pull request Feb 18, 2026

Clean up project item-list query addition changes #12714

Merged

williammartin added a commit that referenced this pull request Feb 18, 2026

Add --query flag to project item-list (#12696)

eac6821

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Babak K. Shandiz <babakks@github.com>

williammartin mentioned this pull request Feb 18, 2026

Remove license bundling debris #12716

Merged

Search code, repositories, users, issues, pull requests...

Comments

Conversation

williammartin commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Acceptance Criteria

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

This comment was marked as spam.

Uh oh!

babakks left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

babakks Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

babakks left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

babakks Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

williammartin Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

babakks Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

babakks Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

BagToad Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

BagToad Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

williammartin commented Feb 16, 2026 •

edited

Loading