gcloud — Google Cloud Platform CLI
Command-line interface for managing Google Cloud resources.
Covers gcloud, gcloud storage (replaces gsutil), and bq (BigQuery).
Platform Notes (Windows + Git Bash)
- Install:
scoop install gcloud (preferred) or GoogleCloudSDKInstaller.exe
- If installed via scoop,
gcloud components install may not work — use scoop to manage
- Config:
%APPDATA%/gcloud/ (PowerShell) or ~/.config/gcloud/ (Git Bash)
- Service account keys: store in
$TEMP or project .secrets/, never commit
- Python: gcloud requires Python; scoop install handles this automatically
⚠️ Path Translation Gotcha
Git Bash auto-translates /-prefixed args, breaking some gcloud commands:
# FIX — disable MSYS path conversion:
export MSYS_NO_PATHCONV=1
# Or per-command:
MSYS_NO_PATHCONV=1 gcloud projects add-iam-policy-binding my-project ...
⚠️ Cost: Commands that create resources (instances, clusters, databases) incur
GCP charges. Always confirm project and region before creating.
Agent Safety Model
Operations classified by risk. Follow this model for all gcloud commands.
| Level |
Gate |
Examples |
| READ |
Proceed autonomously |
list, describe, get, logs read, config list, gcloud storage ls |
| WRITE |
Confirm with user; note cost if billable |
create, deploy, update, enable, gcloud storage cp (upload) |
| DESTRUCTIVE |
Always confirm; show what's affected |
delete, rm, gsutil rm -r, bq rm -r, rsync -d, IAM removal |
| EXPENSIVE |
Confirm + state approximate cost |
GKE clusters ($70+/mo), SQL instances ($8-400/mo), VMs (~$5-2k/mo) |
| SECURITY |
Confirm + explain impact |
--allow-unauthenticated, firewall rules, IAM owner/editor grants |
| FORBIDDEN |
Refuse; escalate to human |
gcloud iam service-accounts keys create, gcloud projects delete, passwords in CLI args |
Rules:
- Never combine
--quiet with destructive operations — it suppresses the only safety gate
- Never put passwords/secrets as command-line arguments — visible in process list & shell history
- Always use
--format=json for machine-parseable output (agents can't reliably parse tables)
- When in doubt, treat as DESTRUCTIVE
Command Structure
gcloud [RELEASE_LEVEL] COMPONENT ENTITY OPERATION [ARGS] [FLAGS]
Key global flags: --project, --format, --filter, --limit, --quiet, --verbosity, --async
Service Reference
| Service |
File |
Key Commands |
| Auth & Config |
auth.md |
Login, ADC, impersonation, config profiles |
| IAM & Projects |
iam.md |
Projects, APIs, service accounts, Secret Manager |
| Compute & Networking |
compute.md |
VMs, SSH, firewall, VPC, DNS, static IPs |
| Serverless |
serverless.md |
Cloud Run, Functions, App Engine, Scheduler, Tasks |
| Storage & Artifacts |
storage.md |
gcloud storage, Artifact Registry |
| Data |
data.md |
Cloud SQL, BigQuery (bq), Pub/Sub |
| Automation & CI/CD |
automation.md |
Scripting, output formats, filtering, GitHub Actions, operations |
Read the per-service file for full command reference.
Pre-Flight Checks
Before working with any GCP service:
# 1. Correct project?
gcloud config get-value project
# 2. Default region set?
gcloud config get-value compute/region
# 3. Required API enabled? (most APIs are disabled by default)
gcloud services list --filter="name:run.googleapis.com" --format="value(name)" | grep -q run || \
gcloud services enable run.googleapis.com
# 4. Billing enabled?
gcloud billing projects describe $(gcloud config get-value project) --format="value(billingEnabled)"
If you hit PERMISSION_DENIED: ... API has not been enabled, enable the API
mentioned in the error and retry.
Troubleshooting
| Problem |
Diagnosis |
Fix |
| Auth failure |
gcloud auth list |
gcloud auth login or check key file |
| Permission denied |
Check IAM (see iam.md) |
Grant correct role |
| API not enabled |
Error message says which API |
gcloud services enable API_NAME |
| Quota exceeded |
gcloud compute project-info describe |
Request increase in Console |
| Wrong project |
gcloud config get-value project |
gcloud config set project X |
| Wrong region |
gcloud config get-value compute/region |
Set correct region; related resources must match |
| Config confusion |
gcloud config configurations list |
Check active config, override with --project |
| Slow commands |
Large result set |
Use --filter, --limit, --format=value |
# Debug mode
gcloud compute instances list --verbosity=debug
# Full environment info
gcloud info
Quick Reference
| Task |
Command |
| Login |
gcloud auth login |
| Set project |
gcloud config set project PROJECT_ID |
| Current project |
gcloud config get-value project |
| Enable API |
gcloud services enable API.googleapis.com |
| List anything |
gcloud COMPONENT list --format=json |
| Describe anything |
gcloud COMPONENT describe NAME --format=json |
| JSON output |
--format=json |
| Single value |
--format="value(field)" |
| Filter |
--filter="field=value" |
| Quiet ⚠️ |
--quiet — suppresses ALL prompts including delete confirmations |
| Help |
gcloud COMPONENT --help |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: marcfargas-skills-gcloud3description: gcloud — Google Cloud Platform CLI4---56# gcloud — Google Cloud Platform CLI78Command-line interface for managing Google Cloud resources.9Covers `gcloud`, `gcloud storage` (replaces `gsutil`), and `bq` (BigQuery).1011## Platform Notes (Windows + Git Bash)1213- Install: `scoop install gcloud` (preferred) or `GoogleCloudSDKInstaller.exe`14- If installed via scoop, `gcloud components install` may not work — use scoop to manage15- Config: `%APPDATA%/gcloud/` (PowerShell) or `~/.config/gcloud/` (Git Bash)16- Service account keys: store in `$TEMP` or project `.secrets/`, **never commit**17- Python: gcloud requires Python; scoop install handles this automatically1819### ⚠️ Path Translation Gotcha2021Git Bash auto-translates `/`-prefixed args, breaking some gcloud commands:2223```bash24# FIX — disable MSYS path conversion:25export MSYS_NO_PATHCONV=12627# Or per-command:28MSYS_NO_PATHCONV=1 gcloud projects add-iam-policy-binding my-project ...29```3031> **⚠️ Cost**: Commands that create resources (instances, clusters, databases) incur32> GCP charges. Always confirm project and region before creating.3334## Agent Safety Model3536Operations classified by risk. **Follow this model for all gcloud commands.**3738| Level | Gate | Examples |39|-------|------|----------|40| **READ** | Proceed autonomously | `list`, `describe`, `get`, `logs read`, `config list`, `gcloud storage ls` |41| **WRITE** | Confirm with user; note cost if billable | `create`, `deploy`, `update`, `enable`, `gcloud storage cp` (upload) |42| **DESTRUCTIVE** | Always confirm; show what's affected | `delete`, `rm`, `gsutil rm -r`, `bq rm -r`, `rsync -d`, IAM removal |43| **EXPENSIVE** | Confirm + state approximate cost | GKE clusters (~$70+/mo), SQL instances (~$8-400/mo), VMs (~$5-2k/mo) |44| **SECURITY** | Confirm + explain impact | `--allow-unauthenticated`, firewall rules, IAM owner/editor grants |45| **FORBIDDEN** | Refuse; escalate to human | `gcloud iam service-accounts keys create`, `gcloud projects delete`, passwords in CLI args |4647**Rules**:4849- **Never combine `--quiet` with destructive operations** — it suppresses the only safety gate50- **Never put passwords/secrets as command-line arguments** — visible in process list & shell history51- **Always use `--format=json`** for machine-parseable output (agents can't reliably parse tables)52- **When in doubt, treat as DESTRUCTIVE**5354## Command Structure5556```text57gcloud [RELEASE_LEVEL] COMPONENT ENTITY OPERATION [ARGS] [FLAGS]58```5960Key global flags: `--project`, `--format`, `--filter`, `--limit`, `--quiet`, `--verbosity`, `--async`6162## Service Reference6364| Service | File | Key Commands |65|---------|------|-------------|66| Auth & Config | [auth.md](ref/auth.md) | Login, ADC, impersonation, config profiles |67| IAM & Projects | [iam.md](ref/iam.md) | Projects, APIs, service accounts, Secret Manager |68| Compute & Networking | [compute.md](ref/compute.md) | VMs, SSH, firewall, VPC, DNS, static IPs |69| Serverless | [serverless.md](ref/serverless.md) | Cloud Run, Functions, App Engine, Scheduler, Tasks |70| Storage & Artifacts | [storage.md](ref/storage.md) | gcloud storage, Artifact Registry |71| Data | [data.md](ref/data.md) | Cloud SQL, BigQuery (bq), Pub/Sub |72| Automation & CI/CD | [automation.md](ref/automation.md) | Scripting, output formats, filtering, GitHub Actions, operations |7374**Read the per-service file for full command reference.**7576## Pre-Flight Checks7778Before working with any GCP service:7980```bash81# 1. Correct project?82gcloud config get-value project8384# 2. Default region set?85gcloud config get-value compute/region8687# 3. Required API enabled? (most APIs are disabled by default)88gcloud services list --filter="name:run.googleapis.com" --format="value(name)" | grep -q run || \89 gcloud services enable run.googleapis.com9091# 4. Billing enabled?92gcloud billing projects describe $(gcloud config get-value project) --format="value(billingEnabled)"93```9495**If you hit `PERMISSION_DENIED: ... API has not been enabled`**, enable the API96mentioned in the error and retry.9798## Troubleshooting99100| Problem | Diagnosis | Fix |101|---------|-----------|-----|102| Auth failure | `gcloud auth list` | `gcloud auth login` or check key file |103| Permission denied | Check IAM (see [iam.md](iam.md)) | Grant correct role |104| API not enabled | Error message says which API | `gcloud services enable API_NAME` |105| Quota exceeded | `gcloud compute project-info describe` | Request increase in Console |106| Wrong project | `gcloud config get-value project` | `gcloud config set project X` |107| Wrong region | `gcloud config get-value compute/region` | Set correct region; related resources must match |108| Config confusion | `gcloud config configurations list` | Check active config, override with `--project` |109| Slow commands | Large result set | Use `--filter`, `--limit`, `--format=value` |110111```bash112# Debug mode113gcloud compute instances list --verbosity=debug114115# Full environment info116gcloud info117```118119## Quick Reference120121| Task | Command |122|------|---------|123| Login | `gcloud auth login` |124| Set project | `gcloud config set project PROJECT_ID` |125| Current project | `gcloud config get-value project` |126| Enable API | `gcloud services enable API.googleapis.com` |127| List anything | `gcloud COMPONENT list --format=json` |128| Describe anything | `gcloud COMPONENT describe NAME --format=json` |129| JSON output | `--format=json` |130| Single value | `--format="value(field)"` |131| Filter | `--filter="field=value"` |132| Quiet ⚠️ | `--quiet` — suppresses ALL prompts including delete confirmations |133| Help | `gcloud COMPONENT --help` |134135---136> Converted and distributed by [TomeVault](https://tomevault.io/claim/marcfargas) — claim your Tome and manage your conversions.137<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io