az storage blob list: Usage & Common CI Errors

List the blobs in an Azure Storage container.

az storage blob list enumerates the blobs in a container. As with upload, the authentication mode - AAD login, account key, or SAS - is the part CI most often gets wrong.

What it does

az storage blob list --account-name <acct> --container-name <c> returns the blobs in a container, with --prefix to scope to a virtual folder and --query/-o to shape output. Authentication uses --auth-mode login (AAD), an --account-key, a --sas-token, or AZURE_STORAGE_CONNECTION_STRING.

Common usage

# List blob names under a prefix using AAD auth
az storage blob list \
  --account-name mystorage \
  --container-name artifacts \
  --prefix releases/ \
  --auth-mode login \
  --query "[].name" -o tsv

# Using a connection string
az storage blob list --container-name artifacts \
  --connection-string "$AZURE_STORAGE_CONNECTION_STRING" -o table

Common error in CI: AuthorizationPermissionMismatch / "auth credentials" warning

Listing with --auth-mode login fails with "AuthorizationPermissionMismatch" when the identity has only control-plane Contributor, not a data-plane role, and omitting auth entirely triggers a warning that the CLI fell back to looking for an account key. Fix: for AAD auth, assign "Storage Blob Data Reader" (or Contributor) on the account/container - control-plane roles do not grant data access; otherwise pass an explicit --account-key, --sas-token, or --connection-string. Quote --query expressions as one argument.

Key options

Related guides