Using the Azure CLI 2.0 (Preview) with Azure Storage


The open-source, cross-platform Azure CLI 2.0 (Preview) provides a set of commands for working with the Azure platform. It provides much of the same functionality found in the Azure portal, including rich data access.

In this guide, we show you how to use the Azure CLI 2.0 (Preview) to perform several tasks working with resources in your Azure Storage account. We recommend that you download and install or upgrade to the latest version of the CLI 2.0 before using this guide.

The examples in the guide assume the use of the Bash shell on Ubuntu, but other platforms should perform similarly.

Versions of the Azure CLI

There are two versions of the Azure Command-line Interface (CLI) currently available:

Azure CLI 1.0--our CLI written in Node.js, for use with both the classic and resource management deployment models.

Azure CLI 2.0 (Preview)--a next-generation CLI written in Python, for use with the resource management deployment model.


This guide assumes that you understand the basic concepts of Azure Storage. It also assumes that you're able to satisfy the account creation requirements that are specified below for Azure and the Storage service.


Install the Azure CLI 2.0 (Preview)

Download and install the Azure CLI 2.0 (Preview) by following the instructions outlined in Install Azure CLI 2.0 (Preview).


If you have trouble with the installation, check out the Installation Troubleshooting section of the article, and the Install Troubleshooting guide on GitHub.

Working with the CLI

Once you've installed the CLI, you can use the az command in your command-line interface (Bash, Terminal, Command Prompt) to access the Azure CLI commands. Type the az command, and you should be presented with output similar to:

    /  \    _____   _ _ __ ___
   / /\ \  |_  / | | | \'__/ _ \
  / ____ \  / /| |_| | | |  __/
 /_/    \_\/___|\__,_|_|  \___|

Welcome to the cool new Azure CLI!

Here are the base commands:

    account   : Commands to manage subscriptions.
    acr       : Commands to manage Azure container registries.
    acs       : Commands to manage Azure container services.
    ad        : Synchronize on-premises directories and manage Azure Active Directory (AAD)
    appservice: Commands to manage your Azure web apps and App Service plans.
    cloud     : Manage the Azure clouds registered.
    component : Commands to manage and update Azure CLI 2.0 (Preview) components.
    configure : Configure Azure CLI 2.0 Preview or view your configuration. The command is
                interactive, so just type `az configure` and respond to the prompts.
    container : Set up automated builds and deployments for multi-container Docker applications.
    context   : Manage contexts.
    feature   : Commands to manage resource provider features, such as previews.
    feedback  : Loving or hating the CLI?  Let us know!
    group     : Commands to manage resource groups.
    login     : Log in to access Azure subscriptions.
    logout    : Log out to remove accesses to Azure subscriptions.
    network   : Manages Network resources.
    policy    : Commands to manage resource policies.
    provider  : Manage resource providers.
    resource  : Generic commands to manage Azure resources.
    role      : Use role assignments to manage access to your Azure resources.
    storage   : Durable, highly available, and massively scalable cloud storage.
    tag       : Manage resource tags.
    vm        : Provision Linux and Windows virtual machines in minutes.
    vmss      : Create highly available, auto-scalable Linux or Windows virtual machines.

In your command-line interface, execute the command az storage -h to list the storage group commands and its subgroups. The descriptions of the subgroups provide an overview of the functionality the Azure CLI provides for working with your storage resources.

    az storage: Durable, highly available, and massively scalable cloud storage.

    account  : Manage storage accounts.
    blob     : Object storage for unstructured data.
    container: Manage blob storage containers.
    cors     : Manage Storage service Cross-Orgin Resource Sharing (CORS).
    directory: Manage file storage directories.
    entity   : Manage table storage entities.
    file     : File shares that use the standard SMB 3.0 protocol.
    logging  : Manage Storage service logging information.
    message  : Manage queue storage messages.
    metrics  : Manage Storage service metrics.
    queue    : Effectively scale apps according to traffic using queues.
    share    : Manage file shares.
    table    : NoSQL key-value storage using semi-structured datasets.

Connect the CLI to your Azure subscription

