---
schema_version: 1
route: /t/azd.md
tool: "azd"
---

# sincecutoff.com /t/azd — Azure Developer CLI

- name: Azure Developer CLI
- kind: cli
- children: none
- homepage: <https://github.com/Azure/azure-dev>

Changes to the tools coding agents drive, since a model's training cutoff, each linked to its first-party source. Check installed versions and limitations before acting; a cutoff date does not establish what a model knows.
Original editorial content: [Apache 2.0](https://sincecutoff.com/v1/data-license.txt), by [0xPatrick](https://0xpatrick.dev). Preserve applicable license and [NOTICE](https://sincecutoff.com/notice.txt) attribution when redistributing. Third-party source text and examples retain their own rights. [License scope and attribution](https://sincecutoff.com/v1/license.json).
To stay current, read the changes feed: [`/v1/changes.md?tool=azd`](https://sincecutoff.com/v1/changes.md?tool=azd) (or `.json`), adding `since=YYYY-MM-DD` for your training cutoff. Entries for registered children are included; the registry itself is `/v1/tools.json`. How to page and save your place: [llms.txt](https://sincecutoff.com/llms.txt).

### azd deploy adds preview support for built-in service hosts (2026-09-30)
- slug: azd-deploy-adds-preview-support-for-built-in-service-hosts-318aff77537b
- score: 0.97

How to use it:

When a project uses a built-in service host, run `azd deploy --preview` to ask each selected service target to describe deployment changes. Read the human-readable `Message` in text output or `services.<name>.data` with JSON output.

Examples:

```
azd deploy --preview
```

```
azd deploy --preview --output json
```

- why_it_matters: Preview the deployment changes for a project using a built-in azd service host.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.35.0>, <https://github.com/Azure/azure-dev/blob/azure-dev-cli_1.35.0/cli/azd/docs/extensions/extension-framework.md>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference>
- gotchas: "Version: 1.35.0"; "--preview: Preview service deployment changes; cannot be combined with `--from-package` or `--timeout`."; "--output json: Select JSON output; preview `Data` is returned under `services.<name>.data`."; "<service>: Select a specific service; without one, the command selects all services listed in `azure.yaml`."; "Supported built-in hosts listed in the release span are App Service, Container Apps, Functions, Static Web Apps, AKS, and AI endpoints."; "Nothing is packaged, published, or deployed; service targets are not initialized and deploy hooks do not run."; "Services whose host does not support preview are reported and skipped."; "The flag cannot be combined with `--from-package` or `--timeout`."

### azd adds per-phase concurrency limits (2026-09-16)
- slug: azd-adds-per-phase-concurrency-limits-fb38fca06749
- score: 0.98

How to use it:

When tuning parallel work in an azd project, set the relevant concurrency environment variables for `azd up`, `azd deploy`, or `azd provision`. Configure `AZD_CONCURRENCY_MAX` for the global ceiling; values are clamped to 64, and standalone `azd package` remains sequential.

Examples:

```
AZD_PACKAGE_CONCURRENCY=<positive-integer> AZD_PROVISION_CONCURRENCY=<positive-integer> AZD_DEPLOY_CONCURRENCY=<positive-integer> AZD_CONCURRENCY_MAX=<positive-integer> azd up
```

```
AZD_PACKAGE_CONCURRENCY=<positive-integer> AZD_DEPLOY_CONCURRENCY=<positive-integer> AZD_CONCURRENCY_MAX=<positive-integer> azd deploy
```

```
AZD_PROVISION_CONCURRENCY=<positive-integer> AZD_CONCURRENCY_MAX=<positive-integer> azd provision
```

- why_it_matters: Tune parallel package, provision, publish, or deploy work when maintaining an azd project.
- before: Before graph-driven `up`, `provision`, and `deploy` pipelines, these commands ran each service and each layer sequentially.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.34.1>, <https://github.com/Azure/azure-dev/pull/9752>, <https://github.com/Azure/azure-dev/blob/azure-dev-cli_1.34.1/cli/azd/docs/concurrency-model.md>
- gotchas: "Version: 1.34.1"; "AZD_CONCURRENCY_MAX: Hard global ceiling; for `azd up`, fallback order is `AZD_UP_CONCURRENCY`, then `AZD_DEPLOY_CONCURRENCY`, then scheduler default. For `azd deploy` and `azd provision`, fallback is the respective command concurrency variable, then scheduler default."; "AZD_PACKAGE_CONCURRENCY: Package phase limit. For `azd up`, fallback is `AZD_UP_CONCURRENCY`; for `azd deploy`, fallback is `AZD_DEPLOY_CONCURRENCY`."; "AZD_PROVISION_CONCURRENCY: Provision phase limit for `azd up`; fallback is `AZD_UP_CONCURRENCY`. It is also the provision phase limit and command-level fallback for `azd provision`."; "AZD_DEPLOY_CONCURRENCY: Shared publish/deploy phase limit. For `azd up`, it is also a global-ceiling fallback and precedes `AZD_UP_CONCURRENCY` for that phase. For `azd deploy`, it is also the global-ceiling and package-limit fallback."; "AZD_UP_CONCURRENCY: Fallback phase limit for package, provision, and publish/deploy under `azd up`; also a global-ceiling fallback after `AZD_CONCURRENCY_MAX`."; "configured concurrency values: Positive integers, clamped to 64. An explicitly set invalid or non-positive value disables that limit and blocks fallback; fallback occurs only when the higher-precedence variable is unset."; "Configured values are positive integers clamped to 64."; "An explicitly set invalid or non-positive value disables that limit and blocks fallback."; "Fallback occurs only when the higher-precedence variable is unset."; "Package and provision work in `azd up` can overlap while retaining independent limits."; "Publish and deploy share one budget because both are part of the deployment phase."; "Standalone `azd package` remains sequential."

### azd deploy supports docker.imagePassthrough (2026-08-26)
- slug: azd-deploy-supports-docker-imagepassthrough-1901a0f52ab8
- score: 0.96

How to use it:

When deploying an existing remote image by reference, set `services.<name>.docker.imagePassthrough: true` and set the service-level `image` to its fully qualified registry reference, then run `azd deploy <service>`.

Examples:

```
azd deploy <service>
```

```
services:
  <service>:
    host: containerapp
    image: <registry>/<repository>:<tag>
    docker:
      imagePassthrough: true
```

- why_it_matters: Deploy an existing container image by reference with azd.
- before: Without `imagePassthrough`, an existing external source image could be pulled, tagged, and copied to a configured destination registry.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.32.0>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/publishing-workflows>, <https://github.com/Azure/azure-dev/pull/9588>
- gotchas: "Version: 1.32.0"; "<service> (required): Service name from `azure.yaml`."; "services.<name>.docker.imagePassthrough (required): Set to `true` to use the service image as the final remote container artifact; no local or remote image operations are performed."; "services.<name>.image (required): Fully qualified remote image reference, including an explicit registry."; "docker.remoteBuild: Cannot be combined with `docker.imagePassthrough: true`."; "azd deploy --from-package: Deploys a package path or container image tag; no flag is needed for passthrough because the configured image is reused."; "Prerequisite: Set the service host to `containerapp` in the documented configuration example."; "Prerequisite: Set the service-level image to a fully qualified remote reference that includes a registry."; "Deploys an existing container image by reference; performs no local or remote image operations."

### azd extension install accepts HTTPS bundle URLs (2026-08-12)
- slug: azd-extension-install-accepts-https-bundle-urls-a9662c687659
- score: 0.97

How to use it:

When the extension bundle is self-contained and hosted at an HTTPS URL, pass that URL as the extension name to `azd extension install`.

Examples:

```
azd extension install https://<host>/<path>/<bundle>.zip
```

- why_it_matters: Install a self-contained azd extension bundle hosted at an HTTPS URL.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.31.0>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/extensions/overview>
- gotchas: "Version: 1.31.0"; "Requires `azd extension install` with a self-contained extension bundle from an HTTPS URL"; "<bundle URL> (required): HTTPS URL of the self-contained `.zip` bundle; provide it as the extension name."; "--version, -v: Specifies the exact version to install; cannot be used when installing a self-contained bundle."; "Prerequisite: The bundle must be a self-contained `.zip` hosted at an HTTPS URL."; "The bundle must be self-contained and available from an HTTPS URL."

### azd extension install supports --no-dependencies (2026-07-09)
- slug: azd-extension-install-supports-no-dependencies-88633b30889d
- score: 0.94

How to use it:

When you want to install only a named extension, run `azd extension install` with `--no-dependencies` to skip its declared dependencies.

Examples:

```
azd extension install <extension-id> --no-dependencies
```

- why_it_matters: Install a named azd extension without installing its declared dependencies.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.27.1>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference>
- gotchas: "Version: 1.27.1"; "<extension-id> (required): ID of the extension to install."; "--no-dependencies: Install only the specified extension(s) without installing their declared dependencies."; "Prerequisite: Install `azd`; the command synopsis describes installing extensions by ID from a registered extension source."; "Installs only the named extension; declared dependencies are not resolved or installed."

### azd deploys Docker services to App Service (2026-06-30)
- slug: azd-deploys-docker-services-to-app-service-e2c29768f65c
- score: 0.95

How to use it:

When deploying a Docker-based service to App Service, set `host: appservice` and `language: docker` or `docker.path`. Then run `azd deploy <service>` to build and push the image to ACR and update the site’s container image reference.

Examples:

```
services:
  <service>:
    project: ./src/web
    host: appservice
    language: docker
    docker:
      path: ./Dockerfile
```

```
azd deploy <service>
```

- why_it_matters: Deploy a Docker-based Web App for Containers scenario to App Service from an azd project.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.27.0>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/app-service-containers>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/azd-schema>
- gotchas: "Version: 1.27.0"; "`host` (required): Set to `appservice` for Azure App Service."; "`project` (required): Path to the service source directory when building the image from source."; "`language`: Set to `docker` to trigger container mode; alternatively, set `docker.path`."; "`docker.path`: Path to the Dockerfile; setting it triggers container mode on the App Service host. The docs do not state that it is mutually exclusive with `language: docker`."; "`<service>` (required): Service name from `azure.yaml` to deploy."; "Prerequisite: The App Service site must already be provisioned as a Linux container app; `azd deploy` does not provision or configure infrastructure."; "Prerequisite: Infrastructure must configure a Linux App Service plan, a container-ready `linuxFxVersion` using `DOCKER|`, a single container, and user-assigned managed identity access to ACR."; "Prerequisite: Infrastructure must define the ACR instance used for the image push."; "This applies to services configured with `host: appservice` and `language: docker` or `docker.path`."

### azd extension install, upgrade, and list accept direct registry sources (2026-06-30)
- slug: azd-extension-install-upgrade-and-list-accept-direct-registry-sources-5b30a11be1ac
- score: 0.97

How to use it:

When installing or upgrading an extension from a registry URL or local path, pass that location with `--source` to register and use it. The current docs describe `list --source` as read-only; see conflicts.

Examples:

```
azd extension install <extension-id> --source <registry-url-or-local-path>
```

```
azd extension upgrade <extension-id> --source <registry-url-or-local-path>
```

```
azd extension list --source <registry-url-or-local-path>
```

- why_it_matters: Install, upgrade, or list an azd extension from a registry URL or local path without first adding a source.
- before: The release note says users previously needed to run `azd extension source add` before using the source.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.27.0>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference>, <https://github.com/Azure/azure-dev/blob/main/cli/azd/docs/extensions/extension-framework.md>
- gotchas: "Version: 1.27.0"; "<extension-id> (required): Extension identifier to install or upgrade."; "--source, -s: Accepts a registered source name or, for install and update, a registry URL or file path to register and use. For list, filters by registered source name or registry location. No mutual-exclusion rule documented."; "--installed: For list, lists installed extensions."; "Prerequisite: When registration needs a source name, install prompts for a name; URLs also require confirmation. Under `--no-prompt`, registering a source from a location is not allowed; add the source first with `azd extension source add`."; "Docs conflict: The release note says `azd extension list -s <location>` validates and persists the location before resolving the extension. Current official docs say list queries locations read-only and does not register them. The current docs are newer than version 1.27.0."

### azd config sub-filter saves per-tenant subscription filters (2026-06-25)
- slug: azd-config-sub-filter-saves-per-tenant-subscription-filters-534ec7959041
- score: 0.91

How to use it:

When interactive subscription prompts should show only selected subscriptions for a tenant, run `azd config sub-filter set` and select the subscriptions to include. Run `azd config sub-filter remove` to clear that tenant’s filter and show all subscriptions in prompts.

Examples:

```
azd config sub-filter set
```

```
azd config sub-filter remove
```

- why_it_matters: When subscription prompts should filter subscriptions by tenant, save and apply the tenant-specific filters.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.26.0>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference>
- gotchas: "Version: 1.26.0"; "set positional arguments and flags: No positional arguments or task-specific flags are documented; `set` interactively prompts for subscription selection under a tenant."; "remove positional arguments and flags: No positional arguments or task-specific flags are documented."

### azd up supports Go Azure Functions on Flex Consumption (2026-06-25)
- slug: azd-up-supports-go-azure-functions-on-flex-consumption-260839eb209c
- score: 0.94

How to use it:

When deploying a Go Function App on Flex Consumption, run `azd up` from the project template folder. The command packages, provisions, and deploys the project.

Examples:

```
azd up
```

- why_it_matters: When deploying a Go Function App on Flex Consumption, use `azd up` to deploy it.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.26.0>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/azd-up-workflow>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/get-started>
- gotchas: "Version: 1.26.0"; "--environment, -e <name>: Select the environment to use."; "--location, -l <location>: Azure location for a new environment."; "--subscription <ID>: Azure subscription to use for a new environment."; "Prerequisite: Run `azd up` from the template folder."; "Prerequisite: Install Azure Developer CLI and authenticate to Azure; the getting-started guide describes providing an Azure location and subscription when prompted."; "Applies to Go Function Apps on Flex Consumption."

### azd exec runs programs with azd environment context (2026-05-16)
- slug: azd-exec-runs-programs-with-azd-environment-context-789118f9b2b2
- score: 0.96

How to use it:

When a program or script needs the current azd environment context, run it with `azd exec`; the documented syntax supplies azd environment variables to the child process. The 1.25.1 release note also says this includes Key Vault secret resolution.

Examples:

```
azd exec <program> [args...]
```

```
azd exec ./<script>
```

- why_it_matters: Run a program or script that needs the current azd environment variables or Key Vault secrets.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.25.1>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference>
- gotchas: "Version: 1.25.1"; "command (required): Program or script to execute."; "args...: Arguments passed to the command; multiple arguments use direct process execution without shell wrapping."; "-e, --environment <environment>: Name of the environment to use."; "-i, --interactive: Connect stdin for interactive mode."; "-s, --shell <shell>: Select shell: bash, sh, zsh, pwsh, powershell, or cmd; auto-detected when omitted."; "-C, --cwd <directory>: Set the current working directory."; "Cross-platform command and script execution engine."; "Docs conflict: The current reference page was updated after azd 1.25.1 and documents command parsing and flags that may differ from that release. Its synopsis describes access to azd environment variables; Key Vault secret resolution is stated in the 1.25.1 release note, not this synopsis."

### azd subscription selection scopes subscriptions by tenant (2026-05-16)
- slug: azd-subscription-selection-scopes-subscriptions-by-tenant-ce1eb8ce6f25
- score: 0.92

How to use it:

For an account with subscriptions across multiple tenants, choose a tenant in the subscription prompt to scope the list. Set `AZURE_TENANT_ID` to filter subscriptions in prompt and no-prompt modes; a nonmatching value falls back to all subscriptions.

Examples:

```
azd up
```

```
AZURE_TENANT_ID=<tenant-id> azd up
```

- why_it_matters: Select a subscription for an account with access to multiple Azure tenants.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.25.1>, <https://github.com/Azure/azure-dev/pull/8083>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/get-started>, <https://github.com/Azure/azure-dev/blob/azure-dev-cli_1.25.1/cli/azd/pkg/prompt/tenant_helper.go>
- gotchas: "Version: 1.25.1"; "AZURE_TENANT_ID: Tenant ID used to filter available subscriptions in prompt and no-prompt modes. If none match, all subscriptions are returned."; "tenant prompt selection: When multiple tenants are available, choose a tenant to filter subscriptions; “All tenants” leaves the list unfiltered. The picker is skipped for zero or one tenant."; "The tenant picker appears for users with access to multiple tenants and is skipped for single-tenant users and service principals."; "No-prompt mode skips the tenant picker, but `AZURE_TENANT_ID` filtering still applies."; "If the tenant ID is set but no subscriptions match, the filter is a no-op and all subscriptions are shown."; "The picker includes an “All tenants” option."

### azure.yaml infra.layers[].dependsOn declares explicit layer dependencies (2026-05-09)
- slug: azure-yaml-infra-layers-dependson-declares-explicit-layer-dependencies-025ada45314d
- score: 0.96

How to use it:

When a layer depends on a value produced by another layer’s hook and that dependency cannot be inferred from parameter references, add the producing layer’s name to the dependent layer’s `dependsOn` list in `azure.yaml`.

Examples:

```
infra:
  layers:
    - name: <producer-layer>
      path: <producer-path>
    - name: <consumer-layer>
      path: <consumer-path>
      dependsOn:
        - <producer-layer>
```

- why_it_matters: Model a hook-mediated dependency in a multi-layer azd project that static analysis cannot infer from the infrastructure files.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.25.0>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/azd-schema>
- gotchas: "Version: 1.25.0"; "infra.layers[].dependsOn: Array of names of layers this layer depends on; declares dependencies the static analyzer cannot infer, including hook-mediated dependencies."; "Prerequisite: The `dependsOn` field was introduced in azd 1.25.0."; "This field declares hook-mediated edges that static analysis cannot infer from `.bicep`, `.bicepparam`, or `.parameters.json` contents alone."; "Explicit edges are validated for unknown layer names, self-references, and cycles."

### azd x watch supports .azdxignore (2026-04-18)
- slug: azd-x-watch-supports-azdxignore-3abb906ce939
- score: 0.92

How to use it:

When watching an azd project with `azd x watch`, create a project-root `.azdxignore` with gitignore syntax to exclude generated or dependency paths from rebuild triggers. The release note says the watcher also respects existing `.gitignore` patterns.

- why_it_matters: Exclude generated or dependency directories from triggering unnecessary rebuilds while watching an azd project.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.24.1>
- gotchas: "Version: 1.24.1"

### azd azure.yaml hooks accept executor-specific config (2026-04-15)
- slug: azd-azure-yaml-hooks-accept-executor-specific-config-d00f5a860812
- score: 0.90

How to use it:

When configuring a JavaScript/TypeScript, Python, or .NET hook, add `config:` to its hook in `azure.yaml` and set the option for that executor. Specify `kind` when needed to identify the executor; provide `run` because it is required when `config` is set.

Examples:

```
hooks:
  postdeploy:
    kind: ts
    run: ./hooks/<script>.ts
    config:
      packageManager: pnpm
```

```
hooks:
  postprovision:
    kind: python
    run: ./hooks/<script>.py
    config:
      virtualEnvName: <directory>
```

```
hooks:
  postprovision:
    kind: dotnet
    run: ./hooks/<script>.cs
    config:
      configuration: Release
      framework: net10.0
```

- why_it_matters: Configure runtime-specific options for hooks in an `azure.yaml` project.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.24.0>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/azd-schema>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/hooks-multi-language>
- gotchas: "Version: 1.24.0"; "run (required): Hook script or relative script path; required when `config` is specified."; "kind: Hook executor kind: `js`, `ts`, `python`, `dotnet`, `sh`, or `pwsh`. If omitted, azd infers it from the script file extension."; "config: Object for executor-specific configuration. Its available properties depend on `kind`."; "config.packageManager: For `js` or `ts`: dependency package manager; overrides lock-file auto-detection. Allowed: `npm`, `pnpm`, `yarn`."; "config.virtualEnvName: For `python`: virtual environment directory name. Defaults to auto-detection (`.venv`, `venv`) or `{baseName}_env`."; "config.configuration: For `dotnet`: MSBuild configuration, for example `Debug` or `Release`."; "config.framework: For `dotnet`: target framework moniker, for example `net8.0` or `net10.0`."; "Prerequisite: For JavaScript/TypeScript hooks, place `package.json` in the script directory or a parent directory."; "Prerequisite: For .NET project mode, a `.csproj`, `.fsproj`, or `.vbproj` must be in the script directory or a parent directory. Standalone `.cs` script mode requires .NET 10+."

### azd azure.yaml hooks run C#/.NET files with dotnet run (2026-04-15)
- slug: azd-azure-yaml-hooks-run-c-net-files-with-dotnet-run-ffb9300e167f
- score: 0.95

How to use it:

When an azd workflow reaches a hook that references a `.cs` file, azd detects the .NET hook and runs it with the .NET SDK. A nearby project file enables project mode; standalone scripts require .NET 10 or later.

Examples:

```
hooks:
  postprovision:
    run: ./hooks/migrate.cs

azd up
```

- why_it_matters: Run a C#/.NET hook defined in `azure.yaml` as part of an azd project workflow.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.24.0>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/hooks-multi-language>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/azd-schema>
- gotchas: "Version: 1.24.0"; "run (required): Inline script or relative script path; `.cs` extension enables .NET detection."; "kind: Executor kind. Allowed value `dotnet`; can explicitly select .NET execution."; "dir: Hook working directory; relative paths resolve from project or service root. Defaults to the script directory."; "config.configuration: MSBuild configuration, such as `Debug` or `Release`."; "config.framework: Target framework moniker, such as `net8.0` or `net10.0`."; "Prerequisite: Install azd and the .NET SDK."; "Prerequisite: Standalone `.cs` scripts require .NET 10 or later. Project mode discovers `.csproj`, `.fsproj`, or `.vbproj` files in the script directory or a parent directory."; "Single-file scripts require .NET 10+."

### azd azure.yaml hooks support Python scripts (2026-04-11)
- slug: azd-azure-yaml-hooks-support-python-scripts-631e39273e97
- score: 0.93

How to use it:

When an `azure.yaml` hook runs a `.py` file, `azd` detects Python from the extension and runs the script. If `requirements.txt` or `pyproject.toml` is in the script’s directory or a parent directory, `azd` creates a virtual environment and installs dependencies.

Examples:

```
hooks:
  preprovision:
    run: ./hooks/setup.py
```

- why_it_matters: Run an `azure.yaml` hook implemented as a Python script in the project.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.15>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/hooks-multi-language>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/azd-schema>
- gotchas: "Version: 1.23.15"; "hooks.<event>.run (required): Inline script or relative script path; `.py` extension enables Python detection."; "hooks.<event>.kind: Executor kind; allowed values include `python`. Omit for extension-based detection."; "hooks.<event>.config.virtualEnvName: Python virtual environment directory name override."; "Prerequisite: Install `azd` and Python 3.x."; "Prerequisite: For automatic dependency installation, put `requirements.txt` or `pyproject.toml` in the script directory or a parent directory."

### azd auth token defaults to raw token output (2026-04-04)
- slug: azd-auth-token-defaults-to-raw-token-output-1ac693b6e749
- score: 0.90

How to use it:

When a workflow needs an access token, run `azd auth token` for raw token output; use `--output json` when it needs structured output including expiration metadata.

Examples:

```
azd auth token
```

```
azd auth token --output json
```

- why_it_matters: Retrieve an access token for a coding workflow that consumes the token directly or needs its expiration metadata.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.14>
- gotchas: "Version: 1.23.14"; "--output json: Selects structured JSON output, including expiration metadata; without it, the command prints the raw access token."

### azd hooks run supports per-layer hooks (2026-04-04)
- slug: azd-hooks-run-supports-per-layer-hooks-32dfc7115981
- score: 0.97

How to use it:

When a project defines infrastructure layers, put the hook under `infra.layers[].hooks` in `azure.yaml` to run it during `azd provision`. To run a named hook for one layer, use `azd hooks run <hook-name> --layer <layer-name>`.

Examples:

```
azd hooks run <hook-name> --layer <layer-name>
```

```
infra:
  layers:
    - name: <layer-name>
      path: <infra-path>
      hooks:
        postprovision:
          shell: sh
          run: <script-path>
```

- why_it_matters: Run hooks for a specific infrastructure layer or configure hooks to run during provisioning.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.14>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/layered-provisioning>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/azd-schema>
- gotchas: "Version: 1.23.14"; "<hook-name> (required): Name of the hook to run."; "--layer <layer-name>: Restricts execution to the specified provisioning layer."; "infra.layers[].name (required): Name of the provisioning layer."; "infra.layers[].path (required): Path to the layer's IaC templates."; "infra.layers[].hooks.<event>: Hook definition for a lifecycle event, such as `postprovision`; hook definitions support `run` and optional `shell`."; "Prerequisite: Install `azd`. The docs specify no additional prerequisite for layer hooks or `azd hooks run --layer`."

### azd auth status JSON reports authentication validity (2026-03-26)
- slug: azd-auth-status-json-reports-authentication-validity-dc024c885ca7
- score: 0.91

How to use it:

When an agent workflow needs to validate Azure Developer CLI authentication from JSON, run `azd auth status --output json`; in version 1.23.13, it exits non-zero when unauthenticated and includes `expiresOn` in the JSON output.

Examples:

```
azd auth status --output json
```

- why_it_matters: Validate azd authentication status in an agent workflow that consumes JSON output.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.13>
- gotchas: "Version: 1.23.13"; "--output json: Requests JSON output. The official reference lists `azd auth status` but does not document this flag; its JSON behavior is stated in the 1.23.13 release note."

### azd deploy supports configurable deployment timeouts (2026-03-20)
- slug: azd-deploy-supports-configurable-deployment-timeouts-0049c0f11c7f
- score: 0.96

How to use it:

When setting a timeout for an Azure Developer CLI service, configure `deployTimeout` in that service’s `azure.yaml` entry or pass `--timeout <seconds>` to `azd deploy <service>`. The CLI flag takes precedence over the service setting; the default is 1200 seconds.

Examples:

```
azd deploy <service> --timeout <seconds>
```

```
services:
  - name: <service>
    deployTimeout: <seconds>
```

- why_it_matters: Set a deployment timeout for an Azure Developer CLI service.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.11>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference>, <https://github.com/Azure/azure-dev/blob/azure-dev-cli_1.23.11/cli/azd/internal/cmd/deploy.go>
- gotchas: "Version: 1.23.11"; "<service>: Service to deploy; omit to deploy services listed in `azure.yaml`."; "--timeout <seconds>: Maximum seconds `azd` waits for each service deployment; default is 1200. It stops waiting but does not cancel the Azure-side deployment."; "deployTimeout: Service configuration field in `azure.yaml` for a user-configurable deployment timeout. The release note does not document units, constraints, or subkeys."; "Prerequisite: The target Azure environment must have a subscription configured; the CLI source returns an infrastructure-not-provisioned error if the subscription ID is empty."

### azd provision runs local preflight validation before Bicep deployment (2026-03-13)
- slug: azd-provision-runs-local-preflight-validation-before-bicep-deployment-1f68e1f332ff
- score: 0.91

How to use it:

For a Bicep project, run `azd provision` to run local preflight automatically before deployment is sent to Azure. To disable it, run `azd config set provision.preflight off`.

Examples:

```
azd provision
```

```
azd config set provision.preflight off
```

- why_it_matters: Provision resources from a Bicep deployment while detecting parameter, configuration, or permission issues before submission to Azure.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.9>, <https://github.com/Azure/azure-dev/pull/7053>, <https://github.com/Azure/azure-dev/blob/azure-dev-cli_1.23.9/cli/azd/docs/design/local-preflight-validation.md>
- gotchas: "Version: 1.23.9"; "provision.preflight: User configuration key; set to `off` to disable local preflight."; "off (required): Value used with `provision.preflight` to disable preflight."; "Prerequisite: Local preflight depends on the `bicep snapshot` command, available in modern Bicep CLI versions; the docs do not specify a minimum version."; "Local preflight depends on the `bicep snapshot` command, available in modern Bicep CLI versions."; "Preflight can be disabled by setting `provision.preflight` to `\"off\"` in azd user configuration."

### azd deploy supports Container App Jobs via host: containerapp (2026-03-07)
- slug: azd-deploy-supports-container-app-jobs-via-host-containerapp-e0c4934bde37
- score: 0.98

How to use it:

When deploying a Bicep-defined Container App Job, set the service’s `host` to `containerapp` and define a `Microsoft.App/jobs` resource. Tag that resource with `azd-service-name` matching the service name, then run `azd deploy`.

Examples:

```
services:
  <service>:
    host: containerapp
    language: docker
    project: <project-path>
    docker:
      path: <Dockerfile-path>
      context: <build-context>
```

```
resource job 'Microsoft.App/jobs@2025-02-02-preview' = {
  name: '<job-name>'
  location: location
  tags: {
    'azd-env-name': environmentName
    'azd-service-name': '<service>'
  }
  properties: {
    environmentId: containerAppsEnvironment.id
    configuration: {
      replicaTimeout: 300
      replicaRetryLimit: 1
      triggerType: 'Manual'
      registries: [
        {
          server: containerRegistry.properties.loginServer
          identity: identityId
        }
      ]
    }
    template: {
      containers: [
        {
          image: imageName
          name: 'main'
          resources: {
            cpu: json('0.5')
            memory: '1.0Gi'
          }
        }
      ]
    }
  }
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identityId}': {}
    }
  }
}
```

```
azd deploy
```

- why_it_matters: Deploy a Bicep-defined Container App Job using azd.
- before: Before this feature, `azd deploy` rejected a `Microsoft.App/jobs` target because it expected resource type `Microsoft.App/containerApps`.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.8>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/container-apps-workflows>, <https://github.com/Azure/azure-dev/issues/2743>
- gotchas: "Version: 1.23.8"; "host (required): Set to `containerapp`; this host supports Container App Jobs."; "language: The documented job example sets this to `docker`."; "project: Path to the job service project; the documented example uses `./src/job`."; "docker.path: Path to the Dockerfile; the documented example uses `./Dockerfile`."; "docker.context: Docker build context; the documented example uses `.`."; "Microsoft.App/jobs resource tag `azd-service-name` (required): Must match the service name in azure.yaml so azd can associate the provisioned job with the service."; "Prerequisite: Define the `azure.yaml` job service and provision a `Microsoft.App/jobs` Bicep resource tagged with a matching `azd-service-name`."

### azd env new and azd init add no-prompt defaults (2026-03-07)
- slug: azd-env-new-and-azd-init-add-no-prompt-defaults-e8821f178fe4
- score: 0.92

How to use it:

When setting up a repository, run `azd env new` or `azd init` with `--no-prompt`; azd generates the environment name from the working directory and, when exactly one subscription is available, selects it automatically. The release note says `--environment` is not required for this behavior.

Examples:

```
azd env new --no-prompt
```

```
azd init --no-prompt
```

- why_it_matters: Create or initialize an azd environment in `--no-prompt` mode when setting up a repository.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.8>
- gotchas: "Version: 1.23.8"; "--no-prompt: Suppress prompts; the release note describes automatic environment naming and single-subscription selection in this mode."; "--environment: The release note says the hard requirement for this option is removed."; "Automatic subscription selection is specified only when one subscription is available."; "Docs conflict: Current Microsoft Learn reference documents `azd env new <environment>` with a required positional environment argument and describes `--no-prompt` as using existing values; this is newer-version documentation and differs from the 1.23.8 release note. https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference"

### azd detects pnpm and yarn for JavaScript/TypeScript services (2026-02-28)
- slug: azd-detects-pnpm-and-yarn-for-javascript-typescript-services-e6b12d5ac394
- score: 0.92

How to use it:

For JavaScript/TypeScript services using pnpm or yarn, run `azd package` or deploy with `azd deploy` to let azd detect the package manager. To override detection, set `services.<service>.config.packageManager` in `azure.yaml`.

Examples:

```
azd package
```

```
azd deploy
```

```
services:
  <service>:
    language: js # or ts
    config:
      packageManager: pnpm # npm | pnpm | yarn
```

- why_it_matters: Build or deploy a JavaScript/TypeScript service that uses pnpm or yarn.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.7>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/azd-commands>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/azd-schema>
- gotchas: "Version: 1.23.7"; "services.<service>.config.packageManager: Package manager used for dependency installation; overrides auto-detection from lock files. Allowed values: `npm`, `pnpm`, `yarn`."; "Prerequisite: Applies to JavaScript/TypeScript services (`js` or `ts`)."; "Applies to JavaScript/TypeScript services."

### azd detects pyproject.toml and installs Python projects (2026-02-28)
- slug: azd-detects-pyproject-toml-and-installs-python-projects-7ebaa88de27e
- score: 0.93

How to use it:

If the Python project has `pyproject.toml`, azd detects it and uses `pip install .` when restoring the project for build or deployment. When both `pyproject.toml` and `requirements.txt` exist, `pyproject.toml` takes priority.

Examples:

```
pip install .
```

- why_it_matters: Prepare a Python project with modern packaging for azd build or deployment.
- before: Before this change, azd detected Python projects through `requirements.txt` and restored them with `pip install -r requirements.txt`.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.7>, <https://github.com/Azure/azure-dev/pull/6848>
- gotchas: "Version: 1.23.7"; "Prerequisite: Requires azd 1.23.7 or later for this detection and install support."; "Applies to Python projects using modern project packaging."

### azd init --template supports local directories (2026-02-28)
- slug: azd-init-template-supports-local-directories-95f6507db0a1
- score: 0.98

How to use it:

When iterating on a template in a local directory, pass its path to `azd init --template` to initialize from it without pushing it to a remote repository.

Examples:

```
azd init --template <local-directory-path>
```

- why_it_matters: Iterate on a template stored in a local directory without pushing it to a remote repository.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.7>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/get-started>
- gotchas: "Version: 1.23.7"; "--template, -t <path> (required for this task) (required): Initializes an application from a template; accepts a local directory path, including `./dir`, `../dir`, or an absolute path."; "Prerequisite: Azure Developer CLI (`azd`) installed."; "Docs conflict: Current command reference says `azd init --template` creates a new directory named after the template, with `.` to initialize in the current directory. This behavior may be newer than version 1.23.7; the reference does not state when it changed."

### azd passes environment variables to framework build subprocesses (2026-02-28)
- slug: azd-passes-environment-variables-to-framework-build-subprocesses-13ed65d08755
- score: 0.93

How to use it:

For a non-Docker Node.js, .NET, Java, Python, or SWA service build that needs `azd` environment variables, set the values in `.azure/<env>/.env`; `azd` passes them to framework build subprocesses. Run the applicable `azd` build or deployment workflow for the service.

Examples:

```
azd env set <KEY> <VALUE> --environment <env>
```

```
azd up
```

- why_it_matters: Build a Node.js, .NET, Java, Python, or SWA service that needs azd environment variables during its build.
- before: Previously only Docker builds and hooks received these variables.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.7>, <https://github.com/Azure/azure-dev/pull/6905>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/manage-environment-variables>
- gotchas: "Version: 1.23.7"; "<KEY> (required): Environment variable name to set."; "<VALUE> (required): Value to store for the variable."; "--environment <env>: Selects the named environment whose `.env` file is updated."; "Applies to non-Docker framework service build subprocesses."; "The change depends on #6894 (pnpm/yarn support)."

### azd provision and azd up accept subscription and location flags (2026-02-21)
- slug: azd-provision-and-azd-up-accept-subscription-and-location-flags-ea3643dec664
- score: 0.97

How to use it:

When provisioning or deploying a repository with a specific Azure subscription and location, pass both values to `azd provision` or `azd up`; the flags save them to the environment and skip the selection prompts.

Examples:

```
azd provision --subscription <subscription-id> --location <location>
```

```
azd up --subscription <subscription-id> --location <location>
```

- why_it_matters: Provision or deploy a repository using a specific Azure subscription and location.
- before: Run the command and select a subscription and location at the interactive prompts.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.6>, <https://github.com/Azure/azure-dev/pull/6777>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference>
- gotchas: "Version: 1.23.6"; "--subscription <subscription-id>: Azure subscription ID to use for the environment; the value is saved to that environment."; "--location <location>: Azure location to use for the environment; the value is saved to that environment. Alias: `-l`."; "Prerequisite: Use an `azd` version that includes the flags (introduced in 1.23.6)."; "Prerequisite: Authenticate with Azure and have access to the chosen subscription."

### azd Azure Functions flex consumption apps support remoteBuild (2026-02-13)
- slug: azd-azure-functions-flex-consumption-apps-support-remotebuild-ffb4f3f11107
- score: 0.94

How to use it:

For an Azure Functions Flex Consumption app, set `remoteBuild: true` on its service in `azure.yaml` to build the deployment package remotely with Oryx.

Examples:

```
services:
  <service-name>:
    project: <project-path>
    language: <language>
    host: function
    remoteBuild: true
```

- why_it_matters: Configure an Azure Functions flex consumption app to use remote builds.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.5>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/azd-schema>, <https://github.com/Azure/azure-dev/blob/main/schemas/v1.0/azure.yaml.json>
- gotchas: "Version: 1.23.5"; "services.<service-name>.remoteBuild: Boolean; `true` builds the function deployment package remotely using Oryx; `false` deploys the package as-is. If omitted, defaults to true for JavaScript, TypeScript, and Python function apps."; "services.<service-name>.host (required): Set to `function`; `remoteBuild` is only valid for function services."; "services.<service-name>.project (required): Path to the service source directory; function services using source projects require this instead of `image`."; "Prerequisite: Use azd 1.23.5 or later for the option introduced in that release."; "Applies to Azure Functions flex consumption apps."; "Docs conflict: The current schema reference describes `remoteBuild` as a general remote image build option. The release note and function-specific schema describe it for function app package builds; this answer follows the release note’s function-app context."

### azd CLI JSON output supports JMESPath queries (2026-02-10)
- slug: azd-cli-json-output-supports-jmespath-queries-82c64db31fb6
- score: 0.96

How to use it:

When an `azd` command emits JSON, pass a JMESPath expression to `--query` to select fields. The release note documents the flag, but I couldn’t find an official `azd` command example at version 1.23.4.

- why_it_matters: Filter JSON output from an azd CLI command to inspect selected fields.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.4>
- gotchas: "Version: 1.23.4"; "--query <JMESPath expression>: The release note says this flag adds JMESPath query support for JSON output; the exact `azd` syntax and behavior are not documented on a usable official `azd` page I found."

### azd automatically enables no-prompt mode for detected coding agents (2026-01-30)
- slug: azd-automatically-enables-no-prompt-mode-for-detected-coding-agents-6f0fc4a27b23
- score: 0.95

How to use it:

When `azd` detects an AI-agent environment, it enables no-prompt mode automatically. Run the `azd` command you need; pass `--no-prompt` to request no-prompt mode explicitly.

Examples:

```
azd <command> [args...]
```

```
azd <command> [args...] --no-prompt
```

- why_it_matters: When running azd from a supported AI coding agent, automate azd commands without interactive prompts.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.3>, <https://github.com/Azure/azure-dev/pull/6633>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference>
- gotchas: "Version: 1.23.3"; "--no-prompt: Runs without prompts, using existing values; fails if a required value or decision cannot be resolved automatically."; "Detection covers 15+ AI agents, including Claude Code, GitHub Copilot, Cursor, Windsurf, Gemini CLI, Amazon Q, and Aider."; "Detection uses environment variables, `AZURE_DEV_USER_AGENT` parsing, and parent process tree walking."; "Cross-platform support is stated for Windows, Linux, and macOS."; "Docs conflict: The current reference documents `AZD_NON_INTERACTIVE=false` to opt out of automatic no-prompt enablement. The card says to use `--no-prompt=false`; the current documentation does not confirm that override syntax."

### azd env remove deletes local environment configuration files (2026-01-23)
- slug: azd-env-remove-deletes-local-environment-configuration-files-f25839544558
- score: 0.96

How to use it:

When you need to remove an azd environment, run `azd env remove <environment>` to remove it. Add `--force` to skip the confirmation prompt.

Examples:

```
azd env remove <environment> [--force]
```

- why_it_matters: Remove a local environment configuration from an azd project.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.1>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference>
- gotchas: "Version: 1.23.1"; "<environment> (required): Name of the environment to remove."; "--force: Skips confirmation before removal."

### azd auto-detects Bicep or Terraform from infra files (2026-01-15)
- slug: azd-auto-detects-bicep-or-terraform-from-infra-files-0138d1ccfdec
- score: 0.95

How to use it:

When `infra.provider` is unset, run `azd provision` to provision from the project’s infrastructure files; for automatic Bicep or Terraform detection, use azd v1.23.0 or later. If both file types are present, set `infra.provider` explicitly.

Examples:

```
azd provision
```

```
infra:
  provider: <bicep|terraform>
```

- why_it_matters: Provision a project with Bicep or Terraform files when `infra.provider` is unset in `azure.yaml`.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.0>, <https://github.com/Azure/azure-dev/pull/6461>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/azd-commands>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/azd-schema>, <https://github.com/Azure/azure-dev/blob/azure-dev-cli_1.23.0/cli/azd/pkg/project/importer.go>
- gotchas: "Version: 1.23.0"; "infra.provider: Infrastructure provisioning provider; documented values include `bicep` and `terraform`."; "Prerequisite: Use Azure Developer CLI v1.23.0 or later for the release-note-described auto-detection."; "Prerequisite: `azure.yaml` belongs at the project root and configures project infrastructure; the `infra` directory contains infrastructure files."; "Detection scans the infra directory and ignores subdirectories."; "If both Bicep and Terraform file types are present, explicit configuration is required."; "Docs conflict: The current schema docs state that the default provider is Bicep; they do not document the v1.23.0 file-based auto-detection behavior. The v1.23.0 source is the version-specific evidence for that behavior."

### azd uses Podman when Docker is unavailable (2026-01-15)
- slug: azd-uses-podman-when-docker-is-unavailable-1c2ff3ed8af7
- score: 0.97

How to use it:

When running azd container functionality, azd checks Docker first and falls back to Podman. Set `AZD_CONTAINER_RUNTIME` to `podman` or `docker` to choose explicitly.

Examples:

```
azd provision
```

```
AZD_CONTAINER_RUNTIME=podman azd provision
```

```
AZD_CONTAINER_RUNTIME=docker azd provision
```

- why_it_matters: Run azd container functionality in a development environment where Podman is installed and Docker is unavailable.
- before: Previously, azd required Docker for container functionality; without Docker, running `azd provision` failed its external-tool check.
- sources: <https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.23.0>, <https://github.com/Azure/azure-dev/pull/6436>, <https://github.com/Azure/azure-dev/blob/azure-dev-cli_1.23.0/cli/azd/pkg/tools/docker/docker.go>, <https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference>
- gotchas: "Version: 1.23.0"; "AZD_CONTAINER_RUNTIME: Selects the container runtime; documented values are `docker` and `podman`."; "azd provision [<layer>] [flags]: Provisions Azure resources for the project; `<layer>` and flags are optional."; "Prerequisite: The selected runtime must be installed and its service running. Minimum versions: Docker 17.09 or Podman 3.0."; "Docker 17.09+ or Podman 3.0+ is required."; "Cross-platform support applies on platforms where Podman is supported."