GCloud Multi-Account Manager

A Go-based CLI tool using Cobra to manage multiple GCP accounts with seamless switching of both gcloud configurations and ADC (Application Default Credentials).

Documentation

Full documentation is available at gctx.readthedocs.io.

Project Overview

Problem: Managing multiple GCP accounts requires constant re-authentication when switching between accounts, especially for ADC credentials which are stored in a single file.

Solution: gctx saves separate ADC credentials for each account and swaps them automatically when switching, eliminating the need for repeated gcloud auth application-default login.

Installation

Homebrew (macOS/Linux)

brew tap k0wl0n/tap
brew install gctx

Scoop (Windows)

scoop bucket add k0wl0n https://github.com/k0wl0n/scoop-bucket
scoop install gctx

Manual

Download the latest binary from the Releases page and add it to your PATH.

From Source

go install github.com/k0wl0n/gctx@latest

Development

Prerequisites

This project uses mise to manage dependencies (Go, Task, gcloud, GoReleaser).

# Install mise (if not installed)
curl https://mise.run | sh

# Install dependencies
mise install

This project uses Task (Taskfile) for build and management commands.

Build & Install

# Build binary
task build

# Install to /usr/local/bin (requires sudo)
task install

# Run tests
task test

# Clean artifacts
task clean

Configuration Management

# Show current config
task config:show

# Reset all configuration (DANGER)
task config:clean

Demo / Testing Flow

# Create a demo account
task demo:create

# Switch to demo account
task demo:switch

# Re-authenticate demo account
task demo:login

# Delete demo account
task demo:delete

Usage

Initial Setup (Auto-save)

# Account 1
gctx create work my-work-project --auto-save
# Opens browser for auth + ADC, auto-saves

# Account 2
gctx create personal my-personal-project --auto-save

# Account 3
gctx create client client-project --auto-save

Initial Setup (Manual)

gctx create work my-work-project
gcloud auth login
gcloud auth application-default login
gctx save work

Daily Usage

# Switch accounts (instant, no re-auth!)
gctx switch work
gctx switch personal

# Re-authenticate an existing account
gctx login work
# This will run gcloud auth login and update saved ADC credentials

# Check current account
gctx active
# Output: Active account: work

# List all accounts
gctx list
# Output:
#   work (my-work-project) [user@work.com] ← active
#   personal (my-personal-project) [user@gmail.com]
#   client (client-project) [user@client.com]

# Run command with specific account (Isolated!)
# This runs the command without changing your global active account
gctx run personal compute instances list

# Start an isolated shell session
# All gcloud commands in this shell will use 'personal' account
gctx shell personal
# (Type 'exit' to return to normal)

# Show account details
gctx info work

# Delete account
gctx delete old-account --gcloud-config

Isolated Sessions

gctx provides two ways to use an account without switching your global configuration:

1. Single Command (gctx run): Runs a single gcloud command with the specified account.

   gctx run my-account storage buckets list

2. Shell Session (gctx shell): Starts a new shell where the specified account is active. This does not affect other terminals or your global configuration.

   gctx shell my-account
   
   # Now you are in an isolated session
   gcloud auth list  # shows my-account
   
   exit # Return to previous context

Shell Completion

Bash

gctx completion bash > /usr/local/etc/bash_completion.d/gctx

Zsh

gctx completion zsh > "${fpath[1]}/_gctx"

Fish

gctx completion fish > ~/.config/fish/completions/gctx.fish

Prompt Integration

Add to .bashrc or .zshrc:

# Show active gctx account in prompt
gctx_prompt() {
    local active=$(gctx active 2>/dev/null | cut -d: -f2 | tr -d ' ')
    if [ -n "$active" ]; then
        echo "($active) "
    fi
}

PS1='$(gctx_prompt)$ '