azcli — Azure Command-Line Interface

Command-line interface for managing Azure resources. Covers az and its 200+ command groups for all Azure services.

Docs: https://learn.microsoft.com/en-us/cli/azure/

Platform Notes (Windows + Git Bash)

• Install: winget install --exact --id Microsoft.AzureCLI (preferred) or MSI from https://aka.ms/installazurecliwindows
• After install/update: close and reopen terminal — required for PATH
• Config: ~/.azure/ (credentials, config, profiles)
• Secrets: use Key Vault or env vars, never commit credentials
• Extensions: az extension add --name NAME (some features require extensions)
• Version: az version (check for updates: az upgrade)

⚠️ Quoting Gotchas

Git Bash, PowerShell, and cmd have different quoting rules for --query (JMESPath):

# Git Bash — use single quotes for JMESPath
az vm list --query '[].name' -o tsv

# PowerShell — use single quotes or escaped double quotes
az vm list --query '[].name' -o tsv

# Avoid: Git Bash may mangle double-quoted JMESPath

⚠️ Cost: Commands that create resources (VMs, databases, clusters) incur Azure charges. Always confirm subscription and region before creating.

Agent Safety Model

Operations classified by risk. Follow this model for all az commands.

Rules:

• Never combine `--yes` with destructive operations — it suppresses the only safety gate
• Never put passwords/secrets as command-line arguments — visible in process list & shell history
• Always use `-o json` for machine-parseable output (agents can't reliably parse tables)
• When in doubt, treat as DESTRUCTIVE

Command Structure

az [GROUP] [SUBGROUP] COMMAND [ARGS] [FLAGS]

Key global flags: --subscription, --output (-o), --query, --verbose, --debug, --only-show-errors, --yes

Service Reference

Read the per-service file for full command reference.

Pre-Flight Checks

Before working with any Azure service:

# 1. Logged in?
az account show -o json

# 2. Correct subscription?
az account show --query '{Name:name, Id:id, State:state}' -o json

# 3. Change subscription if needed
az account set --subscription "<name-or-id>"

# 4. Default location set?
az config get defaults.location 2>/dev/null

# 5. Set default location (optional)
az config set defaults.location=westeurope

# 6. Resource provider registered? (most are auto-registered)
az provider show --namespace Microsoft.ContainerApp --query "registrationState" -o tsv
az provider register --namespace Microsoft.ContainerApp --wait

Troubleshooting

# Debug mode
az vm list --debug 2>&1 | head -50

# Full environment info
az version
az account show -o json

Quick Reference