gcp-projects

Search projects using Cloud Resource Manager API.

Syntax

gcp-projects [profile=STRING] [scope=STRING] [query=STRING] [limit=INT]

Options

profile=STRING: Optional. Google Cloud connect profile. If multiple profiles are separated by commas, each profile is queried in turn and distinguished by the profile field. If not specified, all Google Cloud connect profiles you can use are queried. If an error occurs on a profile, rows already returned remain, the remaining profiles are skipped and the query ends with an error.
scope=STRING: Optional. folders/{number} or organizations/{number}. Returns direct child projects only, not projects in sub folders. If not specified, returns all projects the service account can access, including projects in other organizations.
query=STRING: Optional. Search query of Resource Manager. e.g. state:ACTIVE, id:my-project*, labels.env:prod. Free text without a field is not supported. See the query parameter of projects.search.
limit=INT: Optional. Max number of rows per profile. Positive integer. All rows are returned if not specified.

Output fields

Field	Type	Name	Description
profile	String	Profile	Connect profile name
project_id	String	Project ID	User assigned project ID. e.g. my-project-123456
display_name	String	Display name	Display name of the project
state	String	State	ACTIVE or DELETE_REQUESTED
parent	String	Parent	folders/{number} or organizations/{number}
project_number	String	Project number	System generated project number. e.g. 345678901234
labels	Map	Labels	User defined labels
create_time	Date	Created at	Create time of the project
update_time	Date	Updated at	Last update time of the project
delete_time	Date	Delete requested at	Time when deletion was requested

Error codes

Parse errors

Error message	Cause	Solution
No available Google Cloud profile found.	Wrong profile code or no permission to use the profile	Specify the connect profile code in the profile option and check the profile permission
Invalid scope: {scope}	Invalid scope format, or projects/ specified	Specify folders/{number} or organizations/{number}
limit should be positive integer: {limit}	limit is 0 or less, or not a number	Specify a positive integer

Runtime errors

Error message	Cause	Solution
HTTP 403: PERMISSION_DENIED - The caller does not have permission	No permission on the folder or organization specified in scope	Grant the Browser role on the scope
HTTP 403: PERMISSION_DENIED - Cloud Resource Manager API has not been used in project ...	Cloud Resource Manager API is not enabled in the project of the service account	Enable Cloud Resource Manager API in the project the service account belongs to
HTTP 400: INVALID_ARGUMENT - field [query] has issue [...]	Invalid query syntax, unsupported field, or free text without a field	Use field:value form. e.g. name:my-project*
token exchange failed, HTTP 400: Invalid grant	Wrong JSON key, or the service account or key was deleted	Create a new key and update the connect profile

Description

Searches projects on which the service account has resourcemanager.projects.get permission using projects:search of Cloud Resource Manager API v3. Projects without permission are excluded from the results without an error. If no rows are returned, check the Browser role of the service account with gcp-check-permissions.

If scope is specified, only direct child projects of the folder or organization are returned, because search of Resource Manager supports matching the direct parent only. To list all projects in the organization including sub folders, use gcp-assets with types=cloudresourcemanager.googleapis.com/Project.

If both query and scope are specified, query is sent to Google Cloud and scope is applied to the results, because multiple conditions in a Resource Manager query match if any of them matches.

Project information can also be retrieved with gcp-assets and types=cloudresourcemanager.googleapis.com/Project. Choose a command as follows.

Situation	Recommended command
All projects of an organization with folders and tags	gcp-assets (requires Cloud Asset Viewer role on the organization)
Projects without an organization or across multiple organizations at once	gcp-projects (without scope)
Projects the service account can access, or deletion request time	gcp-projects

Note

Newly created projects or newly granted roles may appear in the results after a few minutes. Project tags are not returned by this command. Use tags and effective_tags of gcp-assets.

Examples

Example: Accessible projects

Situation: Check the projects the service account can access and where they belong.

gcp-projects profile=gcp
| fields project_id, project_number, display_name, parent, state, create_time

Expected result:

project_id	project_number	display_name	parent	state	create_time
my-project-123456	345678901234	My Project	organizations/123456789012	ACTIVE	2026-10-06 14:42:46+0900
test-project-234567	456789012345	Test Project	folders/234567890123	ACTIVE	2026-10-15 11:22:13+0900

Interpretation: parent shows whether a project is directly under the organization or under a folder.

Example: Active projects directly under a folder

Situation: See active projects directly under a specific folder only.

gcp-projects profile=gcp scope=folders/234567890123 query="state:ACTIVE"
| fields project_id, display_name, state

Interpretation: Projects requested for deletion (DELETE_REQUESTED) are excluded. Projects in sub folders are not returned.