Microsoft Azure CLI

Extensions allow users to add, modify, or remove commands within the az CLI. They are useful for releasing private or public previews of Azure CLI commands.

Key characteristics:

• Extensions are supported across all installation methods.
• They are implemented as Python Wheels.
• An extension is NOT an external executable; it operates within the az environment.

The standard collaboration workflow between service teams and the Azure CLI team follows this sequence:

1. Swagger and service ready: The REST API specifications are merged and the service is released.
2. Azure Python SDK ready (PyPI): The corresponding Python SDK is available on PyPI.
3. Azure CLI commands ready: The Azure CLI implementation begins.

When interacting with or developing for the Azure CLI, expect the following behavioral patterns:

• Output Formats: Commands support JSON, TSV, and table output types.
• Piping and Tooling: Commands are designed to be consistent with POSIX tools, meaning they support piping to utilities like grep, awk, and jq.
• Tab Completion: Parameter names and values (such as resource names) support tab completion.
• Standard Streams: Command output is sent to stdout, while logs, status messages, and errors are sent to stderr.
• Return Types: Commands return objects, dictionaries, or None (not strings or Booleans).

The az storage share-rm command group is used to manage Azure file shares via the Microsoft.Storage resource provider. This is useful if you want to bypass firewalls or if HTTPS is supported for your storage account.

Note: This command group is in preview and may change in future releases.

Azure CLI uses two distinct types of telemetry to monitor and analyze command execution:

1. ARM Telemetry: Tracks HTTP requests and responses through the Azure Resource Manager (ARM) endpoint. It does not record cases where:

   • The command fails to create a request (e.g., parameter validation failure).
   • The command calls a data plane service API.
   • The network is inaccessible.
   • No request is required during execution.

2. CLI Client Telemetry: Sent at the end of every Azure CLI command execution, regardless of whether HTTP requests were made. This covers local operations and all command types.

Azure CLI follows semantic versioning to communicate the impact of updates. Since version 2.1.0, the version numbers indicate the following:

• MAJOR version: Incremented for core changes that break command behavior globally.
• MINOR version: Incremented for general backward-compatible feature changes and breaking changes specific to service command modules.
• PATCH version: Incremented for bug fixes.

When a package only upgrades its PATCH version, it guarantees backward compatibility at the command level.

Azure CLI manages backward compatibility through bi-annual Breaking Change Releases that coincide with Microsoft Build (typically May) and Ignite (typically November). A breaking change is any modification that disrupts backward compatibility, such as:

• Modifying names of parameters or commands.
• Modifying the input logic of parameters.
• Modifying the format or properties of result output.
• Modifying the current behavior model.
• Adding additional verification that changes CLI behavior.

To ensure stability, the introduction of breaking changes is typically prohibited outside of the designated Breaking Change Window (a specific sprint aligned with Build/Ignite).

The following features are known to be unsupported in airgapped environments:

• Extension Management: Installing extensions by name (e.g., az extension add --name <name>) is not supported.
• Upgrades: az upgrade is not supported; use manual installation methods instead.
• Discovery: az find for command examples is unavailable.
• AI/Recommendations: Command recommendations based on Aladdin service are unavailable.
• Tool Installation: Commands that attempt to install external tools (e.g., az aks install-cli, az storage copy) will fail.
• External Channels: az bot operations involving external channels like Facebook or WeChat are unavailable.
• Hyperlinks: Some links in help or error messages may be inaccessible.

AAZ Flow is an MCP (Model Context Protocol) server for AAZ APIs. It is designed to assist with pruning command-line interfaces, implementing custom logic, and generating test cases.

Note: AAZ Flow is in early development; functionality and available tools are subject to change.

To debug the Azure CLI source code using Visual Studio Code, ensure you have the following installed and configured:

• Visual Studio Code
• Visual Studio Code Python Extension
• Python 3.10+
• A properly set up development environment (refer to the project's machine configuration guide).