To work with the resources in your Azure subscription, you must first log in to your Azure account with az login. There are several ways you can log in:

  • Interactive login: az login
  • Log in with user name and password: az login -u -p VerySecret
    • This doesn't work with Microsoft accounts or accounts that use multi-factor authentication.
  • Log in with a service principal: az login --service-principal -u http://azure-cli-2016-08-05-14-31-15 -p VerySecret --tenant

Azure CLI 2.0 sample script

Next, we'll work with a small shell script that issues a few basic Azure CLI 2.0 commands to interact with Azure Storage resources. The script first creates a new container in your storage account, then uploads an existing file (as a blob) to that container. It then lists all blobs in the container, and finally, downloads the file to a destination on your local computer that you specify.

# A simple Azure Storage example script

export AZURE_STORAGE_ACCOUNT=<storage_account_name>
export AZURE_STORAGE_ACCESS_KEY=<storage_account_key>

export container_name=<container_name>
export blob_name=<blob_name>
export file_to_upload=<file_to_upload>
export destination_file=<destination_file>

echo "Creating the container..."
az storage container create -n $container_name

echo "Uploading the file..."
az storage blob upload -f $file_to_upload -c $container_name -n $blob_name

echo "Listing the blobs..."
az storage blob list -c $container_name

echo "Downloading the file..."
az storage blob download -c $container_name -n $blob_name -f $destination_file

echo "Done"

Configure and run the script

  1. Open your favorite text editor, then copy and paste the preceding script into the editor.

  2. Next, update the script's variables to reflect your configuration settings. Replace the following values as specified:

    • <storage_account_name> The name of your storage account.
    • <storage_account_key> The primary or secondary access key for your storage account.
    • <container_name> A name the new container to create, such as "azure-cli-sample-container".
    • <blob_name> A name for the destination blob in the container.
    • <file_to_upload> The path to small file on your local computer, such as "~/images/HelloWorld.png".
    • <destination_file> The destination file path, such as "~/downloadedImage.png".
  3. After you've updated the necessary variables, save the script and exit your editor. The next steps assume you've named your script

  4. Mark the script as executable, if necessary: chmod +x

  5. Execute the script. For example, in Bash: ./

You should see output similar to the following, and the <destination_file> you specified in the script should appear on your local computer.

Creating the container...
Uploading the file...                                           Percent complete: %100.0
Listing the blobs...
Name           Blob Type      Length  Content Type              Last Modified
-------------  -----------  --------  ------------------------  -------------------------
test_blob.txt  BlockBlob         771  application/octet-stream  2016-12-21T15:35:30+00:00
Downloading the file...

The preceding output is in table format. You can specify which output format to use by specifying the --output argument in your CLI commands, or set it globally using az configure.

Manage storage accounts

Create a new storage account

To use Azure Storage, you need a storage account. You can create a new Azure Storage account after you've configured your computer to connect to your subscription.

az storage account create -l <location> -n <account_name> -g <resource_group> --sku <account_sku>
  • -l [Required]: Location. For example, "West US".
  • -n [Required]: The storage account name. The name must be 3 to 24 characters in length, and use only lowercase alphanumeric characters.
  • -g [Required]: Name of resource group.
  • --sku [Required]: The storage account SKU. Allowed values:
    • Premium_LRS
    • Standard_GRS
    • Standard_LRS
    • Standard_RAGRS
    • Standard_ZRS

Set default Azure storage account environment variables

You can have multiple storage accounts in your Azure subscription. To select one of them to use for all subsequent storage commands, you can set these environment variables:

export AZURE_STORAGE_ACCOUNT=<account_name>

Another way to set a default storage account is by using a connection string. First, get the connection string with the show-connection-string command:

az storage account show-connection-string -n <account_name> -g <resource_group>

Then copy the output connection string and set the AZURE_STORAGE_CONNECTION_STRING environment variable (you might need to enclose the connection string in quotes):

export AZURE_STORAGE_CONNECTION_STRING=<connection_string>

All examples in the following sections of this article assume that you've set the AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_ACCESS_KEY environment variables.

Create and manage blobs

Azure Blob storage is a service for storing large amounts of unstructured data, such as text or binary data, that can be accessed from anywhere in the world via HTTP or HTTPS. This section assumes that you are already familiar with Azure Blob storage concepts. For detailed information, see Get started with Azure Blob storage using .NET and Blob Service Concepts.

