How to manage Azure subscriptions with the Azure CLI

The Azure CLI helps you manage your Azure subscription, create management groups, and lock subscriptions.You might have multiple subscriptions within Azure. You can be part of more than one organization or your organization might divide access to certain resources across groupings. The Azure CLI supports selecting a subscription both globally and per command.

For detailed information on subscriptions, billing, and cost management, see the billing and cost management documentation.

Terminology

A tenant is an instance of Microsoft Entra ID in which information about a single organization resides. A multi-tenant organization is an organization that has more than one instance of Microsoft Entra ID. A tenant has one or more subscriptions and users.

Users are those accounts that sign in to Azure to create, manage, and use resources. A user may have access to multiple tenants and subscriptions.

Subscriptions are the agreements with Microsoft to use cloud services, including Azure. Every resource is associated with a subscription. Subscriptions contain resource groups.

An Azure resource group is a container that holds related resources for an Azure solution. To learn how to manage resource groups within your subscription, see How to manage Azure resource groups with the Azure CLI

Get the active tenant

Use az account tenant list or az account show to get the active tenant ID.

az account tenant list

az account show

Change the active tenant

To switch tenants, you have two options.

• Change the active subscription.

• Sign in as a user within the desired tenant. Use az login to change the active tenant and update the subscription list to which you belong.

  # sign in as a different user
  az login --user <myAlias@myCompany.com> --password <myPassword>
  
  # sign in with a different tenant
  az login --tenant <myTenantID>
  

  If your organization requires multi-factor authentication, you may receive this error when using az login --user:

  Due to a configuration change made by your administrator, or because you moved to a new location, you must use multi-factor authentication to access...
  

  Using the alternative az login --tenant command prompts you to open an HTTPS page and enter the code provided. You can then use multi-factor authentication and successfully sign in. To learn more about sign in options with the azure CLI, see Sign in with the Azure CLI.

Get subscription information

Most Azure CLI commands act within a subscription. You can specify which subscription to work in by using the --subscription parameter in your command. If you don't specify a subscription, the command uses your current, active subscription.

To see the subscription you're currently using or to get a list of available subscriptions, run the az account show or az account list command. Go to Learn to use Bash with the Azure CLI to see more examples of ways to use these commands.

Here are examples showing how to get subscription information:

# get the current default subscription using show
az account show --output table

# get the current default subscription using list
az account list --query "[?isDefault]"

# get a subscription that contains search words or phrases
az account list --query "[?contains(name,'search phrase')].{SubscriptionName:name, SubscriptionID:id, TenantID:tenantId}" --output table

You can also store subscription information in a variable for use within a script.

Bash

# store the default subscription in a variable
subscriptionId="$(az account list --query "[?isDefault].id" --output tsv)"
echo $subscriptionId

# store a subscription of certain name in a variable
subscriptionId="$(az account list --query "[?name=='my case sensitive subscription full name'].id" --output tsv)"
echo $subscriptionId

PowerShell

# store the default subscription in a variable
$subscriptionId = az account list --query "[?isDefault].id" --output tsv
Write-Host $subscriptionId

# store a subscription of certain name in a variable
$subscriptionId = az account list --query "[?name=='my case sensitive subscription full name'].id" --output tsv
Write-Host $subscriptionId

Tip

The --output parameter is a global parameter, available for all commands. The table value presents output in a friendly format. For more information, see Output formats for Azure CLI commands.

Change the active subscription

Azure subscriptions have both a name and an ID. You can switch to a different subscription using az account set specifying the desired subscription ID or name.

# change the active subscription using the subscription name
az account set --subscription "My Demos"

# change the active subscription using the subscription ID
az account set --subscription "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

You can also change your subscription using a variable. Here is an example:

Bash

# change the active subscription using a variable
subscriptionId="$(az account list --query "[?name=='my case sensitive subscription full name'].id" --output tsv)"
az account set --subscription $subscriptionId

PowerShell

# change the active subscription using a variable
$subscriptionId = az account list --query "[?name=='my case sensitive subscription full name'].id" -o tsv
az account set --subscription $subscriptionId

If you change to a subscription that is in a different tenant, you will also be changing the active tenant. To learn how to add a new subscription to your Microsoft Entra tenant, see Associate or add an Azure subscription to your Microsoft Entra tenant.

If you received a "The subscription of ... doesn't exist..." error, see Troubleshooting for possible solutions.

Clear your subscription cache

To update your subscription list, use the az account clear command. You will need to sign in again to see an updated list.

az account clear

az login

Clearing your subscription cache is not technically the same process as logging out of Azure. However, when you clear your subscription cache, you cannot run Azure CLI commands, including az account set, until you sign in again.

Create Azure management groups

Azure management groups contain subscriptions. Management groups provide a way to manage access, policies, and compliance for those subscriptions. For more information, see What are Azure management groups.

Use the az account management-group commands to create and manage Azure Management Groups.

You can create a management group for several of your subscriptions by using the az account management-group create command:

az account management-group create --name Contoso01

To see all your management groups, use the az account management-group list command:

az account management-group list

Add subscriptions to your new group by using the az account management-group subscription add command:

az account management-group subscription add --name Contoso01 --subscription "My Demos"
az account management-group subscription add --name Contoso01 --subscription "My Second Demos"

To remove a subscription, use the az account management-group subscription remove command:

az account management-group subscription remove --name Contoso01 --subscription "My Demos"

To remove a management group, run the az account management-group delete command:

az account management-group delete --name Contoso01

Removing a subscription or deleting a management group doesn't delete or deactivate a subscription.

Set an Azure subscription lock

As an administrator, you may need to lock a subscription to prevent users from deleting or modifying it. For more information, see Lock resources to prevent unexpected changes.

In Azure CLI, use the az account lock commands. For instance, the az account lock create command can prevent users from deleting a subscription:

az account lock create --name "Cannot delete subscription" --lock-type CanNotDelete

Note

You need to have contributor permissions on a subscription to create or change locks.

To see the current locks on your subscription, use the az account lock list command:

az account lock list --output table

If you make an account read-only, the result resembles assigning permissions of the Reader role to all users. To learn about setting permissions for individual users and roles, see Add or remove Azure role assignments using Azure CLI.

To see details for a lock, use the az account lock show command:

az account lock show --name "Cannot delete subscription"

You can remove a lock by using the az account lock delete command:

az account lock delete --name "Cannot delete subscription"

Troubleshooting

The subscription doesn't exist

In addition to a typographical error, you can receive this error when there is a permissions timing issue. For example, if you have been given permissions to a new subscriptions while your current terminal window is open, this error can occur. The solution is to either close and reopen your terminal window, or use az logout then az login to refresh your available subscriptions list.

Here is a script to help you find and change a subscription.

# See what subscription you are currently using.
az account show

# Get a list of available subscriptions.
az account list --output table

# If the subscription you are seeking is not in the list
#   close and reopen your terminal window,
#   or logout and then sign in again.
az logout
az login

# You can also clear your cache to refresh the
#    available subscription list
az account clear
az login

# Did your available subscription list change?
az account list --output table

# If the subscription you are seeking is still not in the list,
#    contact your system administrator. You cannot change your
#    subscription to an ID that is not in the list.

# If the subscription you are seeking is now in the list,
#   change your subscription.
az account set --subscription 00000000-0000-0000-0000-00000000000

See also

• Associate or add an Azure subscription to your Microsoft Entra tenant
• Manage Azure resource groups