Using gcloud Safely with safe-gcloud

Overview

Direct gcloud commands are blocked in this environment. All Google Cloud CLI operations must go through the safe-gcloud wrapper script, which enforces a project-specific allowlist of permitted commands.

How to Run gcloud Commands

Execute gcloud commands through the safe-gcloud wrapper script:

bash ${CLAUDE_PLUGIN_ROOT}/skills/safe-gcloud-usage/scripts/safe-gcloud.sh <command> [args...]

Examples:

bash ${CLAUDE_PLUGIN_ROOT}/skills/safe-gcloud-usage/scripts/safe-gcloud.sh projects list --format=json bash ${CLAUDE_PLUGIN_ROOT}/skills/safe-gcloud-usage/scripts/safe-gcloud.sh config get-value project bash ${CLAUDE_PLUGIN_ROOT}/skills/safe-gcloud-usage/scripts/safe-gcloud.sh auth list

The wrapper passes all arguments, flags, and piped input directly to gcloud for permitted commands.

Allowlist Configuration

Each project defines permitted commands in .claude/gcloud-allowlist.json . This file contains a JSON array of command patterns.

Pattern Syntax

Pattern Matches Does Not Match

projects list

Exactly gcloud projects list

gcloud projects list --format=json

projects list:*

gcloud projects list with any args/flags gcloud projects describe

projects:*

Any gcloud projects subcommand gcloud compute instances list

Example Allowlist

[ "projects list:", "config get-value:", "auth list", "compute instances list:", "compute instances describe:" ]

Critical Restrictions

NEVER attempt to edit .claude/gcloud-allowlist.json . This file is under user control only. When a command is blocked due to missing permissions:

• Inform the user which command was blocked

• Suggest the pattern they could add to permit it

• Wait for the user to update the allowlist themselves

When Commands Are Blocked

If safe-gcloud blocks a command, it provides:

• The exact command that was attempted

• An error explaining the command is not in the allowlist

• A suggested pattern to add

Example blocked output:

ERROR: Command not permitted by allowlist.

Attempted command: gcloud compute instances list --zone=us-central1-a

The allowlist at .claude/gcloud-allowlist.json does not include a pattern that permits this command.

To allow this command, add an appropriate pattern to the allowlist. For example, to allow this specific command with any flags: "compute instances list:*"

Suggesting Patterns to Users

When the user asks what pattern to add, analyze the command and suggest the appropriate pattern:

• For a specific command with flags: "<command> <subcommand>:*"

• For all subcommands of a service: "<service>:*"

• For exact command only (no flags): "<command> <subcommand>"

Example suggestions:

• User wants gcloud run deploy : suggest "run deploy:*"

• User wants all compute commands: suggest "compute:*"

• User wants only gcloud auth list with no flags: suggest "auth list"

Missing Allowlist File

If .claude/gcloud-allowlist.json does not exist, all gcloud commands are blocked. Inform the user they need to create this file with their desired patterns.

Dependencies

The safe-gcloud wrapper requires:

• gcloud CLI installed and configured