azctx

A CLI tool for managing Azure CLI contexts, modelled after kubectx. It maintains a composable config file that maps named contexts to a tenant, credential, and optional subscription. Running azctx use <name> switches the active context and syncs the Azure CLI session via az login and az account set.

Installation

Homebrew

brew install lvlcn-t/tap/azctx

go install

Requires Go 1.26+ and the GOEXPERIMENT=jsonv2 flag:

GOEXPERIMENT=jsonv2 go install github.com/lvlcn-t/azctx@latest

Manual

Download the archive for your platform from the releases page, extract the binary, and place it on your PATH.

Linux / macOS:

OS=$(uname -s)
ARCH=$(uname -m | sed 's/aarch64/arm64/')
curl -sL "https://github.com/lvlcn-t/azctx/releases/latest/download/azctx_${OS}_${ARCH}.tar.gz" \
  | tar -xz -C ~/.local/bin azctx
chmod +x ~/.local/bin/azctx

Windows (PowerShell):

$arch = if ($env:PROCESSOR_ARCHITECTURE -eq "AMD64") { "x86_64" } else { "arm64" }
$url = "https://github.com/lvlcn-t/azctx/releases/latest/download/azctx_Windows_$arch.zip"
Invoke-WebRequest $url -OutFile azctx.zip
Expand-Archive azctx.zip -DestinationPath .
Move-Item azctx.exe "$env:LOCALAPPDATA\Microsoft\WindowsApps\azctx.exe"

Container Image

Pre-built images are published to GitHub Container Registry:

docker pull ghcr.io/lvlcn-t/azctx:latest
docker run --rm \
  -v ~/.config/azctx:/home/nonroot/.config/azctx \
  -v ~/.azure:/home/nonroot/.azure \
  ghcr.io/lvlcn-t/azctx:latest use dev-west

Available tags: latest, vMAJOR, vMAJOR.MINOR, and full semver.

Quick start

Create a minimal config at ~/.config/azctx/config.yaml:

tenants:
  - name: dev
    id: 00000000-0000-0000-0000-000000000000

credentials:
  - name: personal
    credential:
      type: user
      azure: {}

contexts:
  - name: dev
    context:
      tenant: dev
      credential: personal

Then switch to it:

azctx use dev        # opens browser for login, sets subscription
azctx current        # prints "dev"
azctx list -o table  # show all contexts

Documentation

Guide	Description
Configuration	Config file format, credential types, Key Vault references
Workload Identity	OIDC federation — OAuth2 PKCE and file-based tokens
Usage	All commands, output formats, typical workflows
CLI Reference	Auto-generated command documentation
Contributing	Development setup, testing, PR guidelines

License

Copyright (c) 2024 lvlcn-t. Licensed under the MIT License.

Code of Conduct

This project has adopted the Contributor Covenant v2.1. All contributors must abide by the code of conduct.