/gcloud

name: gcloud
metadata:
  category: CloudInfrastructureAndServices
description: >-
  Provides safety-critical validation, guardrails, and data reduction for gcloud
  CLI operations across Google Cloud Platform (GCP) services and infrastructure.
  Use when planning, generating, constructing, proposing, describing, or
  executing any gcloud CLI commands - including when answering questions about
  gcloud syntax, or formatting flags. Don't use when writing Google Cloud
  client library code or raw REST/gRPC API requests.

gcloud CLI Skill for AI Agents

> [!CAUTION] > > ### MANDATORY PRE-CONDITION: EXPLICIT LEAF-LEVEL SYNTAX VALIDATION > > All pre-existing knowledge of `gcloud` commands, flags, flag values, and > positional argument syntax is **stale and prone to hallucination**. > > NEVER propose command parameters, output flag options, execute commands, OR > outline step-by-step plans for any `gcloud` task before validating leaf-level > syntax via `gcloud help <command>` (or including leaf-level help lookup as a > mandatory step in the plan). > > **Mandatory Action Rules**: > > 1. **Direct Execution & Code Generation**: **ALWAYS** invoke `gcloud help > <leaf_command>` (e.g. `gcloud help compute instances create` or `gcloud > help sql instances create`) before proposing or executing the final > command syntax. > > 2. **Planning & Strategy Queries**: When asked for a plan, strategy, or next > steps to achieve a user goal (e.g., *"What is your plan to accomplish > X..."*), the response **MUST explicitly include running `gcloud help > <leaf_command>`** as Step 1 of the plan before proposing flags or > executing commands. > > 3. **Non-Transitive Validation**: Parent command group help (e.g. `gcloud > help compute`) is not sufficient for leaf-level syntax validation. > Validation must occur at the specific leaf subcommand level. > > 4. **FORBIDDEN Web Search Fallback**: NEVER use `search_web`, web search, or > external documentation search tools for gcloud CLI syntax. `gcloud help > <leaf_command>` is the **EXCLUSIVE** authorized authority for command > syntax. > > 5. **User Flag & Project Preservation**: When proposing intermediate command > steps, **ALWAYS** preserve all user-specified flags (including > `--project=<project_id>`) in the proposed response text. > > 6. **Mandatory Plan Template**: When generating a plan, the response **MUST** > copy this exact 4-step structure: > > - **Step 1**: Syntax Validation via `gcloud help <leaf_command>` > - **Step 2**: Parameter Verification (confirming required and optional > flags, and explicitly checking if the `--dry-run` or `--validate-only` > flag is supported) > - **Step 3**: Dry-Run Command Proposal (If `--dry-run` or > `--validate-only` is supported, there MUST be a `--dry-run` or > `--validate-only` invocation before the next step.) > - **Step 4**: Command Proposal & Authorization (If the command is on the > "Prohibited Operations" denylist, state that autonomous execution is > forbidden, and the user MUST be explicitly asked for authorization to > proceed. If the command is NOT on the denylist, propose or proceed > with execution, while following *ALL* "Execution Constraints" below.)

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.

Execution Modes

AI agents can interact with Google Cloud resources in two primary ways:

• **Direct CLI Execution**: Executing `gcloud` commands directly in a local or

automated shell environment. See [CLI Usage](references/cli-usage.md) for installation, authentication flows, and configuration management.

• **Model Context Protocol (MCP)**: Invoking structured tools via the Cloud

CLI remote MCP server (`run_gcloud_command`). See [MCP Usage](references/mcp-usage.md) for tool schemas, parameter rules, and server configuration.

Core Principles

1. Explicit Command Validation (Mandatory)

• **Action**: **ALWAYS** call `gcloud help <command>` for the *exact* command

that is intended to be 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 or presenting plans. Validation is not transitive from parent groups.

2. Data Reduction Strategies (Mandatory)

Minimize the volume of data returned by `gcloud` to save context window space and reduce latency. DO NOT execute any `list` command without including at least one data reduction flag (`--limit`, `--filter`, or `--format`).

• **Projection**: Use `--format="json(key1, key2, ...)"` to select only the

specific fields needed for the 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 the

context window with redundant data. To prevent this, discover a resource's schema before executing queries. If 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: