DEV Community

Cover image for Why Your Code May Use a Different GCP Project Than gcloud
Uri Berman
Uri Berman

Posted on

Why Your Code May Use a Different GCP Project Than gcloud

#googlecloud #devops #opensource #cli

Most Google Cloud developers assume there is one active cloud context.

There isn't.

Your gcloud CLI can point to one project while Python, Terraform, Node.js, or an AI coding agent uses Application Default Credentials associated with another.

That is the problem I built gcpctx to solve.

The dangerous mismatch

Imagine this local environment:

Component Effective project
gcloud CLI my-dev-project
Application Default Credentials company-production
Terraform provider company-production
Python SDK company-production

You run:

gcloud config set project my-dev-project
Enter fullscreen mode Exit fullscreen mode

The CLI now says development.

But changing a gcloud configuration does not automatically replace the Application Default Credentials used by client libraries and other tools.

The command may be correct.

The inherited cloud context may not be.

The workflow I wanted

I wanted to switch all relevant Google Cloud state together:

  • account
  • project
  • named gcloud configuration
  • Application Default Credentials
  • ADC quota project
  • shell environment
  • repository context

I also wanted a visible prompt and an explicit assertion before running deployment commands.

So I built gcpctx.

Install gcpctx

Install it from npm:

npm install -g gcpctx
Enter fullscreen mode Exit fullscreen mode

Initialize the shell integration:

gcpctx shell-setup
Enter fullscreen mode Exit fullscreen mode

Then bootstrap the first context:

gcpctx bootstrap
Enter fullscreen mode Exit fullscreen mode

The bootstrap command guides you through creating an initial Google Cloud context from your current environment.

Switch the full GCP context

Activate a named context:

gcpctx use prod
Enter fullscreen mode Exit fullscreen mode

After activation, the shell prompt can show the active context and project:

(gcp:prod:your-project)
Enter fullscreen mode Exit fullscreen mode

This provides an immediate visual warning that the current terminal is operating against production.

The important difference is that gcpctx use aligns the gcloud configuration and the per-context ADC environment instead of switching only the CLI project.

Assert before running anything important

A visible prompt helps, but scripts should not rely on a human noticing it.

Verify the expected project explicitly:

gcpctx assert --project your-project
Enter fullscreen mode Exit fullscreen mode

Verify both the context and project:

gcpctx assert \
  --context prod \
  --project your-project
Enter fullscreen mode Exit fullscreen mode

The command exits with a nonzero status when the active context does not match.

That makes it useful in shell scripts, deployment scripts, CI preparation, and agent workflows.

gcpctx assert --context prod --project your-project &&
terraform plan
Enter fullscreen mode Exit fullscreen mode

Execute a command inside a required context

For a stronger execution pattern, use gcpctx exec:

gcpctx exec \
  --require-context prod \
  -- terraform plan
Enter fullscreen mode Exit fullscreen mode

For a production deployment:

gcpctx exec \
  --require-context prod \
  -- terraform apply
Enter fullscreen mode Exit fullscreen mode

Protect production contexts

Mark a sensitive context as protected:

gcpctx protect prod
Enter fullscreen mode Exit fullscreen mode

Protected contexts can display stronger warnings and require explicit authorization in sensitive workflows.

This does not replace IAM, approvals, or separate production credentials.

It adds another local safety boundary.

Diagnose the current environment

Run:

gcpctx doctor
Enter fullscreen mode Exit fullscreen mode

The doctor command checks the local context configuration, including consistency between the active project, account, credentials, quota project, shell integration, and managed files.

A typical workflow becomes:

gcpctx use prod
gcpctx assert --project your-project
gcpctx doctor
Enter fullscreen mode Exit fullscreen mode

Then run the intended command:

gcpctx exec \
  --require-context prod \
  -- terraform plan
Enter fullscreen mode Exit fullscreen mode

Override the project when activating

A context can also be activated with a different project:

gcpctx use prod --project another-project-id
Enter fullscreen mode Exit fullscreen mode

This is useful when the credential identity remains the same but the target project changes.

It also keeps the override visible in the command rather than hiding it in an unrelated environment variable.

Create or refresh credentials for a context

Use:

gcpctx login prod
Enter fullscreen mode Exit fullscreen mode

This associates the authentication flow with the named context instead of treating ADC as one invisible global state.

Credential contents remain local.

gcpctx may display credential paths for diagnostics, but it does not print credential bodies.

Repository-specific activation

A repository can include a safe .gcpctx marker:

{
  "name": "dev",
  "project": "example-dev-123456"
}
Enter fullscreen mode Exit fullscreen mode

This makes the expected environment part of the repository workflow.

A developer moving between several customer or product repositories no longer needs to remember the correct project for each directory.

The repository declares the expected context.

The marker contains context metadata, not credential bodies.

Why gcloud configurations are not enough

Named gcloud configurations are useful, but they primarily affect the CLI.

Mechanism Affects gcloud CLI Affects client libraries and ADC
gcloud config configurations activate Yes No
gcloud auth application-default login No Yes, through the global ADC file
gcpctx use Yes Yes, through per-context ADC and environment

gcpctx does not replace gcloud.

It coordinates the independent context mechanisms around it.

A complete example

Here is the full workflow:

# Install
npm install -g gcpctx

# Configure shell integration
gcpctx shell-setup

# Create the initial context
gcpctx bootstrap

# Authenticate a production context
gcpctx login prod

# Protect it
gcpctx protect prod

# Activate it
gcpctx use prod

# Verify it
gcpctx assert \
  --context prod \
  --project your-project

# Diagnose configuration
gcpctx doctor

# Execute safely inside the expected context
gcpctx exec \
  --require-context prod \
  -- terraform plan
Enter fullscreen mode Exit fullscreen mode

The shell prompt provides human visibility.

assert provides machine-verifiable context.

exec --require-context binds execution to an explicit context requirement.

What gcpctx does not do

gcpctx does not make every cloud command safe.

It does not replace:

  • IAM least privilege
  • separate production identities
  • deployment approvals
  • organization policies
  • protected CI environments
  • Terraform safeguards
  • audit logging
  • backups and recovery controls

Its purpose is narrower:

Make the effective local Google Cloud context explicit, consistent, and testable.

Platform support

gcpctx currently supports:

Platform Support
macOS Native Bash CLI with Bash and Zsh hooks
Linux Native Bash CLI with Bash and Zsh hooks
Windows npm installation through Git Bash or WSL
PowerShell Wrapper available
Windows CMD Not supported

Try it

Install from npm:

npm install -g gcpctx
Enter fullscreen mode Exit fullscreen mode

GitHub:

https://github.com/UriBer/gcpctx

npm:

https://www.npmjs.com/package/gcpctx

The project is open source under Apache 2.0.

I am especially interested in feedback about:

  • multi-account GCP workflows
  • Terraform usage
  • production-context protection
  • PowerShell support
  • AI coding-agent integration
  • context switching across customer environments

How do you currently ensure that gcloud, ADC, Terraform, and your application SDKs are all using the intended Google Cloud project?

Top comments (0)