Version extension gRPC contracts by vhvb1989 · Pull Request #9747 · Azure/azure-dev

Victor Vazquez (vhvb1989) · 2026-08-26T21:43:56Z

Summary

establish canonical stable azd.extensions.v1 and preview azd.extensions.v1beta protobuf packages
separate generated protobuf/gRPC code into pkg/azdext/contracts/v1 and pkg/azdext/contracts/v1beta, while preserving the stable handwritten pkg/azdext SDK facade
register stable and beta services in the azd host, with native beta-only implementations plus generated adapters and focused overrides for preview additions to shared services
retain the frozen pre-versioning /azdext.* RPC surface through a temporary isolated compatibility bridge, measured by telemetry for removal
add reproducible generation, Buf lint/breaking configuration, stable-subset compatibility tests, CODEOWNERS protection, and contract lifecycle documentation

Addresses #9663.

Why this design

This follows the compatibility model described in Microsoft's Versioning gRPC services guidance:

Keep a service backward compatible when practical. Additive fields, methods, services, and enum values can remain within the same stable version when older clients still receive valid behavior.
Put the major version in the protobuf package. The package is part of the gRPC service address, so azd.extensions.v1.ProjectService and azd.extensions.v1beta.ProjectService can be registered side-by-side.
Treat package, service, or method renames as protocol-breaking changes. A client calling a removed address receives gRPC UNIMPLEMENTED; therefore the move from azdext.* to azd.extensions.v1.* needs an explicit migration bridge rather than being treated as a source-only file move.
Share business logic between versions instead of duplicating it. For services present in both channels, generated beta adapters map beta transport messages to stable implementations while focused overrides handle beta-only additions. Services that exist only in beta use native beta implementations.

The v1beta spelling comes from the protobuf API channel convention documented by AIP-185, rather than from Microsoft's article specifically. We use it instead of v1preview or next because:

v1 identifies the stable compatibility-major surface; protobuf package versions do not expose minor or patch versions such as v1.1.
v1beta identifies a long-lived beta channel associated with major version 1 and is a recognizable convention for generated API packages.
The beta surface is required to be a superset of stable v1, which this PR enforces with descriptor-based compatibility tests.
Features graduate by being added compatibly to v1; the v1beta package is not renamed and a v1.1 package is not created.
preview remains the product/support label, while beta is the protobuf package-channel identifier. next would not communicate a stability level or compatibility-major lineage.

The contract rules also align with the Protocol Buffers updating guidance: field numbers identify data on the wire, must not be changed or reused, and removed numbers/names must be reserved. Buf plus the cross-package stable-subset tests enforce these rules for future changes.

Compatibility bridge and rollout

The package migration changes gRPC service addresses, but this PR no longer requires all extensions to migrate atomically. azd registers three service identities:

azd.extensions.v1.* — the supported stable contract for current extension development.
azd.extensions.v1beta.* — the preview contract for narrow opt-in to preview functionality.
azdext.* — a temporary, frozen invocation-compatibility bridge for binaries built before contract versioning.

The bridge is intentionally isolated in internal/grpcserver/legacybridge. It does not restore the old generated SDK or create another contract package for developers to import. Instead, it registers aliases for the exact 18-service, 78-RPC legacy surface that existed when versioning was introduced and delegates those calls to the corresponding versioned implementations: stable v1 for GA services and native v1beta for Compose and Copilot. The allowlist is explicit: additions to v1 do not become legacy endpoints unless someone deliberately edits the frozen list. Descriptor metadata is omitted because the bridge supports invocation compatibility, not a complete legacy reflection schema.

Structured ActionableErrorDetail values also carry protobuf package names in their Any type URLs. For legacy calls, the bridge rewrites stable azd.extensions.v1.* detail URLs back to azdext.*; the message bytes remain valid because the initial stable schema preserves the legacy wire format.

This is a migration layer, not a third supported development channel. Each authenticated unary call or opened stream through /azdext.* increments the integer measurement extension.grpc.legacy_call_count on the enclosing command or ext.run span. Remove the bridge, its interceptor hooks, and the measurement after the count remains zero for a full stable release cycle and all supported extensions have migrated to azd.extensions.v1. A privacy review and downstream query/dashboard coordination are required for this new field.

Extensions pinned to an existing released SDK remain buildable, and already-published binaries continue to communicate with an azd host built from this change through the bridge. The non-Go scaffolds owned by microsoft.azd.extensions are updated here so newly generated JavaScript, Python, and .NET extensions target stable v1. The first planned core release containing the versioned endpoints is azd 1.33.0. Newly generated extension manifests and the developer-kit extension therefore set requiredAzdVersion: ">=1.33.0"; existing first-party extensions should use the same floor when they migrate to the new stable SDK structure.

The initial stable snapshot reflects the GA contracts currently on main, including telemetry, image passthrough, and empty multi-select support. ComposeService and CopilotService are excluded from v1 because those capabilities are not GA; they exist only in v1beta. Their frozen /azdext.* aliases remain available solely to avoid breaking existing preview extension binaries.

Preview-only services

ComposeService and CopilotService use native generated v1beta server implementations rather than pretending to have stable implementations and adapting back to them. They have no generated files or aliases under contracts/v1 or the stable azdext contract façade. The AzdClient.Compose() and AzdClient.Copilot() convenience methods return explicit v1beta client interfaces, and callers import pkg/azdext/contracts/v1beta for request, response, and enum types. When either service reaches GA, it can be added compatibly to v1 and the normal stable-to-beta adapter path will take over.

Extension compatibility scenarios

requiredAzdVersion is enforced while resolving an extension install or update. It protects the new extension → old azd direction, but it is not a negotiated gRPC protocol version. The temporary bridge protects the old extension → new azd direction during migration.

azd and extension combination	What happens with this PR	User-visible result	Recovery / rollout action
Old azd + existing old-contract extension	Compatible; both use `/azdext.*`.	Extension continues to work.	None.
Old azd + install/update to a migrated `v1` or `v1beta` extension whose `requiredAzdVersion` requires the new azd	Existing install/update resolution handles this. An explicit incompatible version is rejected; when selecting latest, azd can install the latest compatible older extension and warn.	Clear message that the requested extension requires a newer azd, or warning that an older compatible extension is being installed.	Update azd, or remain on the older compatible extension.
New azd + migrated stable `v1` extension	Compatible; both use `/azd.extensions.v1.*`.	Extension works normally.	None.
New azd + migrated preview `v1beta` extension	Compatible when its `requiredAzdVersion` includes the first azd release supporting beta.	Extension can use preview RPCs while stable extensions continue using `v1`.	None; preview functionality remains subject to beta compatibility policy.
New azd + already-installed old-contract extension	Compatible through the frozen `/azdext.*` bridge for the legacy RPC surface. Usage increments `extension.grpc.legacy_call_count`.	Existing extension continues to work without a coordinated release.	Publish and adopt a migrated `v1` extension version; the telemetry count shows when the bridge can be removed.
New azd + explicitly selected old extension version	Compatible through the frozen bridge if it only uses RPCs from the pre-versioning surface. It cannot access methods added only to `v1` or `v1beta`.	Existing behavior works; new contract features require an extension update.	Upgrade the extension to a migrated release before the bridge removal milestone.
azd is downgraded after a migrated extension is already installed	The old host lacks `/azd.extensions.v1.` and `/azd.extensions.v1beta.`. The install-time check is not re-run merely because azd was downgraded.	The migrated extension fails when it calls the host, normally with `UNIMPLEMENTED`.	Re-upgrade azd or install an extension version compatible with the downgraded azd.
Future azd after the bridge is removed + unmigrated old extension	The host no longer registers `/azdext.*`.	gRPC returns `UNIMPLEMENTED` unless a separate tailored compatibility diagnostic is added before removal.	Upgrade the extension; otherwise use an azd release that still contains the bridge. Removal is gated on zero measured usage to make this an exceptional fallback.

Migrating an extension

Existing extension to stable `v1`

This is the default migration for an existing GA extension:

Update the extension's github.com/Azure/azure-dev/cli/azd dependency to a release containing this change.
Rebuild the extension. Extensions using GA services through the handwritten pkg/azdext SDK normally keep the same Go import and API names because generated stable types are re-exported by the stable SDK facade; rebuilding changes their RPC addresses to /azd.extensions.v1.*. Compose and Copilot are preview-only and instead require contracts/v1beta request and response types.
If the extension imports generated types directly, move those imports to pkg/azdext/contracts/v1.
Set requiredAzdVersion to the first azd release that hosts azd.extensions.v1.
Publish the migrated extension as a new extension version. Keep the previous extension version available for users who remain on older azd versions.

Example outcome: an extension using azdext.NewAzdClient().Project() remains source-compatible through the facade. Its old binary continues working temporarily through the frozen bridge, while updating the SDK dependency and rebuilding moves it to the supported /azd.extensions.v1.* address. An extension using Compose or Copilot keeps the AzdClient convenience accessor but changes those protobuf message imports to contracts/v1beta.

Stable `v1` extension opting into a beta feature

An extension does not need to migrate every service to beta. The recommended flow is:

Keep existing services on the stable pkg/azdext facade or pkg/azdext/contracts/v1 package.
Import pkg/azdext/contracts/v1beta only for the service containing the required preview RPC, field, or enum value.
Construct that generated beta service client against the azd gRPC connection and use v1beta request/response types for that RPC.
Raise requiredAzdVersion to the first azd version implementing the beta feature.
Clearly mark the extension behavior as preview and publish a new extension version.

Conceptually, a mixed extension can use clients like this against the same host connection:

stableProject := v1.NewProjectServiceClient(conn)
previewModels := v1beta.NewAiModelServiceClient(conn)

The existing azdext.AzdClient convenience methods are stable-v1 only. A beta caller currently uses the generated contracts/v1beta client with a gRPC connection; a future SDK helper could make that more ergonomic without changing the wire model.

Moving a beta feature back to stable `v1`

When a preview feature graduates:

Add the field, method, message, or enum value compatibly to the stable v1 contract; do not rename v1beta and do not create v1.1.
Release an azd version that implements the stable RPC while continuing to host the beta service during the migration period.
Update the extension SDK dependency and switch that service's import/client/message types from contracts/v1beta to pkg/azdext or contracts/v1.
Rebuild and publish the extension, updating requiredAzdVersion if the stable feature requires a newer azd.
Repeat independently for other beta services. The extension may continue using beta for features that have not graduated.

Switching package imports requires a rebuild because v1.SomeRequest and v1beta.SomeRequest are distinct generated Go types even when their fields are currently identical.

Can one extension mix `v1` and `v1beta`?

Yes. Version selection is per gRPC service client/RPC, not a single mode negotiated for the whole extension. The host registers both package identities, so one extension can use stable Project and Environment services while using a beta AI Model service.

The boundaries are:

One RPC call must use a client and request/response types from the same package. A v1beta request cannot be passed to a v1 generated client.
Identically named messages in v1 and v1beta are distinct Go types. Data crossing that boundary must be mapped or transcoded explicitly.
Using beta for one service does not force unrelated services onto beta.
Using v1beta for every service is technically possible, but it unnecessarily couples the extension to the preview channel. Stable by default with narrow beta opt-in minimizes migration and compatibility risk.
requiredAzdVersion applies to the extension release as a whole. A single beta dependency therefore raises the minimum azd version for that extension version, even if its other services remain on v1.

Versioning model

v1 is the stable compatibility-major contract and evolves through protobuf-compatible additions.
v1beta is the preview channel and may add preview messages, fields, enum values, methods, and services. Compose and Copilot are currently beta-only services.
Graduated preview functionality is added compatibly to v1; no v1.1 protobuf package is created.
The host serves stable and beta package identities simultaneously, plus a temporary frozen alias for the pre-versioning legacy identity.
Shared beta methods transcode and delegate to stable business logic. Preview additions on shared services use focused beta overrides; beta-only services such as Compose and Copilot use native v1beta implementations directly.
Stable contract-local structured error details are translated to beta type URLs for beta clients and legacy type URLs for bridged clients.
The legacy bridge is not generated, is not exposed as an SDK package, cannot gain stable methods automatically, and is removed only after telemetry remains at zero for a full stable release cycle.

The versioned contracts become the baseline for future Buf historical compatibility checks. The frozen legacy aliases are migration-only runtime registrations and are not a new source contract baseline.

Testing

mage preflight
make proto reproducibility check
targeted stable/beta/legacy host routing, adapter-generator, structured-error translation, frozen-surface, telemetry, and contract compatibility tests

Telemetry Change Checklist

New Fields

Core field defined in fields/fields.go; extension-supplied ext.* values are covered by the extension's own review instead
Field has the correct classification and purpose
Field documented in docs/specs/metrics-audit/telemetry-schema.md
Hashing applied where required (user-provided values, names, paths) — not applicable to this integer measurement
Measurement fields use correct OTel type (Int64, Float64)
Enum values documented with allowed value set — not applicable; this field is a count
Extension enum values contain no user-derived or customer content — not applicable; no enum was added

New Events

Event constant defined in events/events.go — not applicable; no event was added
Event constant is an exported string const whose Go identifier contains Event — not applicable
Event documented in docs/specs/metrics-audit/telemetry-schema.md — not applicable
Event follows naming convention (prefix.noun.verb) — not applicable

Privacy

Classification assigned using decision tree
No CustomerContent emitted in telemetry
No unhashed user-provided values
No PII in string attributes (names, emails, paths)
Privacy review triggered

Testing

Unit test verifies the usage attribute is incremented only for legacy unary and streaming calls
Integration test confirms legacy unary and streaming endpoints route through the real gRPC server
Verified field appears correctly in local telemetry output

Downstream

LENS job updated (if field is queried in dashboards)
Kusto function updated (if field is used in cooked tables)
Dashboard updated (if field powers a new metric)

Documentation

Feature-telemetry matrix updated (docs/specs/metrics-audit/feature-telemetry-matrix.md)
Telemetry schema updated (docs/specs/metrics-audit/telemetry-schema.md)
Hashed-field table in this checklist updated if needed — not applicable; the field is an integer measurement
This checklist is complete

Establish stable v1 and preview v1beta protobuf packages, separate generated contracts from the handwritten azdext SDK, and register both contract channels in the host. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

azure-pipelines · 2026-08-26T21:44:43Z

Azure Pipelines: Successfully started running 1 pipeline(s). 20 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

Exercise every beta service adapter through real gRPC dispatch and consolidate generated unary adaptation and override validation so contract growth does not cause repeated coverage regressions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Introduces versioned stable and beta extension gRPC contracts while retaining the stable Go SDK facade.

Changes:

Adds v1/v1beta protobuf packages and generated clients.
Registers both contract versions through generated adapters.
Adds generation, compatibility, ownership, and lifecycle guidance.

Reviewed changes

Copilot reviewed 87 out of 135 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`.github/CODEOWNERS`	Protects stable contracts.
`cli/azd/.vscode/cspell.yaml`	Adds generator terms.
`cli/azd/Makefile`	Generates versioned contracts and adapters.
`cli/azd/docs/extensions/contract-versioning.md`	Documents contract lifecycle.
`cli/azd/docs/extensions/extension-framework.md`	Updates contract references.
`cli/azd/grpc/README.md`	Documents generation and compatibility checks.
`cli/azd/grpc/buf.yaml`	Configures Buf validation.
`cli/azd/grpc/generateadapters/main_test.go`	Tests adapter generation rules.
`cli/azd/grpc/generatefacade/main.go`	Generates the stable SDK facade.
`cli/azd/grpc/include/google/protobuf/struct.proto`	Vendors the shared well-known type.
`cli/azd/grpc/proto/azd/extensions/v1/account.proto`	Versions the stable account contract.
`cli/azd/grpc/proto/azd/extensions/v1/ai_model.proto`	Versions the stable AI model contract.
`cli/azd/grpc/proto/azd/extensions/v1/compose.proto`	Versions the stable compose contract.
`cli/azd/grpc/proto/azd/extensions/v1/container.proto`	Versions the stable container contract.
`cli/azd/grpc/proto/azd/extensions/v1/deployment.proto`	Versions the stable deployment contract.
`cli/azd/grpc/proto/azd/extensions/v1/environment.proto`	Versions the stable environment contract.
`cli/azd/grpc/proto/azd/extensions/v1/errors.proto`	Versions stable error details.
`cli/azd/grpc/proto/azd/extensions/v1/event.proto`	Versions the stable event contract.
`cli/azd/grpc/proto/azd/extensions/v1/extension.proto`	Versions the stable lifecycle contract.
`cli/azd/grpc/proto/azd/extensions/v1/framework_service.proto`	Versions the stable framework contract.
`cli/azd/grpc/proto/azd/extensions/v1/models.proto`	Versions shared stable models.
`cli/azd/grpc/proto/azd/extensions/v1/project.proto`	Versions the stable project contract.
`cli/azd/grpc/proto/azd/extensions/v1/prompt.proto`	Versions the stable prompt contract.
`cli/azd/grpc/proto/azd/extensions/v1/telemetry.proto`	Versions the stable telemetry contract.
`cli/azd/grpc/proto/azd/extensions/v1/user_config.proto`	Versions the stable configuration contract.
`cli/azd/grpc/proto/azd/extensions/v1/validation.proto`	Versions the stable validation contract.
`cli/azd/grpc/proto/azd/extensions/v1/workflow.proto`	Versions the stable workflow contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/account.proto`	Adds the beta account contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/compose.proto`	Adds the beta compose contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/container.proto`	Adds the beta container contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/copilot.proto`	Adds the beta Copilot contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/deployment.proto`	Adds the beta deployment contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/environment.proto`	Adds the beta environment contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/errors.proto`	Adds beta error details.
`cli/azd/grpc/proto/azd/extensions/v1beta/event.proto`	Adds the beta event contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/extension.proto`	Adds the beta lifecycle contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/framework_service.proto`	Adds the beta framework contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/models.proto`	Adds shared beta models.
`cli/azd/grpc/proto/azd/extensions/v1beta/project.proto`	Adds the beta project contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/provisioning.proto`	Adds the beta provisioning contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/service_target.proto`	Adds the beta target contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/telemetry.proto`	Adds the beta telemetry contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/user_config.proto`	Adds the beta configuration contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/validation.proto`	Adds the beta validation contract.
`cli/azd/grpc/proto/azd/extensions/v1beta/workflow.proto`	Adds the beta workflow contract.
`cli/azd/internal/grpcserver/server.go`	Registers and translates versioned services.
`cli/azd/pkg/azdext/output_test.go`	Updates stable-message coverage.
`cli/azd/pkg/azdext/contracts/v1/account_grpc.pb.go`	Generates stable account RPCs.
`cli/azd/pkg/azdext/contracts/v1/ai_model_grpc.pb.go`	Generates stable AI model RPCs.
`cli/azd/pkg/azdext/contracts/v1/compose_grpc.pb.go`	Generates stable compose RPCs.
`cli/azd/pkg/azdext/contracts/v1/container_grpc.pb.go`	Generates stable container RPCs.
`cli/azd/pkg/azdext/contracts/v1/copilot_grpc.pb.go`	Generates stable Copilot RPCs.
`cli/azd/pkg/azdext/contracts/v1/deployment_grpc.pb.go`	Generates stable deployment RPCs.
`cli/azd/pkg/azdext/contracts/v1/environment_grpc.pb.go`	Generates stable environment RPCs.
`cli/azd/pkg/azdext/contracts/v1/event_grpc.pb.go`	Generates stable event RPCs.
`cli/azd/pkg/azdext/contracts/v1/extension_grpc.pb.go`	Generates stable lifecycle RPCs.
`cli/azd/pkg/azdext/contracts/v1/framework_service_grpc.pb.go`	Generates stable framework RPCs.
`cli/azd/pkg/azdext/contracts/v1/project_grpc.pb.go`	Generates stable project RPCs.
`cli/azd/pkg/azdext/contracts/v1/prompt_grpc.pb.go`	Generates stable prompt RPCs.
`cli/azd/pkg/azdext/contracts/v1/provisioning_grpc.pb.go`	Generates stable provisioning RPCs.
`cli/azd/pkg/azdext/contracts/v1/service_target_grpc.pb.go`	Generates stable target RPCs.
`cli/azd/pkg/azdext/contracts/v1/telemetry_grpc.pb.go`	Generates stable telemetry RPCs.
`cli/azd/pkg/azdext/contracts/v1/user_config_grpc.pb.go`	Generates stable configuration RPCs.
`cli/azd/pkg/azdext/contracts/v1/validation_grpc.pb.go`	Generates stable validation RPCs.
`cli/azd/pkg/azdext/contracts/v1/workflow_grpc.pb.go`	Generates stable workflow RPCs.
`cli/azd/pkg/azdext/contracts/v1beta/account_grpc.pb.go`	Generates beta account RPCs.
`cli/azd/pkg/azdext/contracts/v1beta/deployment_grpc.pb.go`	Generates beta deployment RPCs.
`cli/azd/pkg/azdext/contracts/v1beta/event_grpc.pb.go`	Generates beta event RPCs.
`cli/azd/pkg/azdext/contracts/v1beta/extension_grpc.pb.go`	Generates beta lifecycle RPCs.
`cli/azd/pkg/azdext/contracts/v1beta/framework_service_grpc.pb.go`	Generates beta framework RPCs.
`cli/azd/pkg/azdext/contracts/v1beta/provisioning_grpc.pb.go`	Generates beta provisioning RPCs.
`cli/azd/pkg/azdext/contracts/v1beta/service_target_grpc.pb.go`	Generates beta target RPCs.
`cli/azd/pkg/azdext/contracts/v1beta/telemetry_grpc.pb.go`	Generates beta telemetry RPCs.
`cli/azd/pkg/azdext/contracts/v1beta/validation_grpc.pb.go`	Generates beta validation RPCs.
`cli/azd/pkg/azdext/contracts/v1beta/workflow_grpc.pb.go`	Generates beta workflow RPCs.

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Correct contract documentation and migrate non-Go extension scaffolds to the stable v1 gRPC package so newly generated clients remain compatible with the versioned host. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d1a4605-370b-43ca-9845-979dd2b4ada3

Copilot

Pull request overview

Copilot reviewed 90 out of 179 changed files in this pull request and generated 1 comment.

Set the generated extension and developer-kit manifests to require azd 1.33.0, the first planned release hosting the stable v1 extension endpoints. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d1a4605-370b-43ca-9845-979dd2b4ada3

Copilot

Pull request overview

Copilot reviewed 93 out of 182 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

cli/azd/Makefile:49

This only exposes a manual target; no workflow or mage preflight path invokes proto-breaking (or proto-lint). As a result, future PRs can change both v1 and v1beta incompatibly and still pass the cross-channel tests, so the historical compatibility protection requested by #9663 is not actually enforced. Wire these targets into CI against the PR base revision once this baseline lands.

azure-pipelines · 2026-08-31T04:56:25Z

Azure Pipelines: Successfully started running 2 pipeline(s). 19 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

azure-sdk-automation · 2026-08-31T06:05:16Z

Azure Dev CLI Install Instructions

Install scripts

MacOS/Linux

May elevate using sudo on some platforms and configurations

bash:

curl -fsSL https://azuresdkartifacts.z5.web.core.windows.net/azd/standalone/pr/9747/uninstall-azd.sh | bash;
curl -fsSL https://azuresdkartifacts.z5.web.core.windows.net/azd/standalone/pr/9747/install-azd.sh | bash -s -- --base-url https://azuresdkartifacts.z5.web.core.windows.net/azd/standalone/pr/9747 --version '' --verbose --skip-verify

pwsh:

Invoke-RestMethod 'https://azuresdkartifacts.z5.web.core.windows.net/azd/standalone/pr/9747/uninstall-azd.ps1' -OutFile uninstall-azd.ps1; ./uninstall-azd.ps1
Invoke-RestMethod 'https://azuresdkartifacts.z5.web.core.windows.net/azd/standalone/pr/9747/install-azd.ps1' -OutFile install-azd.ps1; ./install-azd.ps1 -BaseUrl 'https://azuresdkartifacts.z5.web.core.windows.net/azd/standalone/pr/9747' -Version '' -SkipVerify -Verbose

Windows

PowerShell install

powershell -c "Set-ExecutionPolicy Bypass Process; irm 'https://azuresdkartifacts.z5.web.core.windows.net/azd/standalone/pr/9747/uninstall-azd.ps1' > uninstall-azd.ps1; ./uninstall-azd.ps1;"
powershell -c "Set-ExecutionPolicy Bypass Process; irm 'https://azuresdkartifacts.z5.web.core.windows.net/azd/standalone/pr/9747/install-azd.ps1' > install-azd.ps1; ./install-azd.ps1 -BaseUrl 'https://azuresdkartifacts.z5.web.core.windows.net/azd/standalone/pr/9747' -Version '' -SkipVerify -Verbose;"

MSI install

powershell -c "irm 'https://azuresdkartifacts.z5.web.core.windows.net/azd/standalone/pr/9747/azd-windows-amd64.msi' -OutFile azd-windows-amd64.msi; msiexec /i azd-windows-amd64.msi /qn"

Standalone Binary

MSI

x86_64 - https://azuresdkartifacts.z5.web.core.windows.net/azd/standalone/pr/9747/azd-windows-amd64.msi

Documentation

learn.microsoft.com documentation

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: 08/31/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 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.

azd auth

Authenticate with Azure.

Options

      --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.

azd auth login

Log in to Azure.

Synopsis

Log in to Azure.

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.

azd auth logout

Log out of Azure.

Synopsis

Log out of Azure

azd auth logout [flags]

Options

      --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.

azd auth status

Show the current authentication status.

Synopsis

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.

azd completion

Generate shell completion scripts.

Synopsis

Generate shell completion scripts for azd.

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.

azd completion bash

Generate bash completion script.

azd completion bash

Options

      --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.

azd completion fig

Generate Fig autocomplete spec.

azd completion fig

Options

      --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.

azd completion fish

Generate fish completion script.

azd completion fish

Options

      --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.

azd completion powershell

Generate PowerShell completion script.

azd completion powershell

Options

      --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.

azd completion zsh

Generate zsh completion script.

azd completion zsh

Options

      --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.

azd config

Manage azd configurations (ex: default Azure subscription, location).

Synopsis

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.

azd config get

Gets a configuration.

Synopsis

Gets 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 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.

azd config list-alpha

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.

azd config options

List all available configuration settings.

Synopsis

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.

azd config reset

Resets configuration to default.

Synopsis

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.

azd config set

Sets a configuration.

Synopsis

Sets 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 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.

azd config show

Show all the configuration values.

Synopsis

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.

azd config sub-filter

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.

azd config sub-filter remove

Remove a saved subscription filter for a tenant.

Synopsis

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.

azd config sub-filter set

Set a subscription filter for a tenant.

Synopsis

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.

azd config unset

Unsets a configuration.

Synopsis

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.

azd copilot

Manage GitHub Copilot agent settings. (Preview)

Options

      --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.

azd copilot consent

Manage tool consent.

Synopsis

Manage consent rules for tool execution.

Options

      --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.

azd copilot consent grant

Grant consent trust rules.

Synopsis

Grant trust rules for tools and servers.

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.

azd copilot consent list

List consent rules.

Synopsis

List all consent rules for tools.

azd copilot consent list [flags]

Options

      --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.

azd copilot consent revoke

Revoke consent rules.

Synopsis

Revoke consent rules for tools.

azd copilot consent revoke [flags]

Options

      --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.

azd deploy

Deploy your project code to Azure.

azd deploy <service> [flags]

Options

      --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.
      --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.

azd down

Delete your project's Azure resources.

azd down [<layer>] [flags]

Options

      --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.

azd env

Manage environments (ex: default environment, environment variables).

Options

      --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.

azd env config

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.

azd env config get

Gets a configuration value from the environment.

Synopsis

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.

azd env config set

Sets a configuration value in the environment.

Synopsis

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.

azd env config unset

Unsets a configuration value in the environment.

Synopsis

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.

azd env get-value

Get specific environment value.

azd env get-value <keyName> [flags]

Options

      --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.

azd env get-values

Get all environment values.

azd env get-values [flags]

Options

      --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.

azd env list

List environments.

azd env list [flags]

Options

      --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.

azd env new

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.

azd env refresh

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.

azd env remove

Remove an environment.

azd env remove <environment> [flags]

Options

      --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.

azd env select

Set the default environment.

azd env select [<environment>] [flags]

Options

      --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.

azd env set

Set one or more environment values.

Synopsis

Set one or more environment values using key-value pairs or by loading from a .env formatted file.

azd env set [<key> <value>] | [<key>=<value> ...] | [--file <filepath>] [flags]

Options

      --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.

azd env set-secret

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.

azd exec

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.

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

azd exec [command] [args...] [-- script-args...] [flags]

Options

      --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.

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.

azd extension

Manage azd extensions.

Options

      --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.

azd extension install

Installs specified extensions.

Synopsis

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 (.zip), either as a local
path or an https URL: azd downloads (when remote) and extracts it, then installs
the bundled extension. Bundled extensions aren't tracked for updates; reinstall
from a newer bundle to update.

azd extension install <extension-id|extension-bundle.zip> [flags]

Options

      --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.

azd extension list

List available extensions.

Synopsis

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.

azd extension show

Show details for a specific extension.

Synopsis

Show details for a specific extension from a registered extension source.

The --source flag accepts a registered source name or registry location (URL or
file path). Locations are queried read-only and are not registered.

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.

azd extension source

View and manage extension sources

Options

      --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.

azd extension source add

Add an extension source with the specified name

Synopsis

Add an extension source with the specified name.

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.

azd extension source list

List extension sources

azd extension source list [flags]

Options

      --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.

azd extension source remove

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.

azd extension source validate

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.

azd extension source validate <name-or-path-or-url> [flags]

Options

      --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.

azd extension uninstall

Uninstall specified extensions.

azd extension uninstall [extension-id] [flags]

Options

      --all    Uninstall all installed extensions
      --docs   Opens the documentation for azd extension uninstall in your web browser.
  -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.

azd extension update

Update installed extensions to the latest version.

Synopsis

Update one or more installed extensions.

By default, uses the stored registry source for each extension. If the stored
source is unavailable, falls back to the main (azd) registry. Extensions that
were installed from a non-main registry (e.g., dev) are automatically promoted
to the main registry when a newer version is available there.

Use --source to override the registry source for the update. It accepts a
registered source name or registry location (URL or file path); locations are
registered first and the updated extension's stored source is updated. Because
registration is interactive, locations are rejected under --no-prompt. Use --all
to update all installed extensions in a single batch; failures in one extension
do not prevent the remaining extensions from being updated.

When updating an extension that has dependencies, any installed
dependencies are automatically updated too, to the highest version
satisfying the extension's declared constraints. Use
--no-dependency-updates to opt out and update only the named
extension.

Use --output json for a structured report of all update results.

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.

azd hooks

Develop, test and run hooks for a project.

Options

      --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.

azd hooks run

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.

azd infra

Manage your Infrastructure as Code (IaC).

Options

      --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.

azd infra generate

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.

azd init

Initialize a new application.

Synopsis

Initialize a new application.

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.

azd mcp

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.

azd mcp start

Starts the MCP server.

Synopsis

Starts the Model Context Protocol (MCP) server.

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.

azd monitor

Monitor a deployed project.

azd monitor [flags]

Options

      --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.

azd package

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.

azd pipeline

Manage and configure your deployment pipelines.

Options

      --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.

azd pipeline config

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.

azd provision

Provision Azure resources for your project.

azd provision [<layer>] [flags]

Options

      --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.

azd publish

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.

azd restore

Restores the project's dependencies.

azd restore <service> [flags]

Options

      --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.

azd show

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.

azd template

Find and view template details.

Options

      --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.

azd template list

Show list of sample azd templates. (Beta)

azd template list [flags]

Options

      --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.

azd template show

Show details for a given template. (Beta)

azd template show <template> [flags]

Options

      --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.

azd template source

View and manage template sources. (Beta)

Options

      --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.

azd template source add

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.

azd template source list

Lists the configured azd template sources. (Beta)

azd template source list [flags]

Options

      --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.

azd template source remove

Removes the specified azd template source (Beta)

azd template source remove <key> [flags]

Options

      --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.

azd tool

Manage Azure development tools.

Synopsis

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.

azd tool check

Check for tool updates.

azd tool check [flags]

Options

      --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.

azd tool install

Install specified tools.

azd tool install [tool-name...] [flags]

Options

      --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.

azd tool list

List all tools with status.

azd tool list [flags]

Options

      --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.

azd tool show

Show details for a specific tool.

azd tool show <tool-name> [flags]

Options

      --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.

azd tool uninstall

Uninstall installed tools.

azd tool uninstall [tool-name...] [flags]

Options

      --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.

azd tool update

Update installed tools.

azd tool update [tool-name...] [flags]

Options

      --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.

azd up

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.

azd update

Updates azd to the latest version.

azd update [flags]

Options

      --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.

azd version

Print the version number of Azure Developer CLI.

azd version [flags]

Options

      --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.

Pull request overview

Copilot reviewed 97 out of 191 changed files in this pull request and generated 3 comments.

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

cli/azd/Makefile:49

proto-breaking is only a manual target: nothing in repository workflows or mage preflight invokes it, and it has no default baseline. A future v1 field renumbering mirrored into v1beta would pass the Go subset test, so the promised historical compatibility gate is not enforced. Run Buf lint and breaking checks in CI for contract changes, using the target branch as the baseline.

cli/azd/grpc/README.md:19

This contradicts the compatibility bridge registered by registerLegacyServices and the rollout described in the PR. Existing binaries can call the frozen /azdext.* surface; only new development should use the versioned packages. Document the temporary bridge and its frozen scope instead of saying the endpoints are absent.

+			return err
+		}
+		descriptions = append(descriptions, description)
+		registrar.RegisterService(&descriptions[len(descriptions)-1], implementation)


+The move from the original `azdext` wire package to
+`azd.extensions.v1` is an intentionally accepted one-time breaking change.
+azd does not register legacy `/azdext.*` runtime endpoints. Compatibility
+checks should use the first merged versioned-contract commit as their baseline,
+not the old unversioned sources.


+	ExtensionLegacyGrpcCallCount = AttributeKey{
+		Key:            attribute.Key("extension.grpc.legacy_call_count"),
+		Classification: SystemMetadata,
+		Purpose:        FeatureInsight,
+		IsMeasurement:  true,


Move ComposeService and CopilotService out of the stable v1 contracts, register their native beta implementations, and preserve their frozen legacy aliases during migration. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7d1a4605-370b-43ca-9845-979dd2b4ada3

Copilot

Pull request overview

Copilot reviewed 106 out of 198 changed files in this pull request and generated 5 comments.

Suppressed comments (1)

cli/azd/internal/tracing/fields/fields.go:1227

This new telemetry field requires a privacy review before merge, but the PR checklist still leaves “Privacy review triggered” unchecked. Complete and record that review before landing the field, as required by cli/azd/AGENTS.md:329-334.

 	"github.com/azure/azure-dev/cli/azd/extensions/microsoft.azd.ai.builder/internal/pkg/qna"
 	"github.com/azure/azure-dev/cli/azd/extensions/microsoft.azd.ai.builder/internal/pkg/util"
 	"github.com/azure/azure-dev/cli/azd/pkg/azdext"
+	v1beta "github.com/azure/azure-dev/cli/azd/pkg/azdext/contracts/v1beta"


 	"strings"

 	"github.com/azure/azure-dev/cli/azd/pkg/azdext"
+	v1beta "github.com/azure/azure-dev/cli/azd/pkg/azdext/contracts/v1beta"


 syntax = "proto3";

-package azdext;
+package azd.extensions.v1;


+proto-breaking:
+	@test -n "$(BUF_BREAKING_AGAINST)" || \
+		(echo "set BUF_BREAKING_AGAINST to a Buf module, image, or Git source" && exit 1)
+	$(BUF) breaking grpc --against "$(BUF_BREAKING_AGAINST)"


+`Compose()` and `Copilot()` are preview accessors. Import
+`github.com/azure/azure-dev/cli/azd/pkg/azdext/contracts/v1beta` for their
+request, response, and enum types. They are intentionally excluded from the
+stable `azdext` contract façade until those services graduate to `v1`.


Version extension gRPC contracts

165d9bb

Establish stable v1 and preview v1beta protobuf packages, separate generated contracts from the handwritten azdext SDK, and register both contract channels in the host. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

microsoft-github-policy-service Bot assigned Victor Vazquez (vhvb1989) Aug 26, 2026

github-actions Bot added the area/extensions Extensions (general) label Aug 26, 2026

Richard Park (richardpark-msft) mentioned this pull request Aug 27, 2026

Make underpinnings of azd layer-aware #9767

Open

Victor Vazquez (vhvb1989) requested a balanced review from Copilot August 28, 2026 19:15

Copilot started reviewing on behalf of Victor Vazquez (vhvb1989) August 28, 2026 19:16 View session

Copilot AI reviewed Aug 28, 2026

View reviewed changes

Comment thread cli/azd/grpc/proto/azd/extensions/v1beta/workflow.proto Outdated

Comment thread cli/azd/grpc/proto/azd/extensions/v1beta/deployment.proto Outdated

Comment thread cli/azd/grpc/README.md Outdated

Victor Vazquez (vhvb1989) requested a balanced review from Copilot August 28, 2026 19:29

Copilot started reviewing on behalf of Victor Vazquez (vhvb1989) August 28, 2026 19:30 View session

github-actions Bot added the ext-x microsoft.azd.extensions developer extension (azd x) label Aug 28, 2026

Copilot AI reviewed Aug 28, 2026

View reviewed changes

Comment thread cli/azd/extensions/microsoft.azd.extensions/internal/resources/languages/proto/models.proto

Victor Vazquez (vhvb1989) requested a balanced review from Copilot August 28, 2026 19:42

Copilot started reviewing on behalf of Victor Vazquez (vhvb1989) August 28, 2026 19:42 View session

Copilot AI reviewed Aug 28, 2026

View reviewed changes

Victor Vazquez (vhvb1989) marked this pull request as ready for review August 31, 2026 04:55

Victor Vazquez (vhvb1989) requested review from a team, JeffreyCA, Rick Winter (RickWinter), Marina He (hemarina), Richard Park (richardpark-msft) and tg-msft as code owners August 31, 2026 04:55

Victor Vazquez (vhvb1989) added the skip-governance Skip PR governance checks label Aug 31, 2026

JeffreyCA reviewed Aug 31, 2026

View reviewed changes

Comment thread cli/azd/internal/grpcserver/versioned_services.go

Copilot AI review requested due to automatic review settings September 1, 2026 18:35

Copilot started reviewing on behalf of Victor Vazquez (vhvb1989) September 1, 2026 18:36 View session

github-actions Bot mentioned this pull request Sep 1, 2026

[aw] Extension PR Labeler failed #9814

Open

Copilot AI reviewed Sep 1, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings September 1, 2026 19:00

Copilot started reviewing on behalf of Victor Vazquez (vhvb1989) September 1, 2026 19:01 View session

Copilot AI reviewed Sep 1, 2026

View reviewed changes

Uh oh!

Conversation

Victor Vazquez (vhvb1989) commented Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why this design

Compatibility bridge and rollout

Preview-only services

Extension compatibility scenarios

Migrating an extension

Existing extension to stable v1

Stable v1 extension opting into a beta feature

Moving a beta feature back to stable v1

Can one extension mix v1 and v1beta?

Versioning model

Testing

Telemetry Change Checklist

New Fields

New Events

Privacy

Testing

Downstream

Documentation

Uh oh!

azure-pipelines Bot commented Aug 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

azure-pipelines Bot commented Aug 31, 2026

Uh oh!

azure-sdk-automation Bot commented Aug 31, 2026

Azure Dev CLI Install Instructions

Install scripts

MacOS/Linux

Windows

Standalone Binary

MSI

Documentation

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: 08/31/2026 ms.service: azure-dev-cli ms.topic: reference ms.custom: devx-track-azdevcli

Azure Developer CLI reference

azd

Options

See also

azd add

Options

Options inherited from parent commands

See also

azd auth

Options

Options inherited from parent commands

See also

azd auth login

Synopsis

Options

Options inherited from parent commands

See also

azd auth logout

Synopsis

Options

Options inherited from parent commands

See also

azd auth status

Synopsis

Options

Options inherited from parent commands

Victor Vazquez (vhvb1989) commented Aug 26, 2026 •

edited

Loading

Existing extension to stable `v1`

Stable `v1` extension opting into a beta feature

Moving a beta feature back to stable `v1`

Can one extension mix `v1` and `v1beta`?

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: 08/31/2026
ms.service: azure-dev-cli
ms.topic: reference
ms.custom: devx-track-azdevcli