Gcloud

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 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 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:

    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.
• Non-Interactive Execution (`--quiet` / `-q`): Pass the --quiet (or -q) global flag on all execution commands (e.g., gcloud pubsub topics delete temp-topic --quiet --project=test-project). AI agents run in headless, non-interactive environments without a TTY or stdin input handler. Without --quiet, commands that prompt for user confirmation (such as deleting resources, approving defaults, or selecting unspecified regions) will pause execution indefinitely waiting for input, causing background task timeouts. Including --quiet forces non-interactive mode, causing gcloud to automatically accept safe default choices or fail immediately with an explicit error if required parameters are missing.
• No Blind Lists: NEVER execute a list command without --limit, --filter, or --format.

4. Project and Location Scoping (Critical)

To ensure commands are deterministic, non-interactive, and target the correct environment, they must explicitly provide 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 the location flag is omitted (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 the correct region, zone, or location for a service is not known, run discovery commands first (remembering to limit results if there are many):