gcloud CLI Skill for AI Agents
This document provides essential guidelines and best practices for AI agents
interacting with the Google Cloud SDK (gcloud CLI). Following these rules is
critical to avoid hallucinated commands, flags, flag values, and positional
argument syntax, prevent destructive actions, and minimize context window usage.
Getting Started
1. Installation
If the gcloud executable is missing, refer to the official
Google Cloud CLI Installation Guide
to install it on your platform (Linux, macOS, Windows, etc.).
2. Authorization
Authenticate the CLI with Google Cloud. Choose the flow that matches your
running environment:
- User Account (Interactive): Run
gcloud auth login. Follow the browser
prompts to sign in.
- User Account (Headless Flow): If operating on a terminal without a web
browser (e.g. containers, remote SSH), append the
--no-browser flag:
gcloud auth login --no-browser. Copy the URL, sign in on another machine,
and return the authentication code.
- Application Default Credentials (ADC): To authenticate code calls from
local applications or SDK libraries, set up ADC via
gcloud auth application-default login (append --no-browser for headless
environments).
- Service Account (Best for Detached/Headless Automation): Authenticate
directly using a JSON key file. Ideal for fully automated, background tasks
and pipelines:
gcloud auth activate-service-account --key-file=path/to/key.json. Note that some organizations may restrict
access to JSON key files for security reasons.
- Service Account Impersonation (Preferred for Local Pair-Programming
Agents): Leverage the human developer's existing user credentials to
assume a service account identity. Best for local development assistants to
avoid insecure private keys on human workstations:
gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL
Separation of Privilege (Critical): Both service account approaches ensure the
agent's permissions remain strictly distinct from the human user's wide access
limits (enforcing least privilege), and ensure actions are properly audited
under the agent's focused identity. (Impersonation requires
roles/iam.serviceAccountTokenCreator).
For more detailed strategies and authentication types (such as Workload Identity
Federation), see
Authorizing the gcloud CLI.
Core Principles
1. Explicit Command Validation (Mandatory)
Your internal knowledge of gcloud may be stale or prone to hallucination
(e.g., hallucinating commands, flags, flag values, or positional argument
syntax). You are FORBIDDEN from executing commands until you have validated
the exact syntax at the leaf level.
- Action: Always call
gcloud help <command> for the exact command you
intend to run (e.g., gcloud help compute instances create).
- Verify: Ensure the command, flags, flag values, and positional argument
syntax are valid for that specific leaf command before attempting execution.
Validation is not transitive from parent groups.
2. Data Reduction Strategies
To save context window space and reduce latency, always minimize the volume of
data returned by gcloud.
Projection: Use --format=json(key1, key2, ...) to select only the
specific fields needed for your task. To understand the advanced projection
and formatting syntax, refer to gcloud topic projections and gcloud topic formats.
Limiting: Use --limit=N to cap the number of resources returned.
Filtering: Use --filter to narrow down results server-side. Prioritize
: for pattern matching and never quote the right side of the colon. Treat
the entire filter flag as a singular string without quoting or escaping
characters. To study the filter expression syntax, refer to gcloud topic filters.
Schema Discovery: Unconstrained resource lists can quickly exhaust your
context window with redundant data. To prevent this, discover a resource's
schema before executing queries. If you are unsure of the JSON key path for
projecting fields (--format) or filtering (--filter), run the targeted
resource's list command (if supported) with a single-item limit:
gcloud <GROUP> <RESOURCE> list --limit=1 --format=json
Examine this single instance's JSON structure to safely identify the correct
schema keys before requesting full or filtered datasets.
3. Execution Constraints
- Single Commands: Execute a single
gcloud command at a time. No command
chaining or sequencing.
- No Shell Operators: Do not use command substitution (
$(...)), pipes
(|), or redirection (>, >>, <). This is to increase command safety
and ensure commands are more easily understandable and reviewable by users.
- No Interactivity: Do not run interactive commands or commands requiring
a TTY (e.g.,
gcloud interactive). You must enforce non-interactive mode by
appending --quiet (or -q) to your commands. This ensures that defaults
are used or errors are raised if input is required.
4. Project and Location Scoping (Critical)
To ensure commands are deterministic, non-interactive, and target the correct
environment, you must explicitly manage project and location scoping.
Explicit Project Target: Do not rely on active configuration defaults.
Always append --project=<PROJECT_ID> to all resource-manipulating and
querying commands (unless running pure local config commands). This avoids
accidental execution against the wrong project.
Prevent Location Prompts: Many Google Cloud resources are regional or
zonal. If you omit the location flag (e.g., --region, --zone, or
--location), gcloud will trigger an interactive prompt to select a
zone/region. This violates the No Interactivity rule. Always provide
explicit location flags if the command requires them.
Location Discovery: If you do not know the correct region, zone, or
location for a service, run discovery commands first (remembering to limit
results if there are many):
Compute Engine (VMs, Networks):
gcloud compute regions list --project=<PROJECT_ID>
gcloud compute zones list --project=<PROJECT_ID>
Other Services (Standard API Style): Many GCP services utilize a
unified locations list command:
gcloud <GROUP> locations list --project=<PROJECT_ID>
- Examples:
gcloud artifacts locations list, gcloud kms locations list, gcloud secrets locations list.
Safety & Guardrails
[!CAUTION] Destructive actions (delete, update, remove) MUST be explicitly
authorized by the user. Never invoke them autonomously unless explicitly
instructed to do so in the context of a safe, pre-approved workflow.
Prohibited Operations (Denylist)
You are strictly prohibited from executing the following commands
autonomously. These require explicit human-in-the-loop authorization:
- Any IAM policy, role, or binding modification (Security): Risk of
privilege escalation, administrative lockout, service disruption, or
unauthorized data exposure.
- No Proactive API Enabling: Assume necessary APIs are enabled. To prevent
unexpected resource provisioning or billing charges, do not proactively try
to enable APIs. User approval is required to enable any API.
gcloud * delete (Destructive): Irreversible resource destruction
(e.g., project deletion) or data wiping.
gcloud billing * (Financial): Risk of service disruption or unbounded
costs.
gcloud organizations * (Governance): Org-level changes affect security
posture for all users.
gcloud kms * (Encryption): Risk of permanently locking data.
gcloud infra-manager deployments apply (Destructive): Autonomous IaC
execution can destroy managed resources.
Execution Guidelines
Dry Run (Mandatory): You MUST invoke a command with --dry-run (or
equivalent) first if it exists, before executing the actual command, to
preview changes.
Long Running Operations: For commands that support it, the --async
flag is highly recommended for long-running operations to avoid blocking the
agentic flow. Note that not every command has an --async flag. For
commands that return an operation ID (whether via --async or by default),
you are responsible for polling for completion if the operation status is
needed for the next step.
Structured Workflows
Discovery Workflow
When asked to perform a task on a service you are not familiar with:
- You MUST invoke help on a command (e.g.,
gcloud help <COMMAND>) before
invoking it.
- If you do not know the exact command, traverse the command tree by invoking
help on a command group (e.g.,
gcloud help compute) to discover available
subcommands and groups.
- Schema Discovery: If you need to filter or project fields from a list
command, but do not know the exact JSON keys, first run
gcloud <GROUP> <RESOURCE> list --limit=1 --format=json to safely discover the schema.
Never run a raw list command without scoping constraints (like
--limit=1), as unconstrained results will pollute and exhaust your context
window.
- Execute with data reduction flags.
Quick Reference / Cheat Sheet
| Task |
Command Template |
| Discover Schema |
gcloud <GROUP> <RESOURCE> list --limit=1 --format=json |
| Filtered List |
gcloud <GROUP> <RESOURCE> list --filter="status:RUNNING" |
| Specific Columns |
gcloud <GROUP> <RESOURCE> list --format="json(name, id)" |
| Learn Filters |
gcloud topic filters |
| Learn Formats |
gcloud topic formats |
| Learn Projections |
gcloud topic projections |
| Asynchronous Op |
gcloud <COMMAND> --async |
| Check Operation |
gcloud operations describe <OPERATION_ID> |
| Common commands |
gcloud cheat-sheet |
| List Regions (GCE) |
gcloud compute regions list --project=<PROJECT_ID> |
| List Zones (GCE) |
gcloud compute zones list --project=<PROJECT_ID> |
| List Locations |
gcloud <GROUP> locations list --project=<PROJECT_ID> |
Refer to the
gcloud CLI Scripting Guide
for guidance on using the gcloud CLI in automation.
1---2name: gcloud3description: >-4 Interacts with Google Cloud services using the gcloud CLI safely and5 efficiently. Covers command validation, data reduction, safety guardrails with6 a denylist, and workflows for discovery and investigation. You MUST read this7 skill before invoking any gcloud command. Use when managing cloud resources,8 querying configurations, or troubleshooting issues via gcloud. Don't use when9 writing or debugging Google Cloud client library code or raw REST/gRPC API10 interactions.11metadata:12 source: https://skillmd.com/skills/zuoguyoupan2023/gcloud13---1415# gcloud CLI Skill for AI Agents1617This document provides essential guidelines and best practices for AI agents18interacting with the Google Cloud SDK (`gcloud` CLI). Following these rules is19critical to avoid hallucinated commands, flags, flag values, and positional20argument syntax, prevent destructive actions, and minimize context window usage.2122## Getting Started2324### 1. Installation2526If the `gcloud` executable is missing, refer to the official27[Google Cloud CLI Installation Guide](https://docs.cloud.google.com/sdk/docs/install-sdk)28to install it on your platform (Linux, macOS, Windows, etc.).2930### 2. Authorization3132Authenticate the CLI with Google Cloud. Choose the flow that matches your33running environment:3435* **User Account (Interactive)**: Run `gcloud auth login`. Follow the browser36 prompts to sign in.37* **User Account (Headless Flow)**: If operating on a terminal without a web38 browser (e.g. containers, remote SSH), append the `--no-browser` flag:39 `gcloud auth login --no-browser`. Copy the URL, sign in on another machine,40 and return the authentication code.41* **Application Default Credentials (ADC)**: To authenticate code calls from42 local applications or SDK libraries, set up ADC via `gcloud auth43 application-default login` (append `--no-browser` for headless44 environments).45* **Service Account (Best for Detached/Headless Automation)**: Authenticate46 directly using a JSON key file. Ideal for fully automated, background tasks47 and pipelines: `gcloud auth activate-service-account48 --key-file=path/to/key.json`. Note that some organizations may restrict49 access to JSON key files for security reasons.50* **Service Account Impersonation (Preferred for Local Pair-Programming51 Agents)**: Leverage the human developer's existing user credentials to52 assume a service account identity. Best for local development assistants to53 avoid insecure private keys on human workstations: `gcloud config set54 auth/impersonate_service_account SERVICE_ACCT_EMAIL`5556*Separation of Privilege (Critical)*: Both service account approaches ensure the57agent's permissions remain strictly distinct from the human user's wide access58limits (enforcing least privilege), and ensure actions are properly audited59under the agent's focused identity. *(Impersonation requires60`roles/iam.serviceAccountTokenCreator`)*.6162For more detailed strategies and authentication types (such as Workload Identity63Federation), see64[Authorizing the gcloud CLI](https://docs.cloud.google.com/sdk/docs/authorizing).6566## Core Principles6768### 1. Explicit Command Validation (Mandatory)6970Your internal knowledge of `gcloud` may be stale or prone to hallucination71(e.g., hallucinating commands, flags, flag values, or positional argument72syntax). You are **FORBIDDEN** from executing commands until you have validated73the exact syntax at the leaf level.7475* **Action**: Always call `gcloud help <command>` for the *exact* command you76 intend to run (e.g., `gcloud help compute instances create`).77* **Verify**: Ensure the command, flags, flag values, and positional argument78 syntax are valid for that specific leaf command before attempting execution.79 Validation is not transitive from parent groups.8081### 2. Data Reduction Strategies8283To save context window space and reduce latency, always minimize the volume of84data returned by `gcloud`.8586* **Projection**: Use `--format=json(key1, key2, ...)` to select only the87 specific fields needed for your task. To understand the advanced projection88 and formatting syntax, refer to `gcloud topic projections` and `gcloud topic89 formats`.9091* **Limiting**: Use `--limit=N` to cap the number of resources returned.9293* **Filtering**: Use `--filter` to narrow down results server-side. Prioritize94 `:` for pattern matching and never quote the right side of the colon. Treat95 the entire filter flag as a singular string without quoting or escaping96 characters. To study the filter expression syntax, refer to `gcloud topic97 filters`.9899* **Schema Discovery**: Unconstrained resource lists can quickly exhaust your100 context window with redundant data. To prevent this, discover a resource's101 schema before executing queries. If you are unsure of the JSON key path for102 projecting fields (`--format`) or filtering (`--filter`), run the targeted103 resource's list command (if supported) with a single-item limit:104105 ```bash106 gcloud <GROUP> <RESOURCE> list --limit=1 --format=json107 ```108109 Examine this single instance's JSON structure to safely identify the correct110 schema keys before requesting full or filtered datasets.111112### 3. Execution Constraints113114* **Single Commands**: Execute a single `gcloud` command at a time. No command115 chaining or sequencing.116* **No Shell Operators**: Do not use command substitution (`$(...)`), pipes117 (`|`), or redirection (`>`, `>>`, `<`). This is to increase command safety118 and ensure commands are more easily understandable and reviewable by users.119* **No Interactivity**: Do not run interactive commands or commands requiring120 a TTY (e.g., `gcloud interactive`). You must enforce non-interactive mode by121 appending `--quiet` (or `-q`) to your commands. This ensures that defaults122 are used or errors are raised if input is required.123124### 4. Project and Location Scoping (Critical)125126To ensure commands are deterministic, non-interactive, and target the correct127environment, you must explicitly manage project and location scoping.128129* **Explicit Project Target**: Do not rely on active configuration defaults.130 Always append `--project=<PROJECT_ID>` to all resource-manipulating and131 querying commands (unless running pure local config commands). This avoids132 accidental execution against the wrong project.133134* **Prevent Location Prompts**: Many Google Cloud resources are regional or135 zonal. If you omit the location flag (e.g., `--region`, `--zone`, or136 `--location`), `gcloud` will trigger an interactive prompt to select a137 zone/region. This violates the **No Interactivity** rule. Always provide138 explicit location flags if the command requires them.139140* **Location Discovery**: If you do not know the correct region, zone, or141 location for a service, run discovery commands first (remembering to limit142 results if there are many):143144 * **Compute Engine (VMs, Networks)**:145146 * `gcloud compute regions list --project=<PROJECT_ID>`147 * `gcloud compute zones list --project=<PROJECT_ID>`148149 * **Other Services (Standard API Style)**: Many GCP services utilize a150 unified `locations list` command:151152 * `gcloud <GROUP> locations list --project=<PROJECT_ID>`153 * *Examples*: `gcloud artifacts locations list`, `gcloud kms locations154 list`, `gcloud secrets locations list`.155156## Safety & Guardrails157158> [!CAUTION] **Destructive actions (delete, update, remove) MUST be explicitly159> authorized by the user.** Never invoke them autonomously unless explicitly160> instructed to do so in the context of a safe, pre-approved workflow.161162### Prohibited Operations (Denylist)163164You are **strictly prohibited** from executing the following commands165autonomously. These require explicit human-in-the-loop authorization:166167* **Any IAM policy, role, or binding modification** (Security): Risk of168 privilege escalation, administrative lockout, service disruption, or169 unauthorized data exposure.170* **No Proactive API Enabling**: Assume necessary APIs are enabled. To prevent171 unexpected resource provisioning or billing charges, do not proactively try172 to enable APIs. User approval is required to enable any API.173* **`gcloud * delete`** (Destructive): Irreversible resource destruction174 (e.g., project deletion) or data wiping.175* **`gcloud billing *`** (Financial): Risk of service disruption or unbounded176 costs.177* **`gcloud organizations *`** (Governance): Org-level changes affect security178 posture for all users.179* **`gcloud kms *`** (Encryption): Risk of permanently locking data.180* **`gcloud infra-manager deployments apply`** (Destructive): Autonomous IaC181 execution can destroy managed resources.182183### Execution Guidelines184185* **Dry Run (Mandatory)**: You MUST invoke a command with `--dry-run` (or186 equivalent) first if it exists, before executing the actual command, to187 preview changes.188189* **Long Running Operations**: For commands that support it, the `--async`190 flag is highly recommended for long-running operations to avoid blocking the191 agentic flow. Note that not every command has an `--async` flag. For192 commands that return an operation ID (whether via `--async` or by default),193 you are responsible for polling for completion if the operation status is194 needed for the next step.195196## Structured Workflows197198### Discovery Workflow199200When asked to perform a task on a service you are not familiar with:2012021. You MUST invoke help on a command (e.g., `gcloud help <COMMAND>`) before203 invoking it.2042. If you do not know the exact command, traverse the command tree by invoking205 help on a command group (e.g., `gcloud help compute`) to discover available206 subcommands and groups.2073. **Schema Discovery**: If you need to filter or project fields from a list208 command, but do not know the exact JSON keys, first run `gcloud <GROUP>209 <RESOURCE> list --limit=1 --format=json` to safely discover the schema.210 **Never** run a raw `list` command without scoping constraints (like211 `--limit=1`), as unconstrained results will pollute and exhaust your context212 window.2134. Execute with data reduction flags.214215## Quick Reference / Cheat Sheet216217Task | Command Template218------------------ | ----------------------------------------------------------219Discover Schema | `gcloud <GROUP> <RESOURCE> list --limit=1 --format=json`220Filtered List | `gcloud <GROUP> <RESOURCE> list --filter="status:RUNNING"`221Specific Columns | `gcloud <GROUP> <RESOURCE> list --format="json(name, id)"`222Learn Filters | `gcloud topic filters`223Learn Formats | `gcloud topic formats`224Learn Projections | `gcloud topic projections`225Asynchronous Op | `gcloud <COMMAND> --async`226Check Operation | `gcloud operations describe <OPERATION_ID>`227Common commands | `gcloud cheat-sheet`228List Regions (GCE) | `gcloud compute regions list --project=<PROJECT_ID>`229List Zones (GCE) | `gcloud compute zones list --project=<PROJECT_ID>`230List Locations | `gcloud <GROUP> locations list --project=<PROJECT_ID>`231232Refer to the233[gcloud CLI Scripting Guide](https://docs.cloud.google.com/sdk/docs/scripting-gcloud)234for guidance on using the gcloud CLI in automation.