Create a container

Every blob in Azure storage must be in a container. You can create a container by using the az storage container create command:

az storage container create -n <container_name>

You can set one of three levels of read access for a new container by specifying the optional --public-access argument:

  • off (default): Container data is private to the account owner.
  • blob: Public read access for blobs.
  • container: Public read and list access to the entire container.

For more information, see Manage anonymous read access to containers and blobs.

Upload a blob to a container

Azure Blob storage supports block, append, and page blobs. Upload blobs to a container by using the blob upload command:

az storage blob upload -f <local_file_path> -c <container_name> -n <blob_name>

By default, the blob upload command uploads *.vhd files to page blobs, or block blobs otherwise. To specify another type when you upload a blob, you can use the --type argument--allowed values are append, block, and page.

For more information on the different blob types, see Understanding Block Blobs, Append Blobs, and Page Blobs.

Download blobs from a container

This example demonstrates how to download a blob from a container:

az storage blob download -c mycontainer -n myblob.png -f ~/mydownloadedblob.png

Copy blobs

You can copy blobs within or across storage accounts and regions asynchronously.

The following example demonstrates how to copy blobs from one storage account to another. We first create a container in another account, specifying that its blobs are publicly, anonymously accessible. Next, we upload a file to the container, and finally, copy the blob from that container into the mycontainer container in the current account.

az storage container create -n mycontainer2 --account-name <accountName2> --account-key <accountKey2> --public-access blob

az storage blob upload -f ~/Images/HelloWorld.png -c mycontainer2 -n myBlockBlob2 --account-name <accountName2> --account-key <accountKey2>

az storage blob copy start -u https://<accountname2> -b myBlobBlob -c mycontainer

The source blob URL (specified by -u) must either be publicly accessible, or include a shared access signature (SAS) token.

Delete a blob

To delete a blob, use the blob delete command:

az storage blob delete -c <container_name> -n <blob_name>

Create and manage file shares

Azure File storage offers shared storage for applications using the Server Message Block (SMB) protocol. Microsoft Azure virtual machines and cloud services, as well as on-premises applications, can share file data via mounted shares. You can manage file shares and file data via the Azure CLI. For more information on Azure File storage, see Get started with Azure File storage on Windows or How to use Azure File storage with Linux.

Create a file share

An Azure File share is an SMB file share in Azure. All directories and files must be created in a file share. An account can contain an unlimited number of shares, and a share can store an unlimited number of files, up to the capacity limits of the storage account. The following example creates a file share named myshare.

az storage share create -n myshare

Create a directory

A directory provides an optional hierarchical structure for an Azure file share. The following example creates a directory named myDir in the file share.

az storage directory create -n myDir -s myshare

Note that directory path can include multiple levels, e.g., a/b. However, you must ensure that all parent directories exist. For example, for path a/b, you must create directory a first, then create directory b.

Upload a local file to a share

The following example uploads a file from ~/temp/samplefile.txt to root of the myshare file share. The --source argument specifies the existing local file to upload.

az storage file upload --share-name myshare --source ~/temp/samplefile.txt

As with directory creation, you can specify a directory path within the share to upload the file to an existing directory within the share:

az storage file upload --share-name myshare/myDir --source ~/temp/samplefile.txt

A file in the share can be up to 1 TB in size.

List the files in a share

You can list files and directories in a share by using the az storage file list command:

# List the files in the root of a share
az storage file list -s myshare

# List the files in a directory within a share
az storage file list -s myshare/myDir

# List the files in a path within a share
az storage file list -s myshare -p myDir/mySubDir/MySubDir2

Copy files

You can copy a file to another file, a file to a blob, or a blob to a file. For example, to copy a file to a directory in a different share:

# Get the URL for the source file you want to copy
az storage file url -s myshare -p /mydir/image.png

# Copy the file to another share
az storage file copy start \
    --source-uri \    
    --destination-share myshare2 --destination-path mydir2/image.png

There is known issue in the CLI 2.0 (Preview) preventing the use of --source-share and --source-path. You can use the --source-uri argument as a workaround until this issue is resolved.

Next steps

Here are some additional resources for learning more about working with the Azure CLI 2.0 (Preview).