gcloud CLI for agentic workflows

Give agents a working gcloud without a browser login every chat — and decide whether that identity should be your user or an org service account. Multiple user logins can sit on one machine; only one is active at a time.

Operator logs in once per account, machine stores gcloud credentials for each, agent uses the active account without printing secrets
Figure 1. Operator authenticates in a normal terminal; the SDK keeps credentials per account on disk. Agents reuse the active account — switch with gcloud config set account, do not re-login for every org.
Sibling

Bitwarden CLI for agentic workflows.

OAuth / Project boundaries (Console)

Google Cloud projects as OAuth boundaries.

Default: individual user login (recommended for workstations)

gcloud auth login stores refresh tokens under the Cloud SDK config directory (on Windows, under %APPDATA%\gcloud\). They remain until gcloud auth revoke / gcloud logout or Google revokes the grant.

  1. One-time per Google account (interactive terminal — not a non-interactive agent shell waiting on EOF):

    # Prefer the full path if `gcloud` is not on PATH
& "$env:LOCALAPPDATA\Google\Cloud SDK\google-cloud-sdk\bin\gcloud.cmd" auth login

  2. Prefer the org operator account for org-owned projects (example: Workspace user on the company domain). Extra personal or other-org accounts may also be logged in — see Multiple credentialed accounts (one active).

  3. Verify:

    gcloud auth list
gcloud projects list --format="table(projectId,name,lifecycleState)"

  4. Agents thereafter reuse stored credentials — no re-login until revoke. Confirm the active account matches the org before project admin work.

Agent shells that cannot type a verification code will fail gcloud auth login --no-launch-browser. Complete login in a normal terminal (or browser-launched flow), then let agents use the stored account.

Multiple credentialed accounts (one active)

Repeated gcloud auth login calls accumulate accounts. They do not replace or drop prior sessions. Only one account is active at a time (marked * in gcloud auth list).

Typical workstation example (illustrative emails):

List accounts and see which is active:

+

gcloud auth list
Switch the active user without re-login (must already appear in auth list):

+

gcloud config set account [email protected]
gcloud auth list

When to flip account vs named configurations

  • Flip default account (gcloud config set account EMAIL) — enough when you mostly share one property set (project, region) and only the identity changes, or you always pass --project explicitly.

  • Named configurations (gcloud config configurations) — prefer when org pairs differ on more than email (default project, billing account, region, or quota project). Keep one config per org (example: ftn, devcentr) and activate with gcloud config configurations activate NAME.

Agents should gcloud auth list (and activate the right configuration if used) before Resource Manager / billing / credentials admin for an org. Wrong active account → wrong project visibility or permission errors that look like “missing IAM”.

What removes credentials

| Action | Effect |

gcloud auth revoke / gcloud auth revoke ACCOUNT

Drops that account’s stored refresh token from this machine

gcloud logout

Revokes / clears the active (or specified) login session

Google account / admin revoke of the grant

Tokens stop working even if files remain until cleaned up

Switching with gcloud config set account does not revoke anything. Re-login is only needed after revoke/logout or a dead grant.

Why prefer individual login on a desk

  • Audit trail matches a real person (IAM + Cloud Audit Logs).

  • No long-lived JSON key on disk for day-to-day Console/API admin.

  • Matches how you already treat Bitwarden: you unlock once; agents reuse.

  • Multi-org desks stay simple: login each operator identity once, switch active account (or named config) per task.

Optional: org service account (headless / shared agents)

Use when a machine must run GCP admin without a human login (CI-like agent host, overnight automation). Not required for a normal encrypted laptop where you can log in once.

  1. Create a service account in the platform GCP project (least privilege — Project Viewer / Service Usage / Resource Manager as needed).

  2. Store the JSON key machine-local only (Bitwarden item + ignored path such as %USERPROFILE%\gcloud-sa.<org>.local.json). Never commit; never paste into chat.

  3. Activate when no user account is present:

    gcloud auth activate-service-account --key-file="$env:USERPROFILE\gcloud-sa.<org>.local.json"

  4. Document the key path (not the key) in $CODE_ROOT/machine.md. Optional harness stamp: GCLOUD_AGENT_ENTRY = ensure_gcloud_auth.ps1 once you ship that helper (mirror Bitwarden’s entry script pattern).

JSON keys are powerful and easy to leak. Prefer user login on personal workstations; reserve SA keys for true headless hosts and rotate on a schedule.

What agents should do

  1. Resolve gcloud (PATH or Cloud SDK install path).

  2. Run gcloud auth list. If empty → stop and ask the operator to complete gcloud auth login (or activate the documented SA).

  3. If multiple accounts are present, ensure the active account (and named configuration, if used) matches the org for the task — gcloud config set account EMAIL or gcloud config configurations activate NAME. Do not run a fresh auth login just to switch.

  4. Prefer --format=json / tables; never dump credentials or ADC files into chat.

  5. For project create / undelete / credentials admin, use gcloud (or Console) — do not assume Composio covers Resource Manager admin.

Composio is not a substitute

Connected Google Workspace toolkits (Gmail, Drive, Calendar) do not give agents Cloud Resource Manager, API key minting, or project undelete. A Vision/list-projects connector (if connected) may enumerate projects but still cannot replace SDK login for admin work.

Composio setup

Composio MCP Setup.

Project naming (agents + humans)

GCP project IDs are immutable. Pick a beginner-friendly ID at create time (example: food-truck-nerdz). Display names can change later (example: “FoodTruckNerdz Platform”).

Do not overload a GitHub repo slug (example: ftn-app) as the only human name for the Cloud project — it confuses “mobile client repo” with “org GCP project”. Prefer a product/org-shaped ID when creating; rename display name freely.

Mental model

Google Cloud projects as OAuth boundaries.

Related source (file links, not line anchors)

| Resource | Link |

Harness boundary (what stays machine-local)

general/harness-boundary.md

Harness example stamps

harness.example.md

Bitwarden optional pattern (same persistence idea)

general/bitwarden-session-persist-optional.md

Console OAuth how-to (Client ID / consent — not gcloud)

Google Cloud OAuth for personal tools

Prefer blob/main/<path> (or Antora xref:) over #L… GitHub line links — paths stay stable; line numbers do not.

Checklist

  • gcloud auth list shows the intended account as active (*)

  • Multi-org: switch with config set account / named config — not re-login

  • Default project set only when safe (gcloud config set project …)

  • Org billing / parent folder attached for new projects

  • SA key path (if any) only in $MACHINE / Bitwarden — not User Rules

  • Agents report account email / project id — never credential files