The gcloud CLI uses global mutable state by default — one active configuration, one ADC file, shared across every terminal and every process. This creates credential isolation problems when working across multiple client projects. AI coding agents add a further constraint: they can’t perform interactive auth flows and can’t recover when tokens expire mid-task.
This hub collects the notes on the problem and its solutions.
The Core Problem
gcloud stores everything in ~/.config/gcloud/. Switching your active project in one terminal affects every other process reading from that directory. GCP Application Default Credentials explains the two separate auth systems (CLI credentials vs ADC) and why running one gcloud auth command doesn’t affect the other — a source of constant confusion.
The Four-Variable Solution
The fix is CLOUDSDK_CONFIG, an environment variable that redirects gcloud’s entire state store to a different directory per project. Two sessions using different CLOUDSDK_CONFIG paths cannot interfere with each other.
CLOUDSDK_CONFIG for Per-Project gcloud Isolation covers how the variable works and why you need four variables in total — two for the gcloud CLI and two for client libraries — to achieve full isolation.
direnv Multi-Client GCP Setup covers automating this with direnv so credentials load when you cd into a client directory and unload when you leave. This is the day-to-day workflow: five minutes of setup per client, then it’s ambient.
dbt Integration
dbt profiles.yml with env_var for Multi-Client GCP covers how env_var() interpolation in profiles.yml lets a single configuration file serve every client. dbt picks up the right project and credentials from environment variables set by direnv. The service-account method over oauth is the key choice here — it works in non-interactive environments including agent sessions.
AI Agent Constraints
GCP Auth Constraints for AI Coding Agents covers the specific behavior of Claude Code, Codex, and Cursor. The short version: Claude Code inherits shell environment variables (so direnv works), Codex runs in isolated containers with no ambient credentials, and Cursor’s agent terminal doesn’t inherit environment variables at all. Service account key files are the only auth method that works reliably across all of them.
The Credential Type Tradeoff
Service Account Key Files vs Impersonation Tokens covers the honest security calculus. Google recommends against key files. WIF doesn’t work for local development. Impersonation tokens are better security but break long-running agent sessions when they expire. For most consulting analytics work, service account key files with proper hygiene (one SA per client, minimum roles, 90-day rotation, chmod 600) are the pragmatic choice.
Related: IAM and Service Account Setup
BigQuery IAM Patterns — the least-privilege role model for BigQuery, including the data vs compute permission split.
dbt Service Account Setup for Multi-Project GCP Architectures — IAM setup when source data, transform compute, and infrastructure span separate GCP projects.
Security Posture for AI Agents — broader agent security, including credential scoping and the per-client isolation principle.