Why Your Code May Use a Different GCP Project Than gcloud

Uri Berman — Sat, 01 Aug 2026 08:46:06 +0000

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

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

Initialize the shell integration:

gcpctx shell-setup

Then bootstrap the first context:

gcpctx bootstrap

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

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

(gcp:prod:your-project)

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

Verify both the context and project:

gcpctx assert \
  --context prod \
  --project your-project

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

Execute a command inside a required context

For a stronger execution pattern, use gcpctx exec:

gcpctx exec \
  --require-context prod \
  -- terraform plan

For a production deployment:

gcpctx exec \
  --require-context prod \
  -- terraform apply

Protect production contexts

Mark a sensitive context as protected:

gcpctx protect prod

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

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

Then run the intended command:

gcpctx exec \
  --require-context prod \
  -- terraform plan

Override the project when activating

A context can also be activated with a different project:

gcpctx use prod --project another-project-id

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

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"
}

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

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

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?

DEV Community: Uri Berman