gcloudenv

README

gcloudenv

Manage gcloud configurations the way nvm and rbenv manage language versions: switch the active profile per-shell, set a global default, and auto-switch based on a .gcloudenv file in your project.

gcloudenv is a thin layer over gcloud config configurations — gcloud remains the source of truth for accounts, projects, and credentials. gcloudenv just makes switching between them ergonomic and shell-aware.

How it works

A child process can't change its parent shell's environment, so gcloudenv ships a small shell function (the shim) that evals the export lines the binary prints. Switching a profile sets CLOUDSDK_ACTIVE_CONFIG_NAME, which gcloud reads to pick the active configuration for that shell — no global state touched.

Install

With Go:

go install github.com/figverse/gcloudenv@latest

Or grab a prebuilt binary for your platform from the releases page.

Then add the integration to your shell rc:

# ~/.zshrc or ~/.bashrc
eval "$(gcloudenv init zsh)"

# fish: ~/.config/fish/config.fish
gcloudenv init fish | source

Usage

gcloudenv list                 # all profiles; * marks the active one
gcloudenv use staging          # switch this shell to "staging"
gcloudenv use prod --global    # change gcloud's global default
gcloudenv current              # show active profile + account/project + source
gcloudenv create staging \     # create a profile and seed it
    --account me@x.com --project my-stg
gcloudenv local staging        # write .gcloudenv so this dir auto-switches

Directory auto-switch

gcloudenv local <profile> writes a .gcloudenv file (like .nvmrc). With the shim installed, cd-ing into that directory (or any child) switches the shell to that profile automatically. Resolution precedence, highest first:

1. explicit argument (gcloudenv use X)
2. nearest .gcloudenv walking up from the cwd
3. $CLOUDSDK_ACTIVE_CONFIG_NAME already in the environment
4. gcloud's own global default

Known limitation

gcloud configurations share a single application-default-credentials (ADC) file — switching configurations does not isolate ADC. If you need per-profile ADC for local development against multiple identities, that requires the isolated-CLOUDSDK_CONFIG model, which is not yet implemented. The gcloud interop is isolated behind internal/gcloud to make adding it straightforward.

Develop

make build      # build ./gcloudenv
make test       # run unit tests (no real gcloud needed — uses a stub)
make check      # fmt-check + vet + lint + test, as CI runs them

Tests run against a stub gcloud, so they're safe to run anywhere.

Contributing

Contributions are welcome! See CONTRIBUTING.md for setup, conventions, and the PR checklist, and please follow our Code of Conduct. Security issues should be reported per SECURITY.md.

License

MIT © Figverse

Documentation

Overview

Command gcloudenv manages gcloud configurations the way nvm/rbenv manage language versions: switch the active profile per-shell, set a global default, and auto-switch based on a .gcloudenv file in the working directory.