Azure CLI Diff Tool

0.1.1 · active · verified Thu Apr 16

The `azure-cli-diff-tool` is a Python-based utility designed to assist Azure CLI users in managing and analyzing metadata changes across historical versions of Azure CLI command modules and extensions. It helps identify updates and potential breaking changes by diffing metadata files. The current version is 0.1.1, and it is actively maintained as part of the broader Azure CLI development ecosystem.

Common errors

```
Bad request ...{something} is invalid" or "Unexpected token..."
```
cause Common syntax errors in Azure CLI commands due to incorrect quoting, spaces, or escape characters, especially in `--query` parameters.

fix Review Azure CLI syntax rules for your shell (Bash, PowerShell, Cmd). Use `az <command> --debug` to inspect how arguments are interpreted.
```
(RequestDisallowedByPolicy) Resource was disallowed by policy. Reasons: MFA is required.
```
cause An Azure Policy is preventing an operation, often due to a requirement for Multi-Factor Authentication (MFA) that was not met during authentication.

fix Ensure you are authenticating with MFA. If running in automation, use a service principal or managed identity that has been configured correctly with the necessary permissions and without MFA requirements for the specific operations.
```
Script unexpectedly continues after failed `az` command in PowerShell.
```
cause When running Azure CLI commands within PowerShell scripts, PowerShell's default error handling might not detect `az` command failures, causing scripts to continue execution unexpectedly.

fix Explicitly check the `$LASTEXITCODE` variable after `az` commands in PowerShell to determine success or failure. For example: `az storage account create ...; if ($LASTEXITCODE -ne 0) { Write-Error 'az command failed' }`.
```
Error: AZURE_CONFIG_DIR is not set / a valid directory.
```
cause The environment variable `AZURE_CONFIG_DIR` is not set or points to a non-existent directory, preventing Azure CLI from locating its configuration files.

fix Run `az configure` once to initialize the configuration directory. If `AZURE_CONFIG_DIR` is intentionally set, ensure the path is valid and accessible.

Warnings

gotcha The `azure-cli-diff-tool` requires Python 3.6+ to run. Older operating systems, particularly macOS, might come with Python 2.7 preinstalled, which is incompatible.
Fix: Ensure you are running Python 3.6 or newer. Consider using a virtual environment (`python3 -m venv env`) to manage Python versions.
breaking Azure CLI itself, which this tool extends, introduces breaking changes up to twice a year (typically in the second and fourth quarters). While this tool aids in detecting such changes, users should be aware of the overall Azure CLI breaking change policy and verify scripts in a test environment before upgrading.
Fix: Consult the Azure CLI release notes for pre-announcements of breaking changes. Utilize `az command-change version-diff` to specifically analyze changes relevant to your scripts.
breaking Starting September 2025, Microsoft will require multifactor authentication (MFA) for Azure CLI when using Microsoft Entra ID user identities. This will break automation scripts that rely on username/password authentication without MFA.
Fix: Migrate automation workflows using `az login` with username/password to workload identities such as service principals or managed identities, which are unaffected by this MFA requirement.

Install

pip install azure-cli-diff-tool Install with pip

Quickstart

The `azure-cli-diff-tool` is primarily used as an Azure CLI extension. First, ensure the `command-change` extension is installed, then use `az command-change version-diff` to compare metadata between two Azure CLI versions for a specific module, such as 'monitor'.

az extension add --name command-change

az command-change version-diff --base-version 2.47.0 --diff-version 2.49.0 --target-module monitor

view raw JSON →