Added macos install cask and tarball preview article

Author: mikefrobbins

docs-ref-conceptual/Latest-version/install-azure-cli-macos-preview.md

@@ -0,0 +1,290 @@
+---
+title: Install Azure CLI on macOS using Homebrew cask or tarball preview
+description: Install Azure CLI on macOS using Homebrew cask or tarball. Includes offline setup, upgrade, uninstall, and migration guidance.
+ms.service: azure-cli
+ms.custom: devx-track-azurecli
+zone_pivot_group_filename: azure/zone-pivot-groups.json
+zone_pivot_groups: cli-macos-installation-method
+keywords: Install azure cli, azure cli macos, macos cli, install azure cli macos
+---
+
+# Install Azure CLI on macOS using Homebrew cask or tarball preview
+
+Azure CLI is a cross-platform command-line tool used to manage Azure resources from the command line
+or through scripts.
+
+On macOS, Azure CLI is transitioning to a new installation model that provides greater flexibility
+across environments. This model includes:
+
+- Homebrew cask (recommended for most users)
+- Tarball (recommended for offline, restricted, or custom environments)
+
+This experience is currently in preview and will become the standard installation approach in a
+future release.
+
+> [!NOTE]
+> For the current stable installation guidance, see [Install Azure CLI on macOS](install-azure-cli-macos.md).
+
+## What is changing
+
+Azure CLI installation on macOS is moving away from the Homebrew formula to a more maintainable and
+flexible model.
+
+- Current method: `brew install azure-cli`
+- New methods:
+  - `brew install --cask azure-cli`
+  - Tarball-based installation
+
+During the transition period, both installation methods are supported. The Homebrew formula will be
+deprecated in a future release.
+
+This change improves consistency across environments and provides better support for scenarios such
+as offline installation and controlled deployment environments.
+
+## Choose an installation method
+
+Use the following guidance to select the installation method that best fits your scenario:
+
+|             Scenario             | Recommended method |
+| -------------------------------- | ------------------ |
+| Most users                       | Homebrew cask      |
+| Offline or air-gapped systems    | Tarball            |
+| Custom install location required | Tarball            |
+
+::: zone pivot="cask"
+
+## Option 1 - Install using Homebrew cask
+
+Homebrew provides the simplest and most maintainable installation experience for Azure CLI on macOS.
+It handles installation, upgrades, and removal using standard package management workflows.
+
+### Prerequisites
+
+- macOS (Apple Silicon or Intel)
+- [Homebrew](https://brew.sh/) installed
+
+If Azure CLI is already installed using the Homebrew formula, uninstall it before proceeding to
+avoid conflicts:
+
+```bash
+brew uninstall azure-cli
+```
+
+### Install Azure CLI
+
+```bash
+brew update && brew install --cask azure-cli
+```
+
+This installs Azure CLI using the Homebrew cask, which is the preferred installation method going
+forward.
+
+### Verify installation
+
+After installation, confirm Azure CLI is available:
+
+```bash
+az --version
+```
+
+### Upgrade Azure CLI
+
+To upgrade to the latest version:
+
+```bash
+brew upgrade --cask azure-cli
+```
+
+### Uninstall Azure CLI
+
+To remove Azure CLI:
+
+```bash
+brew uninstall --cask azure-cli
+```
+
+::: zone-end
+
+::: zone pivot="tarball"
+
+## Option 2 - Install using a tarball
+
+Use this method if:
+
+- Homebrew isn't available
+- Internet access is restricted
+- You need full control over the installation location
+
+This method is commonly used in enterprise, regulated, or air-gapped environments.
+
+### Prerequisites
+
+- macOS (Apple Silicon or Intel)
+- Python 3.13 installed using your preferred method (for example, python.org or pyenv)
+
+### Determine your architecture
+
+Before downloading the tarball, determine your system architecture:
+
+```bash
+uname -m
+```
+
+- `arm64` - Apple Silicon (M1, M2, M3, and newer)
+- `x86_64` - Intel-based Mac
+
+Selecting the correct architecture ensures compatibility and optimal performance.
+
+### Step 1: Download the tarball
+
+On a machine with internet access, download the desired Azure CLI release from:
+
+[https://github.com/Azure/azure-cli/releases](https://github.com/Azure/azure-cli/releases)
+
+Example:
+
+```bash
+# Replace <version> and <arch>
+curl -L -o azure-cli-<version>-macos-<arch>.tar.gz \
+  https://github.com/Azure/azure-cli/releases/download/azure-cli-<version>/azure-cli-<version>-macos-<arch>.tar.gz
+```
+
+> [!TIP]
+> For offline environments, transfer the tarball to the target system using a secure method such as
+> removable media or secure file transfer.
+
+### Step 2: Extract to installation directory
+
+Choose a directory where Azure CLI should be installed:
+
+```bash
+sudo mkdir -p /target_directory_path
+sudo tar -xzf azure-cli-<version>-macos-<arch>.tar.gz -C /target_directory_path
+```
+
+### Step 3: Configure environment variables
+
+Azure CLI requires access to a Python runtime. Configure your environment to point to Python and the
+Azure CLI binaries.
+
+Add the following to your shell profile (`~/.zshrc` or `~/.bashrc`):
+
+```bash
+export AZ_PYTHON="/path_to_python"
+export PATH="/target_directory_path/bin:$PATH"
+```
+
+Reload your shell configuration:
+
+```bash
+source ~/.zshrc
+```
+
+### Step 4: Verify installation
+
+```bash
+az --version
+```
+
+### Upgrade (offline)
+
+To upgrade Azure CLI in an offline environment, download a newer tarball and extract it over the
+existing installation:
+
+```bash
+sudo tar -xzf azure-cli-<version>-macos-<arch>.tar.gz -C /target_directory_path
+```
+
+### Uninstall (offline)
+
+Remove the installation directory:
+
+```bash
+sudo rm -rf /target_directory_path
+```
+
+Then remove the `AZ_PYTHON` and `PATH` entries from your shell profile.
+
+::: zone-end
+
+## Migrate from Homebrew formula to cask
+
+If you previously installed Azure CLI using the Homebrew formula:
+
+```bash
+brew install azure-cli
+```
+
+migrate to the cask installation:
+
+```bash
+brew uninstall azure-cli
+brew install --cask azure-cli
+```
+
+Verify the installation:
+
+```bash
+az --version
+```
+
+> [!IMPORTANT]
+> The Homebrew formula installation will be deprecated in a future release.
+
+## Existing installations (Homebrew formula)
+
+Existing installations using the Homebrew formula will continue to work during the transition
+period.
+
+For current guidance, see [Install Azure CLI on macOS](install-azure-cli-macos.md).
+
+## Troubleshooting
+
+### Azure CLI not found
+
+Ensure your PATH includes the installation directory:
+
+```bash
+echo $PATH
+```
+
+### Completion isn't working
+
+For Zsh, enable shell completion:
+
+```bash
+autoload bashcompinit && bashcompinit
+source $(brew --prefix)/etc/bash_completion.d/az
+```
+
+### Proxy blocks connection
+
+If you're behind a proxy, configure your environment:
+
+- `HTTP_PROXY`
+- `HTTPS_PROXY`
+
+Ensure your proxy allows HTTPS access to:
+
+- [https://formulae.brew.sh](https://formulae.brew.sh)
+- [https://homebrew.bintray.com](https://homebrew.bintray.com)
+
+## Next steps
+
+After installation, sign in and begin using Azure CLI:
+
+```bash
+az login
+```
+
+Explore available commands:
+
+```bash
+az find
+```
+
+Learn more:
+
+[https://learn.microsoft.com/cli/azure/](https://learn.microsoft.com/cli/azure/)
+
+```

docs-ref-conceptual/Latest-version/zone-pivot-groups.yml

@@ -24,3 +24,11 @@ groups:
       title: Microsoft Installer (MSI) with PowerShell
     - id: zip
       title: ZIP Package
+- id: cli-macos-installation-method
+  title: Azure CLI installation method for macOS
+  prompt: Choose an installation method
+  pivots:
+    - id: cask
+      title: Homebrew (cask)
+    - id: tarball
+      title: tarball