You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
fix(extensions): propagate cancellation across process and RPC boundaries - #10353
Propagate cancellation end to end across azd commands, foreground extension processes, unary gRPC calls, extension-started workflows, and long-lived extension listener streams.
gives each top-level azd command one scoped Ctrl+C owner and cancellation context
gives direct extension commands deterministic process-tree cleanup on Windows and bounded graceful shutdown on POSIX
transports request-specific cancellation through bidirectional listener streams without closing the stream
makes provider registrations and provider operations request-scoped; only lifecycle subscriptions retain stream lifetime
protects stable request correlation from late responses after unacknowledged cancellation
preserves cancellation and deadline identity through process, workflow, gRPC, scripting, and extension-error wrappers
classifies user cancellation consistently as user.canceled and deadlines as internal.timeout
Root cause
Cancellation previously stopped at several ownership boundaries:
Ctrl+C did not consistently cancel one top-level azd operation; multiple console instances could observe the same signal, and redirected output could fall back to an abrupt process exit.
Foreground extension process termination was not coordinated with extension SDK context cancellation, process-tree cleanup, or final error reporting.
Listener invocations could inherit the long-lived stream context, so canceling the command did not target the matching remote handler.
MessageBroker.SendAndWait stopped waiting locally but did not notify the other process, allowing remote work to continue.
Late responses could collide with reused stable request IDs.
Process, workflow, gRPC, and structured-extension wrappers could hide cancellation behind ext.run.failed, tool failures, or gRPC Internal errors.
Cancellation design
Surface
Current behavior
Top-level azd command
CancellationMiddleware runs outside loginGuard, owns Ctrl+C, and cancels one command context, including implicit login work.
Foreground extension on Linux/macOS
The terminal sends SIGINT to azd and the extension. The Extension SDK cancels its root context; azd allows up to 3 seconds for cleanup, then force-terminates the extension. A later Ctrl+C forces termination sooner.
Foreground extension on Windows
azd cancels the invocation immediately and terminates the extension Job Object, including descendants. azd remains alive to join the process, classify the result, and flush telemetry.
Unary gRPC
Native gRPC context propagation cancels only the matching RPC and server handler.
Extension-started workflow
WorkflowService.Run preserves the runner error chain. Cancellation and deadlines pass through the canonical host gRPC serializer before ordinary failures fall back to Internal.
Listener lifecycle/provider request
The local invocation context cancels; MessageBroker sends a control message with the same request ID; the remote broker cancels only the matching handler context.
Cancellation acknowledgment
The handler's final response acknowledges cancellation. Beta SDK replies keep cancellation inside the project/service handler status so host validation accepts the response and the stream remains open. The caller waits at most 1 second and then returns its original cancellation cause.
Provider registration
Registration and later provider operations use request-scoped contexts and are independently cancellable in either direction.
Lifecycle subscription
Only subscription messages retain the stream context because the registration must live until the listener stream closes.
Correlation safety
Beta requests use UUIDs. Stable deterministic keys use the configured listener identity and are serialized; an unacknowledged cancellation poisons the key until the broker closes.
Listener shutdown
Stop gRPC, wait up to 2 seconds, cancel remaining listener processes, then wait up to another 2 seconds.
Final classification
context.Canceled, terminal interruption, gRPC Canceled, structured extension user/canceled, and interrupted extension processes converge on user.canceled. Deadlines converge on internal.timeout.
No protobuf or generated contract files change under stable v1 or preview v1beta.
Cancellation uses existing request IDs and error/status fields.
Stable lifecycle messages use the existing handler-status envelope for cancellation control.
Beta host-to-SDK cancellation uses an error-only control message; the SDK acknowledgment keeps cancellation inside the existing project/service handler status.
Other broker envelopes use an error-only message with the matching request ID.
Older extensions can ignore the control message safely; azd stops waiting after the bounded acknowledgment period.
The stable extension facade remains unchanged.
Relationship to extension telemetry
PR #10068 controls extension-emitted ext.usage events. This PR does not change that API. It fixes cancellation of host-observed extension work and ensures the enclosing ext.run or cmd.* span uses the same user.canceled classification as existing azd Ctrl+C paths.
Validation
Current PR head: 0286dcb84705a0275058a429406652f5202079a1
Current-head validation:
go test ./internal/grpcserver -count=1
table-driven WorkflowService.Run regression coverage for direct, wrapped, existing-gRPC, and joined cancellation/deadline errors
verifies cancellation takes precedence over another joined failure, including environment.ErrExists
verifies structured extension details deserialize to canonical context.Canceled or context.DeadlineExceeded
verifies ordinary failures remain Internal and environment.ErrExists remains AlreadyExists
verifies stable event request and response keys use the configured listener identity when caller claims identify another extension
verifies command cancellation is registered before loginGuard while telemetry and error middleware remain outside it
verifies beta SDK cancellation responses put structured cancellation in nested project/service handler status and leave the forbidden top-level error unset
runs the actual public ExtensionHost against the real beta stream validator, cancels one service invocation, and completes a second invocation on the same stream
The cross-platform process and broker behavior below was live-tested on parent commit 4fa448ac24c0468cd531de1498ca20573d45abde. Subsequent commits refine workflow error mapping, stable listener correlation identity, middleware ordering, beta handler cancellation acknowledgments, and regression coverage without changing process or broker cancellation transport.
Platform and case
Cancellation evidence
Final telemetry
Exit after signal
Windows foreground extension: azd canceltest wait
One real CTRL_C_EVENT; extension Job Object terminated; no orphaned azd or extension process
ext.run = user.canceled
54 ms
Windows listener lifecycle: azd package web
Remote handler recorded provider-canceled:context canceled; stream cancellation was acknowledged; no orphaned process
cmd.package = user.canceled
57 ms
Windows core control: azd hooks run preprovision
Command context canceled while the hook was running
cmd.hooks.run = user.canceled
84 ms
Linux foreground extension under WSL
SIGINT sent to the shared process group; extension recorded direct-canceled:interrupt signal received before exit
Windows foreground cancellation is deterministic but not cooperative: the extension does not currently receive a host-to-extension cancellation request before Job Object termination, so extension cleanup code is not guaranteed to run.
A legacy or misbehaving listener handler may ignore cancellation. azd stops waiting after 1 second and protects stable correlation keys, but cannot forcibly stop one goroutine without shutting down the listener process.
Azure Pipelines:
Successfully started running 1 pipeline(s).
24 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.
Keep broker response delivery from blocking unrelated messages, classify interrupted tools as user cancellations, and isolate Cobra tests from go test flags.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Avoid retaining the global interrupt handler after a nested controller has already claimed cancellation, and preserve deadline causes from extension invocation contexts.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Preserve deadline causes in command cancellation middleware
cli/azd/cmd/middleware/middleware.go:61
Use context.Cause(commandCtx) to preserve deadline causes. If a WithCancelCause parent is canceled with context.DeadlineExceeded, commandCtx.Err() is context.Canceled. Even when nextFn returns the correct deadline, this middleware joins in cancellation, so ordinary command errors classify as user.canceled instead of internal.timeout. Preserve the cause and replace an exact generic commandCtx.Err() result rather than joining it, as Runner.Invoke already does. Add regression cases where nextFn returns the deadline, nil, or the generic context error.
Also recognize terminal.InterruptErr in this cancellation branch. input.Console returns that sentinel for prompt cancellation (pkg/input/console_ux.go:29–31), and raw-mode Ctrl+C need not generate an OS signal. WrapError currently serializes it as an unspecified error, so azdext.Run exits with code 1 and the host can still classify the cancellation as ext.run.failed. Import the survey terminal package and include errors.Is(err, terminal.InterruptErr) in this condition. Add a round-trip regression for a wrapped prompt interrupt.
Include terminal.InterruptErr in this cancellation branch. Local input.Console prompts return that sentinel (pkg/input/console_ux.go:27–32), and keyboard cancellation need not produce an OS signal that cancels the SDK root context. WrapError currently serializes it as an unclassified error, losing its cancellation identity and causing the host to record an extension failure instead of user.canceled. Import the survey terminal package, extend this condition with errors.Is(err, terminal.InterruptErr), and add direct and wrapped-sentinel round-trip tests.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Cross-platform process termination, signal-order races, and shared-stream cancellation require final maintainer review despite the regression coverage.
title: Azure Developer CLI reference
description: This article explains the syntax and parameters for the various Azure Developer CLI commands.
author: alexwolfmsft
ms.author: alexwolf
ms.date: 10/19/2026
ms.service: azure-dev-cli
ms.topic: reference
ms.custom: devx-track-azdevcli
Azure Developer CLI reference
This article explains the syntax and parameters for the various Azure Developer CLI commands.
azd
The Azure Developer CLI (azd) is an open-source tool that helps onboard and manage your project on Azure
Options
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--docs Opens the documentation for azd in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for azd.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
azd version: Print the version number of Azure Developer CLI.
azd add
Add a component to your project.
azd add [flags]
Options
--docs Opens the documentation for azd add in your web browser.
-h, --help Gets help for add.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd auth in your web browser.
-h, --help Gets help for auth.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
When run without any arguments, log in interactively using a browser. To log in using a device code, pass
--use-device-code.
To log in as a service principal, pass --client-id and --tenant-id as well as one of: --client-secret,
--client-certificate, or --federated-credential-provider.
To log in using a managed identity, pass --managed-identity, which will use the system assigned managed identity.
To use a user assigned managed identity, pass --client-id in addition to --managed-identity with the client id of
the user assigned managed identity you wish to use.
When already logged in, azd automatically clears cached authentication data (such as stale tokens)
before re-authenticating. This ensures a clean login state and prevents issues with expired or
corrupted cached credentials.
azd auth login [flags]
Options
--check-status Checks the log-in status instead of logging in.
--client-certificate string The path to the client certificate for the service principal to authenticate with.
--client-id string The client id for the service principal to authenticate with.
--client-secret string The client secret for the service principal to authenticate with. Set to the empty string to read the value from the console.
--docs Opens the documentation for azd auth login in your web browser.
--federated-credential-provider string The provider to use to acquire a federated token to authenticate with. Supported values: github, azure-pipelines, oidc
-h, --help Gets help for login.
--managed-identity Use a managed identity to authenticate.
--redirect-port int Choose the port to be used as part of the redirect URI during interactive login.
--tenant-id string The tenant id or domain name to authenticate with.
--use-device-code[=true] When true, log in by using a device code instead of a browser.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd auth logout in your web browser.
-h, --help Gets help for logout.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Display whether you are logged in to Azure and the associated account information.
azd auth status [flags]
Options
--docs Opens the documentation for azd auth status in your web browser.
-h, --help Gets help for status.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
The completion command allows you to generate autocompletion scripts for your shell,
currently supports bash, zsh, fish and PowerShell.
See each sub-command's help for details on how to use the generated script.
Options
--docs Opens the documentation for azd completion in your web browser.
-h, --help Gets help for completion.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd completion bash in your web browser.
-h, --help Gets help for bash.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd completion fig in your web browser.
-h, --help Gets help for fig.
--include-help-subcommands Include subcommands under the help command in the Fig spec
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd completion fish in your web browser.
-h, --help Gets help for fish.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd completion powershell in your web browser.
-h, --help Gets help for powershell.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd completion zsh in your web browser.
-h, --help Gets help for zsh.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Manage the Azure Developer CLI user configuration, which includes your default Azure subscription and location.
Available since azure-dev-cli_0.4.0-beta.1.
The easiest way to configure azd for the first time is to run azd init. The subscription and location you select will be stored in the config.json file located in the config directory. To configure azd anytime afterwards, you'll use azd config set.
The default value of the config directory is:
$HOME/.azd on Linux and macOS
%USERPROFILE%.azd on Windows
The configuration directory can be overridden by specifying a path in the AZD_CONFIG_DIR environment variable.
Options
--docs Opens the documentation for azd config in your web browser.
-h, --help Gets help for config.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
The configuration directory can be overridden by specifying a path in the AZD_CONFIG_DIR environment variable.
azd config get <path> [flags]
Options
--docs Opens the documentation for azd config get in your web browser.
-h, --help Gets help for get.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Display the list of available features in alpha stage.
azd config list-alpha [flags]
Options
--docs Opens the documentation for azd config list-alpha in your web browser.
-h, --help Gets help for list-alpha.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
List all possible configuration settings that can be set with azd, including descriptions and allowed values.
azd config options [flags]
Options
--docs Opens the documentation for azd config options in your web browser.
-h, --help Gets help for options.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Resets all configuration in the configuration path.
The default value of the config directory is:
$HOME/.azd on Linux and macOS
%USERPROFILE%\.azd on Windows
The configuration directory can be overridden by specifying a path in the AZD_CONFIG_DIR environment variable to the default.
azd config reset [flags]
Options
--docs Opens the documentation for azd config reset in your web browser.
-f, --force Force reset without confirmation.
-h, --help Gets help for reset.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
The configuration directory can be overridden by specifying a path in the AZD_CONFIG_DIR environment variable.
azd config set <path> <value> [flags]
Examples
azd config set defaults.subscription <yourSubscriptionID>
azd config set defaults.location eastus
Options
--docs Opens the documentation for azd config set in your web browser.
-h, --help Gets help for set.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Show all configuration values in the configuration path.
The default value of the config directory is:
$HOME/.azd on Linux and macOS
%USERPROFILE%\.azd on Windows
The configuration directory can be overridden by specifying a path in the AZD_CONFIG_DIR environment variable.
azd config show [flags]
Options
--docs Opens the documentation for azd config show in your web browser.
-h, --help Gets help for show.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Manage subscription filters for tenant-scoped subscription prompts.
Synopsis
Manage per-tenant subscription filters that control which subscriptions are shown during interactive prompts.
Filters are stored locally in your user configuration and apply per-device.
Options
--docs Opens the documentation for azd config sub-filter in your web browser.
-h, --help Gets help for sub-filter.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Remove the subscription filter for a tenant so that all subscriptions are shown during prompts.
azd config sub-filter remove [flags]
Options
--docs Opens the documentation for azd config sub-filter remove in your web browser.
-h, --help Gets help for remove.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
See also
azd config sub-filter: Manage subscription filters for tenant-scoped subscription prompts.
Select which subscriptions to include when prompted for a subscription under a specific tenant.
If a filter already exists, the previously selected subscriptions are pre-checked.
azd config sub-filter set [flags]
Options
--docs Opens the documentation for azd config sub-filter set in your web browser.
-h, --help Gets help for set.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
See also
azd config sub-filter: Manage subscription filters for tenant-scoped subscription prompts.
Removes a configuration in the configuration path.
The default value of the config directory is:
$HOME/.azd on Linux and macOS
%USERPROFILE%\.azd on Windows
The configuration directory can be overridden by specifying a path in the AZD_CONFIG_DIR environment variable.
azd config unset <path> [flags]
Examples
azd config unset defaults.location
Options
--docs Opens the documentation for azd config unset in your web browser.
-h, --help Gets help for unset.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd copilot in your web browser.
-h, --help Gets help for copilot.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd copilot consent in your web browser.
-h, --help Gets help for consent.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
This command creates consent rules that allow tools to execute
without prompting for permission. You can specify different permission
levels and scopes for the rules.
Examples: Grant always permission to all tools globally
azd copilot consent grant --global --permission always
Grant project permission to a specific tool with read-only scope
azd copilot consent grant --server my-server --tool my-tool --permission project --scope read-only
azd copilot consent grant [flags]
Options
--action string Action type: 'all' or 'readonly' (default "all")
--docs Opens the documentation for azd copilot consent grant in your web browser.
--global Apply globally to all servers
-h, --help Gets help for grant.
--operation string Operation type: 'tool' or 'sampling' (default "tool")
--permission string Permission: 'allow', 'deny', or 'prompt' (default "allow")
--scope string Rule scope: 'global', or 'project' (default "global")
--server string Server name
--tool string Specific tool name (requires --server)
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--action string Action type to filter by (all, readonly)
--docs Opens the documentation for azd copilot consent list in your web browser.
-h, --help Gets help for list.
--operation string Operation to filter by (tool, sampling)
--permission string Permission to filter by (allow, deny, prompt)
--scope string Consent scope to filter by (global, project). If not specified, lists rules from all scopes.
--target string Specific target to operate on (server/tool format)
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--action string Action type to filter by (all, readonly)
--docs Opens the documentation for azd copilot consent revoke in your web browser.
-h, --help Gets help for revoke.
--operation string Operation to filter by (tool, sampling)
--permission string Permission to filter by (allow, deny, prompt)
--scope string Consent scope to filter by (global, project). If not specified, revokes rules from all scopes.
--target string Specific target to operate on (server/tool format)
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--all Deploys all services that are listed in azure.yaml
--docs Opens the documentation for azd deploy in your web browser.
-e, --environment string The name of the environment to use.
--from-package string Deploys the packaged service located at the provided path. Supports zipped file packages (file path) or container images (image tag).
-h, --help Gets help for deploy.
--preview Preview changes to services without deploying them.
--timeout int Maximum time in seconds for azd to wait for each service deployment. This stops azd from waiting but does not cancel the Azure-side deployment. (default: 1200) (default 1200)
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd down in your web browser.
-e, --environment string The name of the environment to use.
--force Does not require confirmation before it deletes resources.
-h, --help Gets help for down.
--purge Does not require confirmation before it permanently deletes resources that are soft-deleted by default (for example, key vaults).
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd env in your web browser.
-h, --help Gets help for env.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
See also
azd env config: Manage environment configuration (ex: stored in .azure/{environment}/config.json).
Manage environment configuration (ex: stored in .azure/{environment}/config.json).
Options
--docs Opens the documentation for azd env config in your web browser.
-h, --help Gets help for config.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Gets a configuration value from the environment's config.json file.
azd env config get <path> [flags]
Options
--docs Opens the documentation for azd env config get in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for get.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
See also
azd env config: Manage environment configuration (ex: stored in .azure/{environment}/config.json).
Sets a configuration value in the environment's config.json file.
Values are automatically parsed as JSON types when possible. Booleans (true/false),
numbers (42, 3.14), arrays ([...]), and objects ({...}) are stored with their native
JSON types. Plain text values are stored as strings. To force a JSON-typed value to be
stored as a string, wrap it in JSON quotes (e.g. '"true"' or '"8080"').
azd env config set <path> <value> [flags]
Examples
azd env config set myapp.endpoint https://example.com
azd env config set myapp.debug true
azd env config set myapp.count 42
azd env config set infra.parameters.tags '{"env":"dev"}'
azd env config set myapp.port '"8080"'
Options
--docs Opens the documentation for azd env config set in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for set.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
See also
azd env config: Manage environment configuration (ex: stored in .azure/{environment}/config.json).
Removes a configuration value from the environment's config.json file.
azd env config unset <path> [flags]
Examples
azd env config unset myapp.endpoint
Options
--docs Opens the documentation for azd env config unset in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for unset.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
See also
azd env config: Manage environment configuration (ex: stored in .azure/{environment}/config.json).
--docs Opens the documentation for azd env get-value in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for get-value.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd env get-values in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for get-values.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd env list in your web browser.
-h, --help Gets help for list.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Create a new environment and set it as the default.
azd env new <environment> [flags]
Options
--docs Opens the documentation for azd env new in your web browser.
-h, --help Gets help for new.
-l, --location string Azure location for the new environment
--subscription string ID of an Azure subscription to use for the new environment
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Refresh environment values by using information from a previous infrastructure provision.
azd env refresh <environment> [flags]
Options
--docs Opens the documentation for azd env refresh in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for refresh.
--hint string Hint to help identify the environment to refresh
--layer string Provisioning layer to refresh the environment from.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd env remove in your web browser.
-e, --environment string The name of the environment to use.
--force Skips confirmation before performing removal.
-h, --help Gets help for remove.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd env select in your web browser.
-h, --help Gets help for select.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd env set in your web browser.
-e, --environment string The name of the environment to use.
--file string Path to .env formatted file to load environment values from.
-h, --help Gets help for set.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Set a name as a reference to a Key Vault secret in the environment.
Synopsis
You can either create a new Key Vault secret or select an existing one.
The provided name is the key for the .env file which holds the secret reference to the Key Vault secret.
azd env set-secret <name> [flags]
Options
--docs Opens the documentation for azd env set-secret in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for set-secret.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Execute commands and scripts with azd environment context.
Synopsis
Execute commands and scripts with full access to azd environment variables.
Commands are run with the azd environment loaded into the child process.
Multiple arguments use direct process execution (no shell wrapping).
A single quoted argument uses shell inline execution unless it is ambiguous
with a missing script path. Use --shell to make inline intent explicit when
the command contains script-like path arguments.
Examples:
azd exec python script.py # Direct exec (exact argv)
azd exec npm run dev # Direct exec (no shell)
azd exec -- python app.py --port 8000 # Direct exec with flags
azd exec 'echo $AZURE_ENV_NAME' # Inline via shell
azd exec ./setup.sh # Execute script file
azd exec --shell pwsh "Write-Host 'Hello'" # Inline PowerShell
azd exec ./build.sh -- --verbose # Script with args
azd exec -i ./init.sh # Interactive mode
--docs Opens the documentation for azd exec in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for exec.
-i, --interactive Run in interactive mode (connect stdin)
-s, --shell string Shell to use (bash, sh, zsh, pwsh, powershell, cmd). Auto-detected if not specified. Also disambiguates inline commands that contain script-like path arguments.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd extension in your web browser.
-h, --help Gets help for extension.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Installs one or more extensions by id from a registered extension source.
The --source flag also accepts a registry location (URL or file path). When a
location is given, azd registers it as a source (prompting for a name, and
confirming first for a URL) and then installs from it. If the location is already
registered, azd reuses that source.
You can also pass a self-contained extension bundle as a local .zip path or an
https URL. Remote URLs may be shortened or opaque. azd follows redirects
automatically and warns when a download redirects from HTTPS to HTTP. Bundle
installs aren't tracked for updates; install a newer bundle to update.
--docs Opens the documentation for azd extension install in your web browser.
-f, --force Force installation, including downgrades and reinstalls
-h, --help Gets help for install.
--no-dependencies Install only the specified extension(s) without installing their declared dependencies
-s, --source string The extension source to use for installs. Accepts a registered source name or a registry location (URL or file path) to register and install from.
-v, --version string The version of the extension to install. Cannot be used with an extension bundle
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
List available extensions from registered extension sources.
The --source flag accepts a registered source name or registry location (URL or
file path). Locations are queried read-only and are not registered. Extensions
from an unregistered location show the location itself in the SOURCE column.
azd extension list [--installed] [flags]
Options
--docs Opens the documentation for azd extension list in your web browser.
-h, --help Gets help for list.
--installed List installed extensions
-s, --source string Filter extensions by registered source name or registry location (URL or file path).
--tags strings Filter extensions by tags
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Includes version compatibility, dependencies, and installed dependents.
Uses installed metadata when no registry lists the extension, or a registry lookup fails without --source.
azd extension show <extension-id> [flags]
Options
--docs Opens the documentation for azd extension show in your web browser.
-h, --help Gets help for show.
-s, --source string The registered source name or registry location (URL or file path) to use.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd extension source in your web browser.
-h, --help Gets help for source.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Names must contain 1-64 lowercase ASCII letters, digits, hyphens, or underscores, and must begin and end with a letter or digit. The name 'bundle' is reserved.
azd extension install --source and azd extension update --source also accept a registry URL or file path directly.
azd extension source add [flags]
Options
--docs Opens the documentation for azd extension source add in your web browser.
-h, --help Gets help for add.
-l, --location string The location of the extension source
-n, --name string The source name: 1-64 lowercase letters, digits, hyphens, or underscores.
-t, --type string The type of the extension source. Supported types are 'file' and 'url'
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd extension source list in your web browser.
-h, --help Gets help for list.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Remove an extension source with the specified name
azd extension source remove <name> [flags]
Options
--docs Opens the documentation for azd extension source remove in your web browser.
-h, --help Gets help for remove.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Validate an extension source's registry.json file.
Synopsis
Validate an extension source's registry.json file.
Accepts a source name (from 'azd extension source list'), a local file path,
or a URL. Checks required fields, valid capabilities, semver version format,
platform artifact structure, and extension ID format.
--docs Opens the documentation for azd extension source validate in your web browser.
-h, --help Gets help for validate.
--strict Enable strict validation (require checksums)
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Also removes unused dependency installs after confirmation.
Use --no-dependencies to keep them; --no-prompt accepts their removal.
Required extensions cannot be removed unless their dependents are also removed
or --force is set.
azd extension uninstall [extension-id...] [flags]
Options
--all Uninstall all installed extensions
--docs Opens the documentation for azd extension uninstall in your web browser.
-f, --force Uninstall even if other installed extensions depend on it
-h, --help Gets help for uninstall.
--no-dependencies Keep dependencies installed for the removed extensions
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Update installed extensions to the latest version.
Synopsis
Also updates installed dependencies to compatible versions unless
--no-dependency-updates is set.
Failures return a nonzero exit code. Other extensions continue updating;
completed updates are kept.
azd extension update [extension-id] [flags]
Options
--all Update all installed extensions
--docs Opens the documentation for azd extension update in your web browser.
-h, --help Gets help for update.
--no-dependency-updates Do not update dependencies when updating an extension that has dependencies
-s, --source string The registered source name or registry location (URL or file path) to use for updates.
-v, --version string The version of the extension to update to
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd hooks in your web browser.
-h, --help Gets help for hooks.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
See also
azd hooks run: Runs the specified hook for the project, provisioning layers, and services
Runs the specified hook for the project, provisioning layers, and services
azd hooks run <name> [flags]
Options
--docs Opens the documentation for azd hooks run in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for run.
--layer string Only runs hooks for the specified provisioning layer.
--platform string Forces hooks to run for the specified platform.
--service string Only runs hooks for the specified service.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
See also
azd hooks: Develop, test and run hooks for a project.
--docs Opens the documentation for azd infra in your web browser.
-h, --help Gets help for infra.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
See also
azd infra generate: Write IaC for your project to disk, allowing you to manually manage it.
Write IaC for your project to disk, allowing you to manually manage it.
azd infra generate [flags]
Options
--docs Opens the documentation for azd infra generate in your web browser.
-e, --environment string The name of the environment to use.
--force Overwrite any existing files without prompting
-h, --help Gets help for generate.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
See also
azd infra: Manage your Infrastructure as Code (IaC).
When used with --template, a new directory is created (named after the template)
and the project is initialized inside it — similar to git clone.
Pass "." as the directory to initialize in the current directory instead.
Re-running init in an initialized project is idempotent: the existing environment is
reused instead of failing. With --no-prompt and no -e, the recorded default environment
is reused.
azd init [flags]
Options
-b, --branch string The template branch to initialize from. Must be used with a template argument (--template or -t).
--docs Opens the documentation for azd init in your web browser.
-e, --environment string The name of the environment to use.
-f, --filter strings The tag(s) used to filter template results. Supports comma-separated values.
--from-code Initializes a new application from your existing code.
-h, --help Gets help for init.
-l, --location string Azure location for the new environment
-m, --minimal Initializes a minimal project.
-s, --subscription string ID of an Azure subscription to use for the new environment
-t, --template string Initializes a new application from a template. You can use a Full URI, <owner>/<repository>, <repository> if it's part of the azure-samples organization, or a local directory path (./dir, ../dir, or absolute path).
--up Provision and deploy to Azure after initializing the project from a template.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Manage Model Context Protocol (MCP) server. (Alpha)
Options
--docs Opens the documentation for azd mcp in your web browser.
-h, --help Gets help for mcp.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
This command starts an MCP server that can be used by MCP clients to access
azd functionality through the Model Context Protocol interface.
azd mcp start [flags]
Options
--docs Opens the documentation for azd mcp start in your web browser.
-h, --help Gets help for start.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
See also
azd mcp: Manage Model Context Protocol (MCP) server. (Alpha)
--docs Opens the documentation for azd monitor in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for monitor.
--live Open a browser to Application Insights Live Metrics. Live Metrics is currently not supported for Python apps.
--logs Open a browser to Application Insights Logs.
--overview Open a browser to Application Insights Overview Dashboard.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Packages the project's code to be deployed to Azure.
azd package <service> [flags]
Options
--all Packages all services that are listed in azure.yaml
--docs Opens the documentation for azd package in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for package.
--output-path string File or folder path where the generated packages will be saved.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd pipeline in your web browser.
-h, --help Gets help for pipeline.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
See also
azd pipeline config: Configure your deployment pipeline to connect securely to Azure. (Beta)
Configure your deployment pipeline to connect securely to Azure. (Beta)
azd pipeline config [flags]
Options
-m, --applicationServiceManagementReference string Service Management Reference. References application or service contact information from a Service or Asset Management database. This value must be a Universally Unique Identifier (UUID). You can set this value globally by running azd config set pipeline.config.applicationServiceManagementReference <UUID>.
--auth-type string The authentication type used between the pipeline provider and Azure for deployment. Valid values: federated, client-credentials. Both the GitHub and Azure DevOps providers default to federated (OIDC) credentials.
--docs Opens the documentation for azd pipeline config in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for config.
--principal-id string The client id of the service principal to use to grant access to Azure resources as part of the pipeline.
--principal-name string The name of the service principal to use to grant access to Azure resources as part of the pipeline.
--principal-role stringArray The roles to assign to the service principal. By default the service principal will be granted the Contributor and User Access Administrator roles. (default [Contributor,User Access Administrator])
--provider string The pipeline provider to use (github for Github Actions and azdo for Azure Pipelines).
--remote-name string The name of the git remote to configure the pipeline to run on. (default "origin")
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
See also
azd pipeline: Manage and configure your deployment pipelines.
--docs Opens the documentation for azd provision in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for provision.
-l, --location string Azure location for the new environment
--no-state (Bicep only) Forces a fresh deployment based on current Bicep template files, ignoring any stored deployment state.
--preview Preview changes to Azure resources.
--subscription string ID of an Azure subscription to use for the new environment
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Publish a service image or reuse an existing passthrough image.
azd publish <service> [flags]
Options
--all Publishes all services that are listed in azure.yaml
--docs Opens the documentation for azd publish in your web browser.
-e, --environment string The name of the environment to use.
--from-package string Publishes the service from a container image (image tag).
-h, --help Gets help for publish.
--to string The target container image in the form '[registry/]repository[:tag]' to publish to.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--all Restores all services that are listed in azure.yaml
--docs Opens the documentation for azd restore in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for restore.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Display information about your project and its resources.
azd show [resource-name|resource-id] [flags]
Options
--docs Opens the documentation for azd show in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for show.
--show-secrets Unmask secrets in output.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd template in your web browser.
-h, --help Gets help for template.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd template list in your web browser.
-f, --filter strings The tag(s) used to filter template results. Supports comma-separated values.
-h, --help Gets help for list.
-s, --source string Filters templates by source.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd template show in your web browser.
-h, --help Gets help for show.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd template source in your web browser.
-h, --help Gets help for source.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Adds an azd template source with the specified key. (Beta)
Synopsis
The key can be any value that uniquely identifies the template source, with well-known values being:
・default: Default templates
・awesome-azd: Templates from https://aka.ms/awesome-azd
azd template source add <key> [flags]
Options
--docs Opens the documentation for azd template source add in your web browser.
-h, --help Gets help for add.
-l, --location string Location of the template source. Required when using type flag.
-n, --name string Display name of the template source.
-t, --type string Kind of the template source. Supported types are 'file', 'url' and 'gh'.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd template source list in your web browser.
-h, --help Gets help for list.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd template source remove in your web browser.
-h, --help Gets help for remove.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Discover, install, update, and check status of Azure development tools.
Options
--docs Opens the documentation for azd tool in your web browser.
-h, --help Gets help for tool.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd tool check in your web browser.
-h, --help Gets help for check.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--agent strings Install the skill for the specified agent(s): copilot, claude. Use --agent all for every detected agent (skill tools only)
--all Install all recommended tools
--docs Opens the documentation for azd tool install in your web browser.
--dry-run Preview what would be installed without making changes
-h, --help Gets help for install.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd tool list in your web browser.
-h, --help Gets help for list.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd tool show in your web browser.
-h, --help Gets help for show.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--agent strings Uninstall the skill from the specified agent(s): copilot, claude. Use --agent all (or omit --agent) to remove the skill from every agent it is installed through (skill tools only)
--all Uninstall all installed tools
--docs Opens the documentation for azd tool uninstall in your web browser.
--dry-run Preview what would be uninstalled without making changes
-h, --help Gets help for uninstall.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--agent strings Update the skill for the specified agent(s): copilot, claude. Use --agent all for every detected agent (skill tools only)
--all Update all installed tools
--docs Opens the documentation for azd tool update in your web browser.
--dry-run Preview what would be updated without making changes
-h, --help Gets help for update.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
Provision and deploy your project to Azure with a single command.
azd up [flags]
Options
--docs Opens the documentation for azd up in your web browser.
-e, --environment string The name of the environment to use.
-h, --help Gets help for up.
-l, --location string Azure location for the new environment
--subscription string ID of an Azure subscription to use for the new environment
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--channel string Update channel: stable or daily.
--check-interval-hours int Override the update check interval in hours.
--docs Opens the documentation for azd update in your web browser.
-h, --help Gets help for update.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
--docs Opens the documentation for azd version in your web browser.
-h, --help Gets help for version.
Options inherited from parent commands
-C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
-e, --environment string The name of the environment to use.
--no-prompt Runs without prompts. Uses existing values; fails if any required value or decision cannot be resolved automatically. Automatically enabled when azd detects a CI/CD or AI-agent environment; set AZD_NON_INTERACTIVE=false to opt out of that automatic enablement.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #9166
Propagate cancellation end to end across azd commands, foreground extension processes, unary gRPC calls, extension-started workflows, and long-lived extension listener streams.
user.canceledand deadlines asinternal.timeoutRoot cause
Cancellation previously stopped at several ownership boundaries:
MessageBroker.SendAndWaitstopped waiting locally but did not notify the other process, allowing remote work to continue.ext.run.failed, tool failures, or gRPCInternalerrors.Cancellation design
CancellationMiddlewareruns outsideloginGuard, owns Ctrl+C, and cancels one command context, including implicit login work.WorkflowService.Runpreserves the runner error chain. Cancellation and deadlines pass through the canonical host gRPC serializer before ordinary failures fall back toInternal.MessageBrokersends a control message with the same request ID; the remote broker cancels only the matching handler context.context.Canceled, terminal interruption, gRPCCanceled, structured extensionuser/canceled, and interrupted extension processes converge onuser.canceled. Deadlines converge oninternal.timeout.flowchart LR CtrlC["Ctrl+C"] --> Middleware["CancellationMiddleware"] Middleware --> CommandCtx["azd command context"] CommandCtx --> Foreground["Foreground extension invocation"] Foreground --> SignalOrJob["POSIX SIGINT + grace / Windows Job Object"] CommandCtx --> Unary["Unary gRPC"] Unary --> NativeCancel["Native RPC cancellation"] CommandCtx --> Workflow["Extension-started workflow"] Workflow --> HostMapper["Canonical host error mapping"] CommandCtx --> Broker["MessageBroker SendAndWait"] Broker --> CancelMessage["Cancel message + request ID"] CancelMessage --> RemoteBroker["Remote MessageBroker"] RemoteBroker --> HandlerCtx["Matching handler context"] HandlerCtx --> Ack["Final response / acknowledgment"] Ack --> Broker Foreground --> Classifier["Canonical cancellation classification"] NativeCancel --> Classifier HostMapper --> Classifier Broker --> Classifier Classifier --> Outcome["user.canceled / internal.timeout"]Compatibility and API surface
v1or previewv1beta.Relationship to extension telemetry
PR #10068 controls extension-emitted
ext.usageevents. This PR does not change that API. It fixes cancellation of host-observed extension work and ensures the enclosingext.runorcmd.*span uses the sameuser.canceledclassification as existing azd Ctrl+C paths.Validation
Current PR head:
0286dcb84705a0275058a429406652f5202079a1Current-head validation:
go test ./internal/grpcserver -count=1WorkflowService.Runregression coverage for direct, wrapped, existing-gRPC, and joined cancellation/deadline errorsenvironment.ErrExistscontext.Canceledorcontext.DeadlineExceededInternalandenvironment.ErrExistsremainsAlreadyExistsExtensionHostagainst the real beta stream validator, cancels one service invocation, and completes a second invocation on the same streamThe cross-platform process and broker behavior below was live-tested on parent commit
4fa448ac24c0468cd531de1498ca20573d45abde. Subsequent commits refine workflow error mapping, stable listener correlation identity, middleware ordering, beta handler cancellation acknowledgments, and regression coverage without changing process or broker cancellation transport.azd canceltest waitCTRL_C_EVENT; extension Job Object terminated; no orphaned azd or extension processext.run = user.canceledazd package webprovider-canceled:context canceled; stream cancellation was acknowledged; no orphaned processcmd.package = user.canceledazd hooks run preprovisioncmd.hooks.run = user.canceleddirect-canceled:interrupt signal receivedbefore exitext.run = user.canceled,error.category = user,error.code = canceledKnown limitations and follow-ups
pkg/extensions.Runnerretains a local context-cause fallback until Make subprocess cancellation consistent across command runners and mocks #10035 centralizes atomic process-completion versus cancellation handling in the shared process wrapper.