gctx

README

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

# Account 1 - automatically authenticates and saves credentials
gctx create work my-work-project
# Opens browser for auth + ADC, auto-saves

# Account 2
gctx create personal my-personal-project

# Account 3
gctx create client client-project

Note: As of v0.5.0, gctx create always auto-authenticates. The --auto-save flag has been removed for simplicity.

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.

   Cross-platform support: Automatically detects and uses the appropriate shell:

   • Windows: PowerShell Core → Windows PowerShell → cmd.exe
   • Unix/Linux/Mac: Uses $SHELL environment variable or /bin/sh

   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)$ '

Updating gctx

Homebrew (macOS/Linux)

brew update
brew upgrade gctx

Scoop (Windows)

scoop update
scoop update gctx

Manual Update

1. Download the latest binary from Releases
2. Replace your existing gctx binary
3. Verify the update:

   gctx version
   

From Source

go install github.com/k0wl0n/gctx@latest

What's New in v0.5.0

🎉 Major Features

• Auto-authentication by default: gctx create now always authenticates automatically (no --auto-save flag needed)
• Full Windows support: Shell command now works on Windows with PowerShell/cmd.exe detection

🐛 Bug Fixes

• Login without ADC: gctx login now works even if no ADC credentials are saved
• Switch with warnings: gctx switch handles missing ADC gracefully with helpful warnings instead of failing
• Active account display: gctx active now correctly shows the active account (no more "unknown")

📝 Improvements

• Cross-platform shell detection (PowerShell Core, Windows PowerShell, cmd.exe, bash, zsh, sh)
• Better error messages and user guidance
• Cleaner codebase with simplified function signatures
• Removed dead code paths