/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.

Getting Started

1. Installation

If the `gcloud` executable is missing, refer to the official [Google Cloud CLI Installation Guide](https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt) to install it on the current platform (Linux, macOS, Windows, etc.).

2. Authorization

Authenticate the CLI with Google Cloud. Choose the flow that matches the 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](https://docs.cloud.google.com/sdk/docs/authorizing.md.txt).

Core Principles

1. Explicit Command Validation (Mandatory)

• **Action**: **ALWAYS** call `gclo