azcli-profile-mgmt (azp)

Manage multiple Azure CLI profiles — fully isolated logins and configurations — by pointing the AZURE_CONFIG_DIR environment variable at per-profile directories. Works in both Bash and PowerShell.

Why

The Azure CLI keeps all of its state (auth tokens, azureProfile.json, configured defaults, installed extensions, telemetry) under a single directory, AZURE_CONFIG_DIR (default ~/.azure). By switching that variable you get completely separate profiles — ideal for juggling multiple tenants, e.g. commercial vs. US Gov vs. a customer subscription, without repeated az logout / az login cycles.

How it works

All profiles live under one root, ~/.azure_profiles/ by default. Each subdirectory name is a profile name — the filesystem is the single source of truth, so there is no separate registry to keep in sync.

~/.azure_profiles/
├── work/      # AZURE_CONFIG_DIR when profile "work" is active
├── gov/
└── customer/

azp use <name> exports AZURE_CONFIG_DIR in your current shell, so it is implemented as a sourced shell function (Bash) / module (PowerShell) rather than a standalone binary.

Commands

Command	Description
azp list	List profiles, marking the active one with *
azp use <name>	Activate a profile in the current shell
azp new <name> [--login/-Login]	Create a profile (optionally run az login)
azp copy <src> <dest>	Clone a profile by copying its config dir
azp rename <old> <new>	Rename a profile
azp remove <name>	Delete a profile (asks for confirmation)
azp current	Show the active profile + az account show summary
azp which	Print the active AZURE_CONFIG_DIR path
azp help	Show usage

Install

Bash

./install.sh          # appends a source line to ~/.bashrc
source ~/.bashrc      # or open a new shell

PowerShell

./install.ps1         # installs to your user PSModulePath
azp help              # PowerShell auto-loads the module

This also works in non-interactive hosts that start PowerShell with -NoProfile, including GitHub Copilot CLI. To retain the previous profile-based installation behavior, pass a profile path explicitly:

./install.ps1 -ProfilePath $PROFILE
. $PROFILE

Both installers are idempotent. You can also wire them up manually:

source /path/to/bash/azp.sh

Import-Module /path/to/pwsh/azp.psm1

Usage examples

azp new work --login        # create "work" and log in to it
azp new gov                 # create an empty "gov" profile
azp copy work customer      # clone "work" as a starting point
azp use gov                 # switch this shell to the gov profile
az login                    # tokens land in ~/.azure_profiles/gov
azp list                    # * gov / work / customer
azp current                 # show active profile + signed-in account

Per-profile shell history

By default, azp use also isolates your shell command history per profile, so you don't see commands from other profiles:

• Bash — sets HISTFILE to <profile>/.bash_history and flushes/reloads history in place, so isolation applies even within a live session.
• PowerShell — sets the PSReadLine HistorySavePath to <profile>/history.txt. New commands are saved per-profile. Note: lines already loaded into memory before your first azp use remain visible for the current session (a PSReadLine limitation).

Disable this behavior by setting AZ_PROFILES_ISOLATE_HISTORY=0.

GitHub Copilot CLI instructions

This repo ships a ready-made instruction file, copilot/azp.instructions.md, that teaches the GitHub Copilot CLI how to pick the right Azure CLI profile with azp before running az commands.

Copilot CLI automatically reads instructions from several locations. Add the file to whichever scope you want:

Global (applies to every session on this machine):

mkdir -p ~/.copilot/instructions
cp copilot/azp.instructions.md ~/.copilot/instructions/azp.instructions.md

Per repository (checked in for your team):

mkdir -p .github/instructions
cp /path/to/azcli-profile-mgmt/copilot/azp.instructions.md \
   .github/instructions/azp.instructions.md

You can also append its contents to an existing AGENTS.md, .github/copilot-instructions.md, or ~/.copilot/copilot-instructions.md, or point Copilot at an extra directory via the COPILOT_CUSTOM_INSTRUCTIONS_DIRS environment variable. Likely ~/.copilto/instructions is already added as a custom instructions directory and the file can be added here.

Verify Copilot loaded it by running /instructions (or /env) inside the Copilot CLI — the azp instructions should be listed. After that, prompts like "switch to my gov profile and show the account" or "list my Azure profiles" will drive azp correctly.

Configuration

Variable	Default	Purpose
AZ_PROFILES_HOME	~/.azure_profiles	Root directory for all profiles
AZ_PROFILES_ISOLATE_HISTORY	1	Set 0 to disable per-profile history

Notes & caveats

• azp copy performs a raw copy of the config dir, including cached tokens, so the clone starts logged in as the same identity. Re-run az login (or az account set) in the new profile if you want a different one.
• The default ~/.azure directory is never touched; profiles are self-contained under AZ_PROFILES_HOME. Profile directories are created with 700 permissions.
• Profile names must match ^[A-Za-z0-9._-]+$.

Tests

• Bash (bats): tests/run-bash.sh or bats tests/bash/azp.bats
• PowerShell (Pester 5+): Invoke-Pester tests/pwsh

Repository layout

bash/azp.sh              Bash function + tab completion
pwsh/azp.psm1            PowerShell module + argument completer
pwsh/azp.psd1            PowerShell module manifest
install.sh               Bash installer (~/.bashrc)
install.ps1              PowerShell module installer (PSModulePath)
copilot/azp.instructions.md  Copilot CLI custom instructions for azp
tests/bash/azp.bats      Bash test suite
tests/pwsh/azp.Tests.ps1 PowerShell test suite
tests/pwsh/install.Tests.ps1 PowerShell installer test suite