It is Tuesday morning. Your account reaches 14 tenants. Three of them want a fresh MFA prompt before you have finished your coffee, and in a second terminal a coding agent has just run az account set to „fix“ a failing command. Your Terraform plan in the first terminal now targets a different subscription than it did five minutes ago, and nothing told you.
The Azure CLI has become much better at sign-in, so the question is fair: do we still need a context switcher? Our answer is yes, because the hard part of the day is no longer the first login. It is everything after it. That is why we rebuilt azctx for the 2026.11 release around pipelines, AI agents, many tenants, and mandatory MFA.
Where the Azure CLI stops
Since version 2.61, az login shows a subscription picker right after sign-in, Windows signs in through the WAM broker by default, and macOS has had an opt-in preview broker since 2.91.0. For one tenant with a handful of subscriptions, that is enough.
The gaps show up later in the day. The active subscription is global state in AZURE_CONFIG_DIR: one az account set in one window changes the target for every terminal and every process, and there is no per-process override. az account set takes only an exact name or ID, so prod in three tenants means copying GUIDs. And with mandatory MFA now enforced for the Azure CLI, a plain az login prints one warning per tenant that needs MFA and leaves the retries to you.
azctx follows the Azure CLI and never shadows it. It switches through az account set, signs in through az login, never touches the MSAL token cache, and never writes Azure configuration files on its own.
One context per command, not per machine
Terraform, azd and the Azure SDKs read the target from environment variables, and since the azurerm provider 4.0, Terraform requires the subscription ID in the provider block or in ARM_SUBSCRIPTION_ID. azctx env prints the four variables these tools read, for bash, zsh, fish or PowerShell:
$ azctx env contoso-dev --shell zsh
export ARM_SUBSCRIPTION_ID='22222222-2222-2222-2222-222222222222'
export ARM_TENANT_ID='aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'
export AZURE_SUBSCRIPTION_ID='22222222-2222-2222-2222-222222222222'
export AZURE_TENANT_ID='aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'
azctx exec goes one step further and runs a single command with that context, without touching the active subscription. The other terminal keeps its target:
azctx exec contoso-dev -- terraform plan
For repositories that should only ever touch one subscription, a committed .azctx.yaml states the expectation:
version: 1
tenant: aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa
subscription: 11111111-1111-1111-1111-111111111111
azctx guard compares the active subscription with the nearest .azctx.yaml and exits with code 4 on a mismatch. azctx -c warns as soon as you look at the current context. azctx never switches based on this file, because a cloned repository is untrusted input. It only checks.
In pipelines, azctx stays out of authentication. azure/login with OIDC or an Azure DevOps workload identity service connection signs in, then azctx checks the context and exports it for later steps:
- name: Check and export the Azure context
run: |
azctx guard --no-input -o json &&
azctx env --format github
--format azure-devops prints ##vso[task.setvariable] lines instead. If a job signs in through azctx, managed identities and service principals pass straight through to az login, for example with azctx login -- --identity, and azctx skips the MFA retries for them.
Built for AI agents
Agents make the global context problem worse. When an agent hits a „subscription not found“ error, az account set is the obvious fix, and the agent runs it without knowing that it just changed the target for every terminal you have open.
The release ships an Agent Skill in the open Agent Skills format, so it works with any coding agent that supports skills. It tells the agent to read the context with azctx -c -o json and azctx list -o json, never to change the active subscription on its own, to pass --subscription to az and use azctx exec for Terraform and azd, to run azctx guard before changes and stop on exit code 4, and to leave sign-in and protected subscriptions to the human.
The CLI contract is built for machines. JSON output carries schemaVersion: 1, errors are one JSON object on stderr with a stable code, and exit codes mean the same thing everywhere: 0 success, 1 error, 2 no or ambiguous match, 3 sign-in failure, 4 guard mismatch, 130 canceled. --no-input turns every prompt into a predictable failure instead of a hang.
Instructions can be ignored, so we add enforcement on top for agents that support plugins and hooks, such as Claude Code and GitHub Copilot CLI. The azctx repository doubles as a plugin marketplace. In Claude Code, for example:
/plugin marketplace add whiteducksoftware/azctx
/plugin install azctx@azctx
The plugin adds a pre-tool-use hook that runs azctx guard before every Bash command starting with az, azd, terraform or bicep. On a mismatch, the command never runs and the agent gets a one-line reason. Without a .azctx.yaml in the repository or without azctx on the PATH, the hook lets the command through with a notice, so the check is opt-in per repository. For the review afterwards, azctx history shows every switch with its timestamp and whether a person or a script made it.
We want to be precise about the limits. The guard, the skill and protected subscriptions reduce mistakes, but they are not a security boundary. The hook does not see wrapped commands such as bash -c or azctx exec, and agents without hook support get the skill without enforcement. Access control stays with Azure RBAC, PIM and Conditional Access.
Many tenants, one MFA round trip
azctx login runs one ordinary az login and classifies the per-tenant failures by their documented AADSTS error codes. 50076 (MFA required) and 50079 (MFA registration required) are worth one targeted retry. 53003 means Conditional Access blocked the token, so azctx explains it instead of retrying. Then it asks once:
$ azctx login
Logging in... Please check your browser for the login prompt.
TENANT ID NAME CODE DETAIL
bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb "Fabrikam" AADSTS50076 MFA required
cccccccc-cccc-cccc-cccc-cccccccccccc "Northwind" AADSTS50076 MFA required
dddddddd-dddd-dddd-dddd-dddddddddddd "Tailspin" AADSTS53003 Blocked by Conditional Access; retry will not help. Contact your tenant administrator.
Sign in to these 2 tenants now? [Y/n]
Signing in to tenant bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb.
Signing in to tenant cccccccc-cccc-cccc-cccc-cccccccccccc.
Warning: Fetched 3 tenants and 5 subscriptions; sign-in incomplete.
That is one confirmation and two targeted sign-ins, plus a clear note on the tenant that needs its administrator. Because one tenant is still blocked, the run ends with exit code 3. azctx login --all-tenants discovers every tenant and signs in to each one. Without a terminal or with --no-input, azctx lists the failed tenants and exits with the same code instead of waiting for input that never comes.
Broker sign-in
A broker is the operating system’s own sign-in component: Web Account Manager (WAM) on Windows and Intune Company Portal with the Microsoft Enterprise SSO plug-in on macOS. Instead of a browser session, the Azure CLI gets its tokens from the device itself. That is what most enterprises need: Conditional Access policies that require a managed or compliant device can be met; sign-in works with Windows Hello, passkeys and the existing device account, and people see fewer prompts.
Switching to broker sign-in means clearing the accounts, changing the setting, and signing in again. azctx auth broker enable does all three after one confirmation, on Windows and on macOS, where it warns that the broker is still a preview that needs an enrolled device. In SSH sessions, Codespaces, and Dev Containers, where no broker is available, azctx suggests --use-device-code before the login starts.
Switching that fits how you work
Run azctx for a fuzzy picker with subscription, ID and tenant columns, or skip the picker:
$ azctx fabrikam/prod
✓ Switched to fabrikam-prod (33333333-3333-3333-3333-333333333333) in tenant Fabrikam (bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb)
$ azctx -
✓ Switched to contoso-prod (11111111-1111-1111-1111-111111111111) in tenant Contoso (aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa)
tenant/subscription scopes a query to one tenant by name, domain or ID, and azctx - swaps back to the previous subscription. Short names take one command:
azctx alias set prod 11111111-1111-1111-1111-111111111111
azctx prod
Aliases live in a strict, versioned config file together with pinned, hidden, and protected subscriptions, and azctx config path shows where it is. Pinned subscriptions come first in the picker, followed by the ones you used most recently. Hidden subscriptions disappear from the picker, the list and completion until you pass --all. Protected subscriptions, typically production, ask for confirmation before every switch and need an explicit --yes in scripts.
With dozens of tenants, azctx tenant picks the tenant first, and Azure Lighthouse delegations are marked. To keep the context in view, azctx -c -o name prints only the subscription name for a Starship, oh-my-posh or Powerlevel10k prompt segment. picker: fzf is there for kubectx users, and shell completion works for bash, zsh, fish and PowerShell.
azctx and the Azure CLI side by side
| Task | Azure CLI | azctx 2026.11 |
|---|---|---|
| Terraform and azd context | 🔴 Export variables by hand | 🟢 azctx env, azctx exec |
| Wrong subscription prevention | 🔴 Not checked | 🟢 .azctx.yaml, azctx guard, protected subscriptions |
| Pipelines | 🟡 OIDC sign-in, no context check | 🟢 OIDC sign-in plus azctx guard and pipeline exports |
| AI agents | 🔴 Shared active subscription across terminals | 🟢 Agent Skill, JSON contract, guard hook, history |
| Many tenants with MFA | 🟡 One warning per tenant, manual retries | 🟢 One confirmation, targeted retries |
| Broker sign-in | 🟡 Three manual steps | 🟢 azctx auth broker enable |
| Switching | 🟡 Picker at login, exact name or GUID | 🟢 Picker at any time, tenant/subscription, aliases, azctx - |
Our recommendation
- One tenant, a few subscriptions: The Azure CLI is enough.
- Terraform or azd against several subscriptions: Use
azctx execinstead of switching. - AI agents in your repositories: Commit a
.azctx.yaml, install the Agent Skill and enable the guard hook where your agent supports plugins. - Pipelines: Keep OIDC sign-in and add
azctx guardbefore the first deployment step. - Many tenants with MFA: Start with
azctx loginandazctx tenant.
Try it
Install azctx 2026.11 with brew install --cask whiteducksoftware/tap/azctx, winget install --id whiteducksoftware.azctx (currently in review – available soon), or take the release binaries from GitHub. Coming from an older version? The upgrade guide lists the breaking changes. Issues and pull requests are welcome.
Many tenants, mandatory MFA, and AI agents are a platform problem, not only a tooling problem. Our Platform Engineering team helps build Azure platforms where engineers and agents work safely across tenants. Talk to us.






