Tell us about your PDF experience.

Azure Developer CLI (azd)

The Azure Developer CLI (azd) is an open-source tool that accelerates your path from a
local development environment to Azure. azd provides a set of developer-friendly
commands that map to key stages in your workflow (code, build, deploy, monitor). The
CLI allows you to work consistently in a repeatable way across the terminal, your
editor/integrated development environment, GitHub Actions pipeline, and more.

Get started

ｂ GET STARTED

What is Azure Developer CLI (azd)?

Install azd

Deploy an azd template

Supported languages and environments

Training - Introduction to Azure Developer CLI

Work with templates

ｇ TUTORIAL

Explore azd templates

Visit the template gallery

Make your project azd compatiable

Training - Build and deploy azd templates

Configure deployment pipeline

Customization and configuration

ｇ TUTORIAL

Manage environment variables

Use terraform with azd

Customize workflows using hooks

Remote environment support

Troubleshooting

Popular templates

ｓ SAMPLE

Visit the template gallery

ToDo C# Azure Cosmos DB

ToDo C# Azure SQL Database

ToDo Java Mongo

ToDo NodeJs MongoDB

ToDo Python MongoDB

Video content

ｄ TRAINING

Introducing the Azure Developer CLI - Azure Friday

Azure Developer CLI - GitHub Universe presentation

Azure Developer CLI YouTube playlist

Community standups

Get help & provide feedback

ｃ HOW-TO GUIDE

Troubleshoot & Get help

Frequently asked questions (FAQ)

ｉ REFERENCE
Azure Developer CLI Reference
What is the Azure Developer CLI?
Article • 09/12/2024

The Azure Developer CLI ( azd ) is an open-source tool that accelerates your path from a
local development environment to Azure. azd provides best practice, developer-friendly
commands that map to key stages in your workflow, whether you're working in the
terminal, your editor or integrated development environment (IDE), or CI/CD
(continuous integration/continuous deployment).

You can use azd with extensible blueprint templates that include everything you need to
get an application up and running on Azure. These templates include reusable
infrastructure as code assets and proof-of-concept application code that can be
replaced with your own app code. You can also create your own template or find one to
build upon.

Typical azd workflow

Once you've installed Azure Developer CLI, you can get your app running on Azure in
just a few steps.

1. Select an Azure Developer CLI template.

2. Initialize the project with the template by running azd init
3. Package, provision and deploy the app by running azd up.
4. Continue iterating on your application code and deploying changes as needed by
running azd deploy
5. Update Azure resources by modifying the template's Infrastructure as Code (IaC)
and then running azd provision (optional)

Introductory video
https://www.youtube-nocookie.com/embed/9z3PiHSCcYs

Check out our Azure Developer CLI playlist !

Next steps
View supported languages and environments
Install the Azure Developer CLI.
Walk through the azd quickstart to see Azure Developer CLI in action.
Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Install or update the Azure Developer
CLI
Article • 11/27/2024

Welcome to the Azure Developer CLI ( azd )! Let's get started with installing and learning
how to run azd .

Start by selecting your development environment. For more information about the pros
and cons of the different development environment choices, see Azure Developer CLI
(azd) supported environments.

For more advanced installation scenarios and instructions, see Azure Developer CLI
Installer Scripts .

Note: When you install azd , the following tools are installed within azd scope (meaning
they aren't installed globally) and are removed if azd is uninstalled:

The GitHub CLI

The Bicep CLI

Windows Package Manager (winget)

Install azd
PowerShell

winget install microsoft.azd

Update azd
PowerShell

winget upgrade microsoft.azd

Uninstall azd
PowerShell
 winget uninstall microsoft.azd

Verify your installation

Verify your azd installation completed successfully by running the azd version
command in a terminal:

Azure Developer CLI

azd version

azd prints the current version:

Output

azd version 1.9.5 (commit cd2b7af9995d358aab33c782614f801ac1997dde)

Update the Azure Developer CLI

When working with an out of date version of azd , you'll see a warning to upgrade to the
latest version. Follow the instructions in the warning to update to the latest version.

Request help
For information on how to file a bug, request help, or propose a new feature for the
Azure Developer CLI, please visit the troubleshooting and support page.

Next steps
Quickstart - Select and deploy an azd template

What are Azure Developer CLI templates?

Azure Developer CLI FAQ

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Quickstart: Deploy an Azure Developer
CLI template
Article • 12/22/2024

In this quickstart, you'll learn how to provision and deploy app resources to Azure using
an Azure Developer CLI (azd) template and only a few azd commands. azd templates
are standard code repositories that include your application source code, as well as azd
configuration and infrastructure files to provision Azure resources. To learn more about
azd templates and how they can accelerate your Azure provisioning and deployment

process see What are Azure Developer CLI templates?.

Select and deploy the template

For the steps ahead, you'll use the following template to provision and deploy an app
on Azure:

React Web App with Node.js API and MongoDB on Azure

You can also select a template that matches your preferences from the Awesome AZD
template gallery site. Regardless of which template you use, you'll end up with the
template code in your development environment and be able to run commands to
build, redeploy, and monitor the app in Azure.

Select your preferred environment to continue:

Local install

A local development environment is a great choice for traditional development

workflows. You'll clone the template repository down onto your device and run
commands against a local installation of azd .

Prerequisites
Install the Azure Developer CLI.
An Azure account with an active subscription. Create one for free .
Node.js with npm (v 16.13.1 LTS)
Review the architecture diagram and the Azure resources you'll deploy in the
Node.js template README .
Initialize the project
1. In File Explorer or a terminal, create a new empty directory, and change into it.

2. Run the azd init command and specify the template you want to use as a
parameter:

Azure Developer CLI

azd init --template todo-nodejs-mongo

Enter an environment name when prompted, such as azdquickstart , which

sets a naming prefix for the resource group that will be created to hold the
Azure resources. What is an Environment Name in azd?

After you specify the environment, azd clones the template project to your
machine and initializes the project.

Provision and deploy the app resources

1. Run the azd auth login command and azd launches a browser for you to
complete the sign-in process.

Azure Developer CLI

azd auth login

2. Run the azd up command:

Azure Developer CLI

azd up

3. Once you are signed-in to Azure, you will be prompted for the following
information:

ﾉ Expand table

Parameter Description

Azure Location The Azure location where your resources will be deployed.

Azure Subscription The Azure Subscription where your resources will be deployed.
 Select your desired values and press enter. The azd up command handles the
following tasks for you using the template configuration and infrastructure
files:

Creates and configures all necessary Azure resources ( azd provision ),

including:
Access policies and roles for your account
Service-to-service communication with Managed Identities
Packages and deploys the code ( azd deploy )

When the azd up command completes successfully, the CLI displays two links
to view resources created:

ToDo API app

ToDo web app frontend

７ Note

You can call azd up as many times as you like to both provision and
deploy updates to your application. The deployment may fail due to a
resource being undeployable in the selected region. Because this is a
quick start, it is safe to delete the .azure directory and try azd up again.
When asked, select a different region. In a more advanced scenario you
could selectively edit files within the .azure directory to change the
region.

Clean up resources
When you no longer need the resources created in this article, run the following
command to power down the app:

Azure Developer CLI

 azd down

If you want to redeploy to a different region, delete the .azure directory before running
azd up again. In a more advanced scenario you could selectively edit files within the

.azure directory to change the region.

Request help
For information on how to file a bug, request help, or propose a new feature for the
Azure Developer CLI, please visit the troubleshooting and support page.

Next steps
Learn how to run and debug apps with azd.
Troubleshoot common problems when using Azure Developer CLI (azd).
Read the Azure Developer CLI frequently asked questions (FAQ).

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Explore and customize an Azure Developer
CLI template
Article • 04/16/2025

In this quickstart, you explore and customize an Azure Developer CLI template. The hello-azd
template provides a simple starting point for building and deploying applications to Azure
using the Azure Developer CLI ( azd ). This quickstart expands on the concepts demonstrated in
the Quickstart - Deploy an azd template article.

Prerequisites
To complete this quickstart in your browser you'll need:

Access to GitHub Codespaces

Alternatively, to complete this quickstart using local tooling:

The Azure Developer CLI installed on your local machine

Visual Studio Code or your editor of choice
Docker desktop installed on your local machine

Explore Azure Developer CLI template structure

azd templates are standard code repositories with additional assets included. All azd

templates share a similar file structure based on azd conventions:

infra folder - Contains all of the Bicep or Terraform infrastructure as code files for the
azd template. azd executes these files to create the Azure resources required by your

app.
src folder - Contains the app source code. azd packages and deploys the code based on

configurations in azure.yaml .
azure.yaml file - A configuration file that maps source code folders in your project to

Azure resources defined in the infra folder for deployment. For example, you might
define an API service and a web front-end service in separate folders and map them to
different Azure resources for deployment.
.azure folder - Contains essential Azure configurations, such as the location to deploy

resources.

For example, most azd templates match the following folder structure:
Visit the Azure Developer CLI templates overview article for more details about azd template
structure.

Set up the sample template

hello-azd is a sample template designed to showcase essential features of azd that you can

deploy to Azure using a single command. The template provides a friendly UI with information
about azd and a small demo tool that allows you to upload and view support tickets.

The template supports the following features:

Packages and deploys a containerized app to Azure Container Apps

Creates the Azure resources needed by the app, such as an Azure Cosmos DB database
Can automatically Configure a CI/CD pipeline using the azd pipeline config command

Follow these steps to set up the template:

Codespaces

1. Open the hello-azd template repository on GitHub.

2. Select the Code button and then select Codespaces.

3. Create a new Codespace to launch a fully configured development environment in

your browser. You might need to wait a moment for the environment to initialize.

4. After the Codespaces environment loads, initialize the azd template using the azd
init command:

Bash

azd init -t hello-azd

 5. When prompted, enter a name for the azd environment, such as helloazd .

Explore the template

With the template open in your tool of choice, you can browse the folder structure to explore
how azd templates work:

1. Expand the src folder to view the source code of the app.

The hello-azd template includes a containerized .NET app that provides a simple UI
to learn about azd and manage sample ticket data. azd also supports other
languages like JavaScript and Python.
When you run azd up , the app is packaged as a container image and deployed to
Azure Container Apps.

2. Expand the infra folder to explore the infrastructure as code files.

This template uses Bicep files ( .bicep ) to create Azure resources, but you can also
use Terraform ( .tf ).

The main.bicep file creates Azure resources by referencing other Bicep modules in
the infra folder, such as an Azure Storage account:

Bicep

// Omitted...

// Create a storage account

module storage './core/storage/storage-account.bicep' = {
name: 'storage'
scope: rg
params: {
name: !empty(storageAccountName) ? storageAccountName :
'${abbrs.storageStorageAccounts}${resourceToken}'
location: location
tags: tags
containers: [
{
name: 'attachments'
}
]
}
}

// Omitted...
 3. At the root of the template, open the azure.yaml file to view essential template
configurations:

The template defines one service called aca .

The aca service configuration instructs azd to package and deploy the source code
in the src folder to the Azure Container App provisioned by the Bicep modules you
explored previously.

The docker configurations instruct azd to package and deploy the app as a
container.

yml

metadata:
template: hello-azd-dotnet # Specifies the template being used
name: azd-starter # Name of the project
services:
aca: # Define the Azure Container App service
project: ./src # Path to the source code
language: csharp # Programming language
host: containerapp # Hosting service
docker:
path: ./Dockerfile # Location of the Dockerfile

Update the Template

You can make changes to the template to influence the deployed app and resources. In this
example, you make two small changes to the app and explore the deployed results:

Update the app header welcome text to your own message

Update the created storage account so that it creates two blob containers instead of one

To make these changes, complete the following steps:

1. In the src > Components > Pages folder, open the Home.razor component.

2. Replace the Hello, Azure Developer CLI! header text at the top of the page with a different
message, such as Hello, customized template! and save your changes.

razor

<MudText Typo="Typo.h2" GutterBottom="true">Hello, customized template!

</MudText>
3. In the infra folder, open the main.bicep file.

4. Locate the block of Bicep code around line 75 that creates a storage account and a blob
container:

Bicep

// Create a storage account

module storage './core/storage/storage-account.bicep' = {
name: 'storage'
scope: rg
params: {
name: !empty(storageAccountName) ? storageAccountName :
'${abbrs.storageStorageAccounts}${resourceToken}'
location: location
tags: tags
containers: [
{
name: 'attachments'
}
]
}
}

Replace the code with the following snippet:

Bicep

// Create a storage account

module storage './core/storage/storage-account.bicep' = {
name: 'storage'
scope: rg
params: {
name: !empty(storageAccountName) ? storageAccountName :
'${abbrs.storageStorageAccounts}${resourceToken}'
location: location
tags: tags
containers: [
{
name: 'attachments'
},
{
name: 'archive'
}
]
}
}
Run the Template
After making your changes, use the azd up command to provision and deploy the app
resources:

1. Open a terminal in the project directory.

2. To provision and deploy the template, run the azd up command:

Azure Developer CLI

azd up

This command will:

Package the app for deployment

Provision the required Azure resources
Deploy your application with the updated changes
Print the URL for the deployed application

3. To see your updated application live, open the URL printed in the azd console output
logs in your browser.

4. To view the two blob containers that were created, navigate to the created storage
account in the Azure portal.
Conclusion
In this quickstart, you explored the structure of the hello-azd template, customized its
application and infrastructure, and deployed it to Azure using the Azure Developer CLI. For
more advanced scenarios, explore other templates or dive deeper into the azd documentation.

Next steps
What are Azure Developer CLI commands?
What are Azure Developer CLI templates?
Create Azure Developer CLI templates overview
Explore the Azure Developer CLI template
galleries
Article • 04/14/2025

Azure Developer CLI ( azd ) templates simplify the process of building, provisioning, and
deploying applications on Azure. This document explores what these templates are, their
purpose, and the available galleries, including Awesome AZD and the AI Template Gallery.

What are Azure Developer CLI templates?

Azure Developer CLI templates are standardized project structures that include application
code, infrastructure as code (IaC) files, and deployment configurations. These templates are
designed to help developers quickly set up and deploy full-stack applications on Azure. They
provide a starting point for common application architectures and integrate seamlessly with
Azure services.

Key features of Azure Developer CLI templates:

Include infrastructure as code to create app resources like Azure App Service or Azure
OpenAI
Define deployment configurations to package and deploy apps built with various
languages
Enable simplified, automated workflows for provisioning resources and deploying
applications
Provide starting points or architectural examples for building cloud-native apps

For more detailed information on azd templates, visit the templates overview page.

What are template galleries?

Template galleries offer curated collections of reusable azd templates to help you get started
with building and deploying applications on Azure. They provide developers with various
ready-to-use templates for different use cases, such as web applications, AI-powered solutions,
and microservices architectures.

These galleries help developers:

Quickly prototype and deploy applications

Explore sample architectures for specific scenarios
Learn best practices for Azure app development
Share and build on community-contributed templates
Explore the galleries
You can explore templates from different galleries using a local editor like Visual Studio Code,
or directly in the browser with GitHub Codespaces. The following sections highlight two key
galleries that showcase different types of templates for various use cases.

Awesome AZD
Awesome AZD is a community-driven collection of Azure Developer CLI templates, tools,
and resources. It includes templates for various application types, contributed by both
Microsoft and the developer community. The gallery is designed to showcase best practices
and innovative use cases for azd .

Key highlights of Awesome AZD:

Templates for web apps, APIs, microservices, and more

Community-contributed examples for real-world scenarios
Resources for extending and customizing Azure Developer CLI workflows

To learn more or contribute to the Awesome AZD gallery, visit the Awesome AZD GitHub
repository .

The AI App Templates gallery

The AI App Templates gallery is a specialized collection of Azure Developer CLI templates
focused on AI-powered applications. These templates help developers quickly build intelligent
solutions by integrating with Azure AI services such as Azure OpenAI and Azure AI Foundry.
Key highlights of the AI Template Gallery:

Templates for chatbots, recommendation systems, and other AI use cases.

Preconfigured infrastructure for integrating Azure AI services.
Examples of how to use AI capabilities in cloud-native applications.

The AI Template Gallery simplifies the process of building and deploying AI-driven applications
by providing ready-to-use templates and best practices.

Add your own custom template sources

In addition to using the predefined galleries, you can also add your own template sources to
customize your development workflow. This allows you to create and share templates tailored
to your specific needs or organization.

To add a custom template source:

1. Create a repository containing your templates. Each template should follow the Azure
Developer CLI template structure, including application code, infrastructure as code files,
and deployment configurations.

2. Use the azd template command to add your repository as a source. For example:

Bash

azd template add --source <repository-url>

3. Once added, you can list and use your custom templates just like the predefined ones:
 Bash

azd template list

By adding your own template sources, you can extend the capabilities of the Azure Developer
CLI and streamline development for your team or projects.

Conclusion
Azure Developer CLI template galleries, such as Awesome AZD and the AI Template Gallery,
provide developers with powerful starting points for building and deploying applications on
Azure. Whether you're creating a web app, exploring AI capabilities, or learning best practices,
these galleries offer valuable resources to accelerate your development process.
Supported languages and environments
Article • 09/13/2024

Supported development environments

You can run any azd template, in one of the following supported development
environments:

ﾉ Expand table

Environment Description Pros Cons Feature

Stage

Local Machine Not in a container, You control all You have to manually Stable
via CLI dependencies are dependencies. You install all
manually installed may already have dependencies.
by you, and the some of the
project is run on dependencies
your local machine. installed. You don't
need Docker
installed.

Visual Studio Run and debug You can work with Requires installing an Beta
Code azd templates azd using a code extension.
using the Visual editor and extension
Studio Code system you may
extension . already be
comfortable with.

Visual Studio Run and debug You can work with Requires installing a Alpha
azd templates azd using an IDE you separate preview
using Visual Studio may already be version of Visual
(preview) . comfortable with. Studio.

DevContainer / Container with all Other than VS Code, You need to clone the Beta
VS Code dependencies Docker, and the repository. The
Remote - installed and run Remote Containers container
Containers on your local VS Code extension, initialization can take
machine. all dependencies are a long time.
installed for you in
the DevContainer.

GitHub Container with all All dependencies are Run and debug that Beta
Codespaces dependencies installed without requires launching a
installed and cloning the code web browser is
running on locally. currently not
 Environment Description Pros Cons Feature
Stage

GitHub.com in the supported because of

browser. known limitation with
GitHub
Codespaces .

Supported Azure compute services (host)

azd supports several services for hosting your app. Services marked as alpha are

experimental and need to be enabled manually with azd config to use them. beta
features may experience breaking changes. stable features are not expected to
experience breaking changes.

For more information about each feature stage, see feature versioning and release
strategy. For a list of all features and their stages, see Alpha, Beta, and Stable Feature
Stages .

ﾉ Expand table

Azure compute service Feature Stage

Azure App Service Stable

Azure Static Web Apps Stable

Azure Container Apps Beta

Azure Functions Stable

Azure Kubernetes Service Beta (only for projects deployable via kubectl apply -f )

Azure Spring Apps Beta

Supported languages and frameworks

Currently supported languages and frameworks:

ﾉ Expand table

Language Feature Stage

Node.js Stable
 Language Feature Stage

Python Stable

.NET Stable

Java Stable

For more information about each feature stage, see feature versioning and release
strategy

Next Steps
Install the Azure Developer CLI.
Walk through the azd quickstart to see Azure Developer CLI in action.

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Azure Developer CLI vs Azure CLI overview
Article • 04/14/2025

Azure provides multiple command-line tools to help users interact with cloud services. Two of
the most commonly used tools are the Azure Developer CLI and the Azure CLI. While both
options enable users to manage and deploy resources on Azure, they're designed for different
audiences and use cases. The following sections provide an overview of each tool, highlight
their differences, and offer comparisons to help you select the best tool for different situations.

What is the Azure Developer CLI?

The Azure Developer CLI ( azd ) is a developer-focused command-line tool designed to
streamline the process of building, provisioning, deploying, and managing full-stack apps on
Azure. Key features include:

High-level commands oriented around app lifecycle stages, such as provisioning and
deployment
A template system to define infrastructure as code and deployment configurations for
your app
Automated provisioning and deployment of app resources
Built-in CI/CD pipeline setup for GitHub Actions or Azure Pipelines
Galleries of starter app templates for common app architectures

What is the Azure CLI?

The Azure CLI ( az ) is a general-purpose command-line interface for managing Azure
resources. It provides a comprehensive set of commands to create, configure, delete, and
monitor resources programmatically or interactively. Key features include:

Granular administrative control over Azure resources

Support for scripting and task automation
Integration with a wide range of Azure services and tools
Resource management across many tenants, subscriptions, and environments

How are the tools different?

While both the Azure Developer CLI and Azure CLI provide command-line interfaces for Azure,
they serve different purposes and audiences:
 Azure Developer CLI: Focuses on simplifying the developer experience by providing an
opinionated workflow for building and deploying applications. It abstracts much of the
complexity of resource management and is tailored for application-centric tasks.
Azure CLI: Offers granular control over Azure resources and is designed for a broader
audience, including IT administrators, DevOps engineers, and developers. It provides
flexibility for managing individual resources but requires knowledge of specific Azure
services.

Compare commands
You can print the available commands for both CLI tools to visualize these differences. For
example, run the Azure Developer CLI command azd help to view information about the tool
and available commands:

Output

Usage
azd [command]

Commands
Configure and develop your app
auth : Authenticate with Azure.
config : Manage azd configurations (ex: default Azure subscription,
location).
hooks : Develop, test and run hooks for an application. (Beta)
init : Initialize a new application.
restore : Restores the application's dependencies. (Beta)
template : Find and view template details. (Beta)

Manage Azure resources and app deployments

deploy : Deploy the application's code to Azure.
down : Delete Azure resources for an application.
env : Manage environments.
package : Packages the application's code to be deployed to Azure. (Beta)
provision : Provision the Azure resources for an application.
up : Provision Azure resources, and deploy your project with a single
command.

Monitor, test and release your app

monitor : Monitor a deployed application. (Beta)
pipeline : Manage and configure your deployment pipelines. (Beta)
show : Display information about your app and its resources.

The commands in the preceding output map to high level development workflow concerns,
such as managing app deployments, app configuration, and monitoring.

However, if you run the az help command for the Azure CLI, you see output that resembles
the following output:
 Output

Group
az

Subgroups:
account : Manage Azure subscription information.
acr : Manage private registries with Azure Container
Registries.
ad : Manage Microsoft Entra ID (formerly known as
Azure Active
Directory, Azure AD, AAD) entities needed for
Azure role-based
access control (Azure RBAC) through Microsoft
Graph API.
advisor : Manage Azure Advisor.
afd : Manage Azure Front Door Standard/Premium.
aks : Manage Azure Kubernetes Services.
ams : Manage Azure Media Services resources.
apim : Manage Azure API Management services.
appconfig : Manage App Configurations.
appservice : Manage App Service plans.
aro : Manage Azure Red Hat OpenShift clusters.
backup : Manage Azure Backups.
batch : Manage Azure Batch.
bicep : Bicep CLI command group.
billing : Manage Azure Billing.
bot : Manage Microsoft Azure Bot Service.
cache : Commands to manage CLI objects cached using
the `--defer`

(omitted for brevity...)

In the preceding output, all of the commands focus on managing configurations for specific
Azure resources, such as Azure Container Registries or Azure Billing services.

Compare features
The following table highlights the key differences between the Azure Developer CLI and the
Azure CLI in more detail:

ﾉ Expand table

Functionality Azure Developer CLI ( azd ) Azure CLI ( az )

Primary Developers focused on building cloud- Developers, IT admins, and DevOps

audience native apps engineers

Primary use case End-to-end app lifecycle management Azure resource administration &
 Functionality Azure Developer CLI ( azd ) Azure CLI ( az )

management

Type of tasks Provisioning and deploying app resources, Resource administration and scripting
CI/CD pipeline setup

Command Opinionated, high-level commands for Flexible, low-level commands for

behavior common workflows granular control

Template Includes predefined templates for common No templates; requires manual

support architectures resource configuration

IaC support Native support for IaC tools like Bicep and Requires separate IaC setup and
Terraform integration

CI/CD Automates pipeline setup for GitHub No built-in CI/CD automation

Integration Actions or Azure Pipelines

Compare use cases

Choosing the right tool depends on your specific needs and the tasks you want to accomplish.
Below are examples of scenarios where each tool excels to help you decide which one to use
for your workflow.

When to Use the Azure Developer CLI

The Azure Developer CLI is best suited for scenarios where you need to manage the end-to-
end workflow for application development and deployment. Example use cases include:

Packaging, provisioning and deploying full-stack cloud-native apps in a portable,

repeatable way
Quickly provisioning sample app architectures using predefined templates for rapid
prototyping
Setting up CI/CD pipelines for GitHub Actions or Azure Pipelines with minimal effort

When to Use the Azure CLI

The Azure CLI is ideal for scenarios that require granular control over individual Azure
resources or advanced scripting capabilities. Example use cases include:

Creating, configuring, or deleting Azure resources

Automating resource management using custom scripts
Monitoring and troubleshooting Azure resources
Integrating resource management into broader DevOps workflows
By understanding these use cases, you can determine which tool is better suited for your
specific needs or use both tools in combination to maximize efficiency.

Conclusion
The Azure Developer CLI and Azure CLI are complementary tools designed for different
audiences and use cases. The Azure Developer CLI simplifies app packaging, provisioning, and
deployment for developers, while the Azure CLI provides granular control for administrative
tasks. Depending on your role and requirements, you can use one or both tools to achieve
your goals on Azure.
Explore the azd up workflow
Article • 04/29/2025

The Azure Developer CLI ( azd ) enables you to provision and deploy application resources on
Azure with only a single command using azd up . This guide provides a detailed breakdown of
azd up and how the different stages of this workflow command correlate to the structure of an

azd template.

Follow along using a template

The sections ahead use examples from the hello-azd template to demonstrate various azd
concepts and patterns. You can follow along by initializing the template on your local machine:

Azure Developer CLI

azd init -t hello-azd

For more information about getting started with azd and the hello-azd template, visit the
Quickstart: Deploy an Azure Developer CLI template article.

Essential concepts
When working with an azd template, you can provision and deploy your app resources on
Azure using the azd up command. Run the command from a terminal window that is open to
your template folder:

Azure Developer CLI

azd up

azd up is designed so that you can repeatedly run the command as you develop your app, and

the new changes are deployed incrementally. The command initiates a powerful workflow that
essentially wraps three specific stages:

1. Packaging: Prepares the application code and dependencies for deployment.

2. Provisioning: Creates and configures the necessary Azure resources required by the app
using infrastructure-as-code files.
3. Deployment: Deploys the packaged application to the provisioned Azure resources.

You can also run each of these stages individually using their respective command, but azd up
provides a convenience wrapper to streamline the overall process. Each stage plays a critical
role in ensuring a smooth and automated deployment process. You can influence the azd up
workflow stages using configurations in the template azure.yaml file. The following sections
explore each stage in more detail.

The packaging stage

The packaging stage is the first step in the azd up workflow. During this stage:

The app code is prepared for deployment. Depending on the programming language the
template app is built with, packaging can involve building or compiling the app, bundling
dependencies, or creating deployment artifacts such as Docker images.
The azd template structure typically includes a src folder where the application code
resides. Build scripts or configuration files (such as a Dockerfile) can influence how the
application should be packaged.
The azure.yaml file contains configuration mappings that tell azd where your app code
lives and which language it uses so azd can package it appropriately.
This stage ensures that the application is in a deployable state before moving to the next
step.

You can run the packaging process on its own outside of azd up using the azd package
command:

Azure Developer CLI

azd package

Example packaging configurations

azd can package apps built with different languages in different ways. For example, if your app
uses a containerized approach, the azd template might include a Dockerfile in the app src
directory. The packaging stage builds a Docker image for the app based on this file. These
configurations are managed through the azure.yaml file.

For example, consider the following project structure and configurations of the hello-azd
starter template:
In the preceding image, the azure.yaml file:

Defines the code in the src directory as a C# app.

Specifies the location of a Dockerfile to use to build a container image of the app.

When you run azd up (or azd package ), the Azure Developer CLI uses this combination of
configurations to build and package the app code in the src directory as a .NET container
image. If a Dockerfile wasn't configured, azd could also package the .NET app using the
standard .NET publishing process.

The provisioning stage

The provisioning stage creates and configures the required Azure resources for your app. For
example, your app might require an Azure App Service instance to host the app itself, and an
Azure Storage Account to hold uploaded files. The provisioning stage uses infrastructure-as-
code (IaC) files included in the template to define the resources.

Some key points to understand about the provisioning stage include:

1. azd supports both Bicep and Terraform for infrastructure-as-code tasks.

 2. By default, infrastructure-as-code files are stored in the infra folder, but this location can
be customized.
3. azd searches for a main.bicep or main.tf file to act as the main orchestration file for the
IaC process.

You can also run the provisioning process on its own outside of azd up using the azd
provision command:

Azure Developer CLI

azd provision

Example provisioning configurations

Inside the infra folder, a main.bicep file generally defines the Azure resources that azd
should create for the app. Consider the following snippet from main.bicep in the hello-azd
starter template:

Bicep

// ...omitted code for other resource configurations

// Create an Azure Cosmos DB account

 module cosmos 'app/cosmos.bicep' = {
name: 'cosmos'
scope: rg
params: {
userPrincipalId: principalId
managedIdentityId: identity.outputs.principalId
}
}

// Create a storage account

module storage './core/storage/storage-account.bicep' = {
name: 'storage'
scope: rg
params: {
name: !empty(storageAccountName) ? storageAccountName :
'${abbrs.storageStorageAccounts}${resourceToken}'
location: location
tags: tags
containers: [
{ name: 'attachments' }
]
}
}

// Container apps environment and registry

module containerAppsEnv './core/host/container-apps.bicep' = {
name: 'container-apps'
scope: rg
params: {
name: 'app'
containerAppsEnvironmentName: !empty(containerAppsEnvName) ?
containerAppsEnvName : '${abbrs.appManagedEnvironments}${resourceToken}'
containerRegistryName: !empty(containerRegistryName) ? containerRegistryName :
'${abbrs.containerRegistryRegistries}${resourceToken}'
location: location
}
}

// ...omitted code for other resource configurations

Using the preceding Bicep code, azd creates the following resources:

An Azure Cosmos DB instance to store data submitted through the app

An Azure Storage account to store uploaded images
An Azure Container App to host the app

The deployment stage

The deployment stage is the final step in the azd up workflow. During this stage:
 The app artifacts created during the packaging stage are deployed to the provisioned
Azure resources.
azd uses configuration files in the template, such as azure.yaml , to determine how to

deploy the app.

Environment variables and connection strings are configured to ensure the app can
interact with the provisioned resources.

You can also run the deployment process on its own outside of azd up using the azd deploy
command:

Azure Developer CLI

azd deploy

Example deployment configurations

Inside the azure.yaml file, you can specify which service in your project should be deployed to
which Azure resource. For example, consider the following configurations for the hello-azd
starter template:

YAML

metadata:
template: hello-azd-dotnet
name: azd-starter
services:
aca:
project: ./src # The location of the service source code
language: csharp
host: containerapp # The provisioned resource to deploy the service to
docker:
path: ./Dockerfile

The preceding code instructs azd to deploy the artifacts packaged from the code in the src
folder to the containerapp that was created during the provisioning stage. You can also define
multiple services and map each to a different host.

Conclusion
The azd up workflow streamlines the process of deploying applications to Azure by
automating the packaging, provisioning, and deployment stages. Developers can ensure a
consistent and efficient deployment process by adhering to the azd template structure.
Whether you're deploying a simple web app or a complex microservices architecture, the azd
up command simplifies the journey from code to cloud.
Azure Developer CLI commands
overview
Article • 01/21/2025

The Azure Developer CLI ( azd ) is designed to streamline the end-to-end developer
workflow on Azure. azd provides high-level commands that act as abstractions to
simplify common developer tasks such as project initialization, infrastructure
provisioning, code deployment, and monitoring. azd commands are available in the
terminal, an integrated development environment (IDE), or through CI/CD (continuous
integration/continuous deployment) pipelines. In this article, you'll learn about the
following:

Essential azd command concepts

How azd commands compare to other tools
The relationship between azd commands and templates
Common azd commands and which development tasks they accelerate

７ Note

Visit the Deploy an Azure Developer CLI template quickstart to explore a sample
azd command workflow in more detail.

Compare Azure Developer CLI commands

The emphasis on high-level development stages differentiates azd commands from
other command-line tools such as the Azure CLI or Azure PowerShell. Whereas those
tools provide numerous commands for granular control over individual Azure resources
and configurations, azd provides fewer, broader commands to automate higher-level
development tasks such as provisioning multiple resources or deploying multiple
services at once.

The following table highlights the differences between a sample azd command and
other Azure command-line tools. Note that the azd provision command performs
numerous tasks at once, and does not have a direct equivalent in these other tools.
Many Azure CLI or PowerShell commands would be required to accomplish the same
task.
 ﾉ Expand table

Tool Sample Command Outcome

Azure azd provision Provisions multiple Azure resources required for

Developer an app based on project resources and
CLI configurations, such as an Azure resource
group, an Azure App Service web app and app
service plan, an Azure Storage account, and an
Azure Key Vault.

Azure CLI az webapp create --resource- Provisions a new web app in the specified
group myResourceGroup --plan resource group and app service plan.
myAppServicePlan --name
myWebApp

Azure New-AzWebApp - Provisions a new web app in the specified

PowerShell ResourceGroupName resource group and app service plan.
"myResourceGroup" -Name
"myWebApp" -AppServicePlan
"myAppServicePlan"

Azure Developer CLI commands and templates

azd commands are able to perform broader workflow tasks due in-part to their

integration with the azd template system. Azure Developer CLI templates are code
projects that adhere to azd structural conventions and include sample application code,
infrastructure files, and configuration files. Most azd templates include the following:

.azure folder - Contains essential Azure configurations and environment variables,

such as the location to deploy resources or other subscription information.

infra folder - Contains all of the Bicep or Terraform infrastructure-as-code files for

the azd template.

src folder - Contains all of the deployable app source code.

azure.yaml file - A configuration file that defines one or more services in your

project and maps them to Azure resources defined in the infra folder for
deployment.
Without azd commands, these templates are just standard code repositories. Essentially,
azd templates serve as foundational blueprints, while CLI commands act as the engine

driving deployment, management, and monitoring of your applications. azd commands

use the assets in these templates to perform various tasks.

Using the preceding template as an example:

The azd provision command creates resources in Azure using the infrastructure-
as-code files in the infra folder of a template.
The azd deploy command deploys an app or service defined in the src folder.

７ Note

azd can also create and manage some Azure resources without the need to define

infrastructure-as-code templates manually using the new azd compose feature,

which is currently in alpha.

Explore common commands

The following sections provide an overview of some of the most common azd
commands to provide examples of working with templates and different development
tasks.

７ Note

For a complete list of azd commands and their parameters, visit the Azure
Developer CLI reference page.

Initialize and run a template

 azd init : Initializes an existing azd template or creates and initializes a new

template. This command essentially sets up the necessary files and directories to
start working with azd .
azd up : A convenience command to provision, package, and deploy all of your app

resources in one command. This command is the equivalent of running azd

provision , azd package , and azd deploy individually.

Infrastructure Provisioning
azd provision : Provisions the required Azure resources such as Azure Container

App instances or Azure Storage accounts based on infrastructure-as-code

templates or resources defined in azure.yaml .

Code Deployment
azd package : Packages the application's code to be deployed to Azure.
azd deploy : Deploys your application code to the resources created by the azd

provision command.

Monitoring and Management

azd monitor : Provides insights into the health and performance of the deployed

application

CI/CD Pipeline Configuration

azd pipeline config : Configures a CI/CD pipeline for the project. This command
sets up continuous integration and continuous deployment pipelines to automate
the build and deployment processes.

Environment Management
azd env list : Lists all the different environments (e.g., development, staging,

production) that have been set up for the template.

azd env new : Creates a new environment with its own configuration and resources,

allowing you to manage multiple environments for different stages of

development.

Resource Cleanup
 azd down : Deletes the Azure resources created by the template to clean up your

environment and avoid unnecessary costs.

Next steps
What are Azure Developer CLI templates?

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Azure Developer CLI templates overview
Article • 09/13/2024

Azure Developer CLI ( azd ) templates are regular code repositories that include sample
application code, as well as azd configuration and infrastructure files. azd templates
enable you to provision Azure resources, deploy your application, configure CI/CD
pipelines, and more. You can either create your own templates, or get started using an
existing template from a template repository such as Awesome AZD . In this article,
you'll learn about the following concepts:

How azd templates enable you to provision and deploy app resources
How azd templates are structured
How to decide whether to use an existing template or create one
Explore existing azd starter templates

Why use Azure Developer CLI templates?

Developers often face many time consuming and challenging tasks when building
properly architected and configured environment aware apps for the cloud. Teams must
account for many different concerns in these environments, such as creating resources,
applying configurations, setting up monitoring and logging, building CI/CD pipelines,
and other tasks. azd templates reduce and streamline these responsibilities to help the
developer on their journey from local development to a successfully deployed app on
Azure.

For example, suppose you work at a company that operates a ticket management and
customer communication platform, which requires the following Azure resources:

Two App Service instances and an App Service Plan to host a front-end web app
and back-end API
A Key Vault instance to store secure app secrets
A Cosmos DB database to permanently store app data
Azure Monitor resources such as Application Insights dashboards
A Service Bus to manage scalable messaging
CI/CD pipelines to ensure changes can be reliably deployed through an
automated, repeatable process.

Rather than starting from the ground up, with azd you can leverage existing
architecture templates to provision and deploy most of the resources for you. The
development team can then focus on building the app and making smaller adjustments
to the template architecture.

How Azure Developer CLI templates work

Azure Developer CLI templates are designed to work with azd commands such as azd
init and azd up . The templates include configuration and infrastructure-as-code (IaC)

files that are used by the commands to perform tasks such as provisioning Azure
resources and deploy the app code to them.

For example, a typical azd workflow using an existing template includes the following
steps:

1. Run the azd init command with the --template parameter to clone an existing
template down from GitHub.

Azure Developer CLI

azd init --template todo-nodejs-mongo

2. Run the azd auth login command to authenticate to your Azure subscription.

Azure Developer CLI

azd auth login

3. Run the azd up command to provision and deploy the template resources to
Azure. The azd up command leverages the configuration and infrastructure-as-
code (IaC) files in your template to provision Azure resources and deploy your
application to those resources.

Azure Developer CLI

azd up

4. Once your environment is set up in Azure, you can locally modify the application
features or Azure resource templates and then run azd up again to provision your
changes.
Understand Azure Developer CLI template
structure
All azd templates share a similar file structure based on azd conventions. Here are the
minimum required assets:

infra folder - Contains all of the Bicep or Terraform infrastructure as code files for

the azd template. azd executes these files to create the Azure resources required
to host your app.

azure.yaml file - A configuration file that defines one or more services in your

project and maps them to Azure resources defined in the infra folder for
deployment. For example, you might define an API service and a web front-end
service and map them to different Azure resources for deployment.

.azure folder - Contains essential Azure configurations and environment variables,

such as the location to deploy resources or other subscription information.

src folder - Contains all of the deployable app source code. Some azd templates

exclude the src folder and only provide infrastructure assets so you can add your
own application code.

７ Note

Templates that exclude the src folder are generally designed as infrastructure
starter templates.

azd templates also optionally include one or more of the following folders:

.github folder - Holds the CI/CD workflow files for GitHub Actions, the default

CI/CD provider for azd.

.azdo folder - If you decide to use Azure Pipelines for CI/CD, define the workflow

configuration files in this folder.

.devcontainer folder - Allows you to set up a Dev Container environment for
your application.

For example, a common azd template might match the following folder structure:
Start with an existing template or create your
own
There are two main approaches to working with azd templates:

Start with an existing azd template.

This is a good choice if you're just getting started with azd or if you're looking
for a template to build off of for a new app with a similar architecture and
frameworks.
Convert an existing project to an azd template.
This is a good choice when you already have an existing app but you want to
make it compatible with azd capabilities.

The following sections provide more information on these two options.

Start with an existing template

A broad selection of azd templates is available on the awesome-azd template gallery.
These templates provide infrastructure and application code for various development
scenarios, language frameworks, and Azure services. If you find a template that aligns
with your local application stack or desired architecture, you can extend and replace the
template code with your own

For example, the following azd templates provide starting points for common app
architectures and frameworks:

C#

ﾉ Expand table
 Template App host Tech stack

React Web App with C# API and Azure App Service Azure Cosmos DB for
MongoDB on Azure NoSQL, Bicep

React Web App with C# API and SQL Azure App Service Azure SQL Database,
Database on Azure Bicep

Static React Web App + Functions with Azure Static Web Apps, Azure SQL Database,
C# API and SQL Database on Azure Azure Functions Bicep

Create a new azd template for your app

You can also convert an existing app into an azd template to enhance the repository
with provisioning and deployment capabilities. This approach allows for the most
control and produces a reusable solution for future development work on the app. The
high level steps to create your own template are as follows:

Initialize the project template with azd init .

Create the Bicep or Terraform infrastructure as code files in the infra folder.
Update the azure.yaml file to tie the app services together with the Azure
resources.
Provision & deploy with azd up .

The following resources provide more information about creating your own templates:

Build your first Azure Developer CLI template

Make your project compatible with azd guide

Guidelines for using azd templates

Please note that each template that you use with Azure Developer CLI is licensed by its
respective owner (which may or may not be Microsoft) under the agreement which
accompanies the template. It is your responsibility to determine what license applies to
any template you choose to use.

Microsoft is not responsible for any non-Microsoft templates and does not screen these
templates for security, privacy, compatibility, or performance issues. The templates you
use with Azure Developer CLI, including those provided from Microsoft, are not
supported by any Microsoft support program or service. Any Microsoft-provided
templates are provided AS IS without warranty of any kind.
Next steps
Select and deploy a template

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Azure Developer CLI feature versioning
and release strategy
Article • 09/14/2023

Azure Developer CLI ( azd ) features are introduced and supported using a phased
approach. Features begin in the alpha stage and then advance to beta and stable after
meeting various criteria. This article describes the definitions, expectations and
advancement requirements for each phase. See a full list of each feature /command
supported by azd and its current stage on GitHub

Alpha Features
All features start as alpha features (e.g., experimental). In this phase, the goal is to
receive sufficient usage to get meaningful feedback around the feature's design,
functionality and user experience. Alpha features can be enabled and managed using
the azd config command.

） Important

Alpha features are only recommended for non-business-critical scenarios with

caution as there is a small chance of incompatible changes in subsequent releases
leading up to stable.

Definition
These features are under active development.
Features are hidden behind a feature flag, which interested users must explicitly
opt into.
There are no guarantees about the long-term stability or support of experimental
features.
No commitment that the feature is something the product team plans to advance
to preview or stable stage (it's an experiment).

How to opt into alpha features

1. To list available experimental features, run:

Azure Developer CLI

 azd config list-alpha

2. To enable a specific experimental feature, e.g. resourceGroupDeployments to

support infrastructure deployments at resource group scope, run:

Azure Developer CLI

azd config set alpha.resourceGroupDeployments on

3. To disable the resourceGroupDeployments feature, run:

Azure Developer CLI

azd config set alpha.resourceGroupDeployments off

For more information, visit the azure-dev GitHub repository.

Advancement criteria (how to reach beta)

The feature has been properly spec'd and approved by the product team.
The product team has formally signed off on advancing the feature to next phase.
The feature is documented and help text is available in the product.
Confirmation that the UX is successful via sufficient user feedback.

Beta Features
The goal of this phase is to improve the feature experience and advance beyond proof
of concept.

） Important

Beta features are only recommended for non-business-critical scenarios with

caution as there is a small chance of incompatible changes in subsequent releases
leading up to stable.

Definition
Unlike alpha features, a user doesn't need to take explicit action to use a beta
feature.
 Reduced number of breaking changes across releases for beta features as
functionality matures updates are made based on customer feedback.
Breaking changes are documented with explanations regarding how to digest
these breaks.
Beta commands are denoted as such (Beta) in azd product help.

Advancement criteria (how to reach stable)

The Product team has formally reviewed and signed off on feature advancement to
next phase.
The feature is functionally complete and stable.
Feature has been thoroughly manually tested and has sufficient unit and
integration tests to catch regressions and bugs.
Any remaining bugs are acceptable and nonblocking for users (e.g., UX
improvements).
The product team has received signals that the UX is successful via sufficient user
feedback.
The product team believes that the feature is truly adding value to the end-to-end
UX.

Stable Features

Definition
The product team stand behind these features.
Breaking changes in these areas are unexpected.
The product team ensures that any breaking changes are rolled out in a way that
minimizes impact.
Use in business-critical scenarios.

Request help
For information on how to file a bug, request help, or propose a new feature for the
Azure Developer CLI, please visit the troubleshooting and support page.

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Create Azure Developer CLI templates
overview
Article • 09/13/2024

The Azure Developer CLI ( azd ) utilizes templates to provision and deploy app resources
to the cloud. Developers can add support for azd commands and features by converting
their applications to templates. This article provides a contextual overview of the
different options for building azd templates. Once you understand the concepts in this
article, visit the following resources for more detailed implementation guides:

Use an existing template for your app.

Create a template from your app code
Training - build and deploy azd templates

７ Note

This article assumes a general understanding of azd templates. Visit the template
overview doc for more information about templates.

Template creation concepts

Creating an azd template requires adding specific configuration and infrastructure
assets to your existing code base, or starting a new app from an existing template those
same assets. Both workflows are explained in later sections. All azd templates share a
similar file structure based around azd conventions. The following diagram gives a quick
overview of the process to create an azd template:

Every azd template requires the following minimum resources:

An infra folder that holds the infrastructure as code (Bicep or Terraform) files.
An azure.yaml configuration file that maps your application services to the
provisioned infrastructure resources.
Other optional directories are often included as well, such as a .github folder with
assets to create a CI/CD pipeline. Visit the template overview doc for more information
about templates.

Consider the following sample app repository:

After converting this sample app to an azd template, the same app repository contains
the following:

The original app resources are unchanged, but new assets were added that azd
depends on for commands such as azd up :

An infra folder was added that includes Bicep files to create Azure resources.
 An azure.yaml configuration file was added to map the app code in the src
directory to the provision Azure resources.
A .azure folder was created to hold azd environment variables.
A .github folder (optional) was added to support CI/CD pipelines through GitHub
actions.

Template creation workflows

The azd init command is used to initialize an azd template for provisioning and
deploying the app resources on Azure. The command prompts you to choose between
two different workflows to initialize a template that are outlined in the following
sections - Use code in the current directory and Use an existing template.

Run the azd init command in the root of the directory you'd like to convert to an azd
template :

Azure Developer CLI

azd init

Use code in the current directory

This option instructs azd to analyze the code in your directory to identity which
technologies it uses, such as the programming language, framework and database
system. azd automatically generates template assets for you, such as the azure.yaml
service definition file and the infra folder with infrastructure-as-code files. The
generated assets are a starting point for additional modifications. Use this approach if
you plan to use common Azure services supported by azd scaffolding features.

Visit the Start with your app code to create a template tutorial for details on how to
implement this approach and more information on which Azure resources support
automatic detection and scaffolding.
Select a template
Select this option to use an existing template that defines many of your Azure resources
and architectural goals as a starting point. azd will prompt you to select a starter
template or another template from the awesome-azd gallery. When you select a
template, the assets of that template are added to your existing project directory to use
as a starting point. Some templates include sample app code that you can replace with
your own, while some (called "starter templates") are infrastructure only.

Use the azd init command to pull down an existing template to an empty directory
and use it as a starting point for your own app. If the template includes app source
code, you can either build off of that code or replace the source code directory with
your own.

Visit the Start with an existing template tutorial for details on how to implement this
approach.

See also
Use an existing template for your app.
Create a template from your app code

Request help
For information on how to file a bug, request help, or propose a new feature for the
Azure Developer CLI, please visit the troubleshooting and support page.

Next steps
Azure Developer CLI FAQ

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Get started with the Azure Developer CLI
compose feature
Article • 04/25/2025

The Azure Developer CLI ( azd ) composability (compose) feature enables you to progressively
compose the Azure resources required for your app without manually writing Bicep code.
Compose also uses Azure Verified Modules (AVM) when possible, providing recommended
practices using building blocks for Azure.

７ Note

The azd compose feature is currently in alpha and shouldn't be used in production apps.
Changes to alpha features in subsequent releases can result in breaking changes. Visit the
azd feature versioning and release strategy and feature stages pages for more
information. Use the Feedback button on the upper right to share feedback about the
compose feature and this article.

Enable the compose feature

The azd compose feature is currently in alpha, which means you need to enable it manually.
Visit the azd feature stages page for more information.

Bash

azd config set alpha.compose on

What is the compose feature?

The azd compose feature offers a new way to get started with azd . Before the compose
feature, developers had two primary options to configure the Azure resources to provision and
deploy an application:

Start with a prebuilt template, which defines resources and services to be provisioned and
deployed on Azure, and then customize. Browse templates in the AI template gallery or
the community gallery .
Start from an existing codebase by following the instructions in the simplified init flow.

Any further customization required the user to manually modify the Bicep files—until the
introduction of the compose feature.
Streamline resource creation with compose
The azd compose feature introduces a third option to add Azure resources to your apps.
Developers use the azd add command to instruct azd to compose new Azure resources and
update template configurations using minimal prompt workflows. This feature is useful for
developers who want to avoid writing Bicep or using an existing template.

Run the azd add command to start the compose workflow and add a new resource:

Bash

azd add

This command begins a prompt-based workflow that allows you to select a new resource to
create for your app:

Output

? What would you like to add? [Use arrows to move, type to filter]
> AI
Database
Host service
Key Vault
Messaging
Storage account
~Existing resource

When you're finished adding resources with azd add , run azd up or azd provision to create
the resources in Azure. azd manages resource creation internally until you Generate Bicep files
for the resources for further customization.

Visit the Build a minimal template using the compose feature article for a full walkthrough of
this feature.

Services supported by the compose feature

The azd compose feature supports adding resources for the following Azure services:

Azure AI Services models and Azure AI Foundry

Azure Container Apps
Azure Cosmos DB
Azure Cosmos DB for MongoDB
Azure Cosmos DB for PostgreSQL
Azure Cache for Redis
 Azure Database for MySQL
Azure Key Vault
Azure OpenAI with Microsoft Entra ID authentication
Azure Service Bus and Azure Event Hubs
Azure Blob Storage

Next steps
Compose quickstart
Build a minimal template using the Azure
Developer CLI compose feature
Article • 04/25/2025

The Azure Developer CLI ( azd ) composability (compose) feature enables you to progressively
compose the Azure resources required for your app without manually writing Bicep code. In
this article, you learn how to work with the compose feature to build a minimal template. Visit
the azd compose overview article for more conceptual information about this feature.

７ Note

The azd compose feature is currently in alpha and shouldn't be used in production apps.
Changes to alpha features in subsequent releases can result in breaking changes. Visit the
azd feature versioning and release strategy and feature stages pages for more
information. Use the Feedback button on the upper right to share feedback about the
compose feature and this article.

Work with the compose feature

Access azd compose features through the azd add command. The azd add command works
with templates created using the following azd init workflows:

Use code in the current directory (for apps that target Azure Container Apps for hosting)
Create a minimal project

Templates initialized through the Select a template flow aren't currently supported. The azd
compose feature manages infrastructure for you and isn't compatible with templates that have
existing infra folder assets. Visit the Generate the Bicep code article and template creation
workflows page for more information.

Complete the following steps to add new resources to your template without writing any code:

1. In a terminal window, navigate to the root of your azd template.

2. Run the azd add command to add a new resource and start the compose workflow:

Bash

azd add
3. Select one of the supported resources to add to your app. For this example, select
Database .

Output

? What would you like to add? [Use arrows to move, type to filter]
> AI
Database
Host service
Key Vault
Messaging
Storage account
~Existing resource

4. For the type of database, select PostgreSQL .

Output

? Which type of database? [Use arrows to move, type to filter]

MongoDB
> PostgreSQL
Redis

5. Enter a name for the new resource, such as azddb .

Output

? Input the name of the app database (PostgreSQL)

6. If your app contains services, azd prompts you to select the service that uses this
resource.

Output

? Select the service(s) that uses this resource

> [✓] webfrontend

7. azd generates a preview of the required changes to the azure.yaml file. Press Enter to
accept and apply the changes.

Output

Previewing changes to azure.yaml:

+ azddata:
+ type: db.postgres
 webfrontend:
type: host.containerapp
uses:
- azddb
+ - azddata
port: 80

8. Run the azd up command to provision any changes made through the azd add
command. In this example, azd provisions a PostgreSQL database in Azure.

9. Run the azd add command again to add other resources, such as an OpenAI service.

Explore the azure.yaml file

azure.yaml is the configuration file that azd uses to manage your app. azd manages the

services and resources composed through the azd add command using the corresponding
services and resources nodes. Consider the following example of an azure.yaml file updated

entirely through azd add :

yml

name: azdcomposesample
metadata:
template: azd-init@1.11.0
services:
webfrontend:
project: src
host: containerapp
language: dotnet
resources:
webfrontend:
type: host.containerapp
port: 80
uses:
- azdsql
- azdchat
azdsql:
type: db.postgres
azdchat:
type: ai.openai.model
model:
name: gpt-4o
version: "2024-08-06"

The services node declares:

 A deployment mapping named webfrontend between a .NET web app in the src
directory and Azure Container Apps.
The resources node declares:
An Azure container app and a matching dependency mapping named webfrontend
between the hosted .NET container app and the database and AI service it depends on.
The uses node maps the app to the other resources it depends on.
An Azure Database for PostgreSQL resource named azdsql .
An Azure OpenAI resource named azdchat .

Next steps
Generate Bicep code using the compose feature
Generate Bicep using the compose feature
Article • 04/25/2025

The Azure Developer CLI ( azd ) compose feature simplifies the process of building, deploying,
and managing cloud applications. By using azd compose , you can define and manage the
infrastructure and application code for your project in a unified way. This guide explains how to
generate Bicep code from the azd compose feature, enabling you to customize your cloud
infrastructure to meet your specific requirements.

７ Note

The azd infra synth feature is currently in alpha status and must be enabled before use:

Bash

azd config set alpha.infraSynth on

How azd compose manages infrastructure state

The azd compose feature tracks your infrastructure state in-memory during the composition
process. This approach allows you to iteratively define and refine your application and
infrastructure without immediately generating files or modifying your project directory.

When you run the azd infra synth command, the in-memory state is converted into Bicep
files in the infra folder. At this point, the infrastructure state transitions from being managed
in-memory to being represented as code, allowing for further customization.

 Tip

Use azd compose to quickly prototype your infrastructure before committing to file-based
changes with azd infra synth .

Generate the Bicep code

To explore or customize the Bicep code used internally by azd to provision resources created
by azd add , run the following command:

Bash
 azd infra synth

This command generates the corresponding Bicep files in the infra folder of your app.

７ Note

Running the azd infra synth command exits you from the azd compose feature and the
simplified initialization process. Any changes you make to the generated Bicep files are
not tracked by azd compose . For example, if you edit the Bicep code and then run azd
infra synth again, azd overwrites your changes with the regenerated code.

Next steps
Create Azure Developer CLI templates overview
Add Azure Developer CLI support to
your app using an existing template
Article • 09/13/2024

The Azure Developer CLI ( azd ) provides two different workflows to initialize a template
to use with your app, which include:

Use code in the current directory: This approach analyzes your app and
autogenerates supported infrastructure and configuration resources.
Select a template: This approach allows you to integrate an existing template with
your app, or use an existing template as a starting point for a new app.

Both of these approaches are explored in the Create Azure Developer CLI templates
overview doc.

In this article, you learn how to add support for the Azure Developer CLI ( azd ) to your
app through the Select a template approach. Visit the Add azd support to your app
using an existing template doc for more information on the alternative approach. You
can also visit the Training - build and deploy azd templates for more information on
building azd templates.

Select a template for your app

The Select a template workflow of the azd init command allows you to choose an
existing azd template to use as a starting point. The contents of the selected template
are added to the root directory of your project. Most templates provide the required set
of azd files and folders, and many include a complete set infrastructure-as-code files to
provision Azure resources for a chosen application stack.

In this example, you'll use the Starter - Bicep template, which includes the essential
structure of an azd template and some useful boilerplate code to get started. Starter
templates are a great choice when you want to scaffold out the correct template
structure and starting resources, but still author your own infrastructure files.

1. To follow along with the steps ahead using an existing sample application, clone
the following starter project to an empty directory on your computer:

Bash

git clone https://github.com/Azure-Samples/msdocs-python-flask-webapp-

 quickstart

2. In your command line tool of choice, navigate to the root directory of the cloned
project.

3. Run the azd init command to initialize an azd template.

Bash

azd init

4. When prompted, choose the option to Select a template.

5. From the list of templates, select Starter - Bicep. You can type the template name
or use your keyboard arrow keys to find it.

6. When prompted, enter a short environment name, such as testenv.

7. After you run azd init , the following assets are added to your current directory:

txt

├── .azdo [ Configures an Azure

Pipeline ]
├── .devcontainer [ For DevContainer ]
├── .github [ Configures a GitHub
workflow ]
├── .vscode [ VS Code workspace
configurations ]
├── .azure [ Stores Azure
configurations and environment variables ]
├── infra [ Contains
infrastructure as code files ]
│ ├── main.bicep/main.tf [ Main infrastructure
file ]
│ ├── main.parameters.json/main.tfvars.json [ Parameters file ]
│ └── core/modules [ Contains reusable
Bicep/Terraform modules ]
└── azure.yaml [ Describes the app
and type of Azure resources]
Update the Bicep files
Your project now contains the core structure and assets of an azd template. However, to
provision the Azure resources for your specific project, the Bicep files in the infra folder
need to be updated. To host the sample application, you'll need to define the following
resources using Bicep files:

An Azure App Service Plan

An Azure App Service running on Linux

1. Open the root project directory in your editor of choice, such as Visual Studio
Code.

2. Open the main.bicep file in the infra folder using your editor. This file contains
useful boilerplate code to setup essential variables, parameters, and naming
conventions. Beneath the comment block around line 50 that reads Add resources
to be provisioned below , add the following Bicep:

Bicep

// Creates an app service instance to host the app

module web './core/host/appservice.bicep' = {
name: 'web'
scope: rg
params: {
name: '${abbrs.webSitesAppService}web-${resourceToken}'
location: location
tags: union(tags, { 'azd-service-name': 'web' })
appServicePlanId: appServicePlan.outputs.id
runtimeName: 'python'
runtimeVersion: '3.8'
scmDoBuildDuringDeployment: true
}
}

// Create an App Service Plan to group applications under the same

payment plan and SKU
module appServicePlan './core/host/appserviceplan.bicep' = {
name: 'appserviceplan'
scope: rg
params: {
name: '${abbrs.webServerFarms}${resourceToken}'
location: location
tags: tags
sku: {
name: 'B1'
}
 }
}

７ Note

A unique string is generated based on subscription ID and used as a

${resourceToken} variable. This token is appended to the name of all

Azure resources created by azd .

azd uses tags to identify resources so you can modify the names based

on your organization's naming convention.

The 'azd-service-name': 'web' tag on the app service is the value azd
uses to identify deployment host. The value must be the same as what is
defined for the service in the azure.yaml file.

Update the azure.yaml file

To deploy the app, azd needs to know more about your app. The azure.yaml file is used
to define the source code location, language, and the Azure hosting service for each
service in your app. For full details, refer to the azure.yaml schema.

1. Open the azure.yaml at the root of the project.

2. Add the following lines to the bottom of the file:

yml

name: msdocs-python-flask-webapp-quickstart
services:
web:
project: .
language: py
host: appservice

Provision and deploy the template

1. Save all of your changes and run the following command to provision and deploy
the app resources on Azure:

Azure Developer CLI

 azd up

2. When the command finishes, click the link in the command output to navigate to
the deployed site.

Your project is now compatible with Azure Developer CLI and can be used as a template.

７ Note

azd also supports using Buildpack for containerizing your apps by default. If
your azd template targets Azure Container Apps or Azure Kubernetes Service but
does not include a Docker file, azd automatically generates an image using
Buildpack.

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Add Azure Developer CLI support to
your app using code in your app
directory
Article • 09/13/2024

The Azure Developer CLI ( azd ) provides two different workflows to initialize a template
to use with your app, which include:

Use code in the current directory: This approach analyzes your app and
autogenerates supported infrastructure and configuration resources.
Select a template: This approach allows you to integrate an existing template with
your app, or use an existing template as a starting point for a new app.

Both of these approaches are explored in the Create Azure Developer CLI templates
overview doc.

In this article, you learn how to add support for the Azure Developer CLI ( azd ) to your
app through the Use code in the current directory approach. Visit the Add azd support
to your app using an existing template doc for more information on the alternative
approach. You can also visit the Training - build and deploy azd templates for more
information on building azd templates.

Use code in the current directory

1. You can follow the steps ahead using your own project. However, if you'd prefer to
follow along using a sample application, clone the following starter repo to an
empty directory on your computer:

Bash

git clone https://github.com/Azure-Samples/msdocs-python-flask-webapp-

quickstart

2. Open a terminal to the root directory of the project.

3. Run the azd init command to initialize the template.

Bash

azd init
 4. When prompted, select the option to Use code in the current directory. azd
analyzes the project and provides a summary of the detected services and
recommended Azure hosting resources.

5. Select Confirm and continue initializing my app. azd generates the following
assets in the project root directory:

An azure.yaml file with appropriate service definitions.

An infra folder with infrastructure-as-code files to provision and deploy the
project to Azure.
A .azure folder with environment variables set in a .env file.

More details on this detection and generation process are provided later in the
article.

6. The generated files work as-is for the provided sample app and may for your own
apps as well. If necessary, the generated files can be modified to fit your needs. For
example, you may need to further modify the infrastructure-as-code files in the
infra folder if your app relies on Azure resources beyond those that were

identified by azd .

7. Run the azd up command to provision and deploy your app to Azure.

Bash

azd up

8. When prompted, select the desired subscription and location to begin the
provisioning and deployment process.

9. When the process completes, click the link in the azd output to open the app in
the browser.

Explore the initialization steps

When you select the Use code in the current directory workflow, the azd init
command analyzes your project and autogenerates code based on what it discovers.
The sections below explain the details of how this process works and which technologies
are currently supported.

Detection
The azd init command detects project files for supported languages located in your
project directory and subdirectories. azd also scans package dependencies to gather
information about the web frameworks or databases your app uses. If needed, you can
manually add or edit the detected components as presented in the confirmation
summary prompt.

The current detection logic is as follows:

Supported languages:
Python
JavaScript/TypeScript
.NET
Java
Supported databases:
MongoDB
PostgreSQL
For Python and JavaScript/TypeScript, web frameworks and databases are
automatically detected.
When a JavaScript/TypeScript project uses a front-end (or client-side) web
framework, it is classified as a front-end service. If your service uses a front-end
web framework that is currently undetected, you may select JQuery to provide
equivalent front-end service classification and behavior.

Generation
After you confirm the detected components, azd init generates the infrastructure-as-
code files needed to deploy your application to Azure.

The generation logic is as follows:

Supported hosts:
Azure Container Apps.
For databases, the supported mapping between database technology and service
used:
MongoDB: Azure CosmosDB API for MongoDB
PostgreSQL: Azure Database for PostgreSQL flexible server
Redis: Azure Container Apps Redis add-on
Services using databases will have environment variables that provide connection
to the database pre-configured by default.
When both front-end and back-end services are detected, CORS configuration on
the Azure host for back-end services will be updated to allow the default hosting
 domain of front-end services. This can be modified or removed as necessary in the
Infrastructure as Code configuration files.

Add support for dev containers

You can also make your template compatible with development containers and
Codespaces. A dev container allows you to use a container as a full-featured
development environment. It can be used to run an application, to separate tools,
libraries, or runtimes needed for working with a codebase, and to aid in continuous
integration and testing. Dev containers can be run locally or remotely, in a private or
public cloud. (Source: https://containers.dev/ )

To add support for dev containers:

1. Create a .devcontainer folder at the root of your project.

2. Create a devcontainer.json file inside of the .devcontainer folder with the desired
configurations. The azd starter template provides a sample devcontainer.json
file that you can copy into your project and modify as needed.

Read more about working with dev containers on the Visual Studio Code
documentation.

Add support for a CI/CD pipeline

You can also add support for CI/CD in your template using GitHub actions or Azure
DevOps using the following steps:

1. Add a .github folder for GitHub actions or a .ado folder for Azure DevOps to the
root of your project.

2. Add a workflow file into the new folder. The azd starter template provides a
Sample GitHub Actions workflow file and Sample Azure DevOps Pipelines files
for each platform that you can copy into your project and modify as needed.

3. You may also need to update the main.parameters.json file in your infra folder
with the required environment variables for your workflow to run.

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Configure a pipeline and push updates
Article • 09/13/2024

In this article, you'll learn how to use the Azure Developer CLI ( azd ) to push template
changes through a CI/CD pipeline such as GitHub Actions or Azure DevOps. For this
example you'll use the React Web App with Node.js API and MongoDB on Azure
template, but you can apply the principles you learn in this article to any of the Azure
Developer CLI templates.

７ Note

The azd pipeline config command is still in beta. Read more about alpha and beta
feature support on the feature versioning and release strategy page.

Prerequisites
Install the Azure Developer CLI.
Deploy the Node.js template.
Visual Studio Code installed.

azd templates may or may not include a default GitHub Actions and/or Azure DevOps
pipeline configuration file called azure-dev.yml , which is required to setup CI/CD. This
configuration file provisions your Azure resources and deploy your code to the main
branch. You can find azure-dev.yml :

For GitHub Actions: in the .github/workflows directory.

For Azure DevOps: in the .azdo/pipelines directory.

You can use the configuration file as-is or modify it to suit your needs.

７ Note

Make sure your template has a pipeline definition ( azure-dev.yaml ) before calling
azd pipeline config . azd does not automatically create this file. See Create a

pipeline definition for azd below.

Use the azd pipeline config command to configure a CI/CD pipeline, which handles
the following tasks:
 Creates and configures a service principal for the app on the Azure subscription.
Your user must have either Owner role or Contributor + User Access
Administrator roles within the Azure subscription to allow azd to create and assign

roles to the service principal.

Steps you through a workflow to create and configure a GitHub or Azure DevOps
repository and commit your project code to it. You can also choose to use an
existing repository.
Creates a secure connection between Azure and your repository.
Runs the GitHub action when you check in the workflow file.

For more granular control over this process, or if you user does not have the required
roles, you can manually configure a pipeline .

Select your preferred pipeline provider to continue:

GitHub Actions

Authorize GitHub to deploy to Azure

To configure the workflow, you need to authorize a service principal to deploy to
Azure on your behalf, from a GitHub action. azd creates the service principal and a
federated credential for it.

1. Run the following command to create the Azure service principal and
configure the pipeline:

Azure Developer CLI

azd pipeline config

This command, optionally creates a GitHub repository and pushes code to the
new repo.

７ Note

By default, azd pipeline config uses OpenID Connect (OIDC), called

federated credentials. If you'd rather not use OIDC, run azd pipeline
config --auth-type client-credentials .

OIDC/federated credentials are not supported for Terraform.

 Learn more about OIDC support in azd.

2. Supply the requested GitHub information.

3. When prompted about committing and pushing your local changes to start a
new GitHub Actions run, specify y .

4. In the terminal window, view the results of the azd pipeline config
command. The azd pipeline config command will output the GitHub
repository name for your project.

5. Using your browser, open the GitHub repository for your project.

6. Select Actions to see the workflow running.

Make and push a code change

1. In the project's /src/web/src/layout directory, open header.tsx .

2. Locate the line <Text variant="xLarge">ToDo</Text> .

3. Change the literal ToDo to myTodo .

4. Save the file.

5. Commit your change. Committing the change starts the GitHub Action
pipeline to deploy the update.
6. Using your browser, open your project's GitHub repository to see both:

Your commit
The commit from GitHub Actions being set up.

7. Select Actions to see the test update reflected in the workflow.

8. Visit the web frontend URL to inspect the update.

 azd as a GitHub action

Add azd as a GitHub action . This action will install azd . To use it, you can add the
following to .github\workflows\azure-dev.yml :

yml

on: [push]

jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Install azd
uses: Azure/setup-azd@v0.1.0

Clean up resources
When you no longer need the Azure resources created in this article, run the following
command:

Azure Developer CLI

azd down

Advanced features
You can extend the azd pipeline config command for specific template scenarios or
requirements, as described in the following sections.

Additional secrets or variables

By default, azd sets variables and secrets for the pipeline. For example, the azd pipeline
config command creates the subscription id , environment name and the region as

pipeline variables whenever it executes. The pipeline definition then references those
variables:

YAML

env:
AZURE_CLIENT_ID: ${{ vars.AZURE_CLIENT_ID }}
AZURE_TENANT_ID: ${{ vars.AZURE_TENANT_ID }}
 AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}

When the pipeline runs, azd gets the values from the environment, which is mapped to
the variables and secrets. Depending on the template, there might be settings which
you can control using environment variables. For example, an environment variable
named KEY_VAULT_NAME could be set to define the name of a Key Vault resource within
the template infrastructure. For such cases, the list of variables and secrets can be
defined by the template, using the azure.yaml . For example, consider the following
azure.yaml configuration:

YAML

pipeline:
variables:
- KEY_VAULT_NAME
- STORAGE_NAME
secrets:
- CONNECTION_STRING

With this configuration, azd checks if any of the variables or secrets have a non-empty
value in the environment. azd then creates either a variable or a secret for the pipeline
using the name of the key in the configuration as the name of the variable or secret, and
the non-string value from the environment for the value.

The azure-dev.yaml pipeline definition can then reference the variables or secrets:

YAML

- name: Provision Infrastructure

run: azd provision --no-prompt
env:
KEY_VAULT_NAME: ${{ variables.KEY_VAULT_NAME }}
STORAGE_NAME: ${{ variables.STORAGE_NAME }}
CONNECTION_STRING: ${{ secrets.CONNECTION_STRING }}

７ Note

You must run azd pipeline config after updating the list of secrets or variables in
azure.yaml for azd to reset the pipeline values.

Infrastructure parameters
Consider the following bicep example:

Bicep

@secure()
param BlobStorageConnection string

The parameter BlobStorageConnection has no default value set, so azd prompts the user
to enter a value. However, there is no interactive prompt during CI/CD. azd must
request the value for the parameter when you run azd pipeline config , save the value
in the pipeline, and then fetch the value again when the pipeline runs.

azd uses a pipeline secret called AZD_INITIAL_ENVIRONMENT_CONFIG to automatically save

and set the value of all the required parameters in the pipeline. You only need to
reference this secret in your pipeline:

YAML

- name: Provision Infrastructure

run: azd provision --no-prompt
env:
AZD_INITIAL_ENVIRONMENT_CONFIG: ${{
secrets.AZD_INITIAL_ENVIRONMENT_CONFIG }}

When the pipeline runs, azd takes the values for the parameters from the secret,
removing the need for an interactive prompt.

７ Note

You must re-run azd pipeline config if you add a new parameter.

Create a pipeline definition

If your azd template doesn't already have a CI/CD pipeline definition file, you can create
one yourself. A CI/CD pipeline definition has typically 4 main sections:

trigger
permissions
operating system or pool
steps to be run
The following examples demonstrate how to create a definition file and related
configurations for GitHub Actions and Azure Pipelines.

GitHub Actions

Running azd in GitHub Actions requires the following configurations:

Grant id-token: write and contents: read access scopes.

Install the azd action , unless you are using a docker image where azd is
already installed.

You can use the following template as a starting point for your own pipeline
definition:

YAML

on:
workflow_dispatch:
push:
# Run when commits are pushed to mainline branch (main or master)
# Set this to the mainline branch you are using
branches:
- main
- master

# Set this permission if you are using a Federated Credential.

permissions:
id-token: write
contents: read

jobs:
build:
runs-on: ubuntu-latest
# azd build-in variables.
# This variables are always set by `azd pipeline config`
# You can set them as global env (apply to all steps) or you can add
them to individual steps' environment
env:
AZURE_CLIENT_ID: ${{ vars.AZURE_CLIENT_ID }}
AZURE_TENANT_ID: ${{ vars.AZURE_TENANT_ID }}
AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}
## Define the additional variables or secrets that are required
globally (provision and deploy)
# ADDITIONAL_VARIABLE_PLACEHOLDER: ${{
variables.ADDITIONAL_VARIABLE_PLACEHOLDER }}
# ADDITIONAL_SECRET_PLACEHOLDER: ${{
secrets.ADDITIONAL_SECRET_PLACEHOLDER }}
steps:
- name: Checkout
 uses: actions/checkout@v4

# using the install-azd action

- name: Install azd
uses: Azure/setup-azd@v1.0.0

# # If you want to use azd-daily build, or install it from a PR,

you can remove previous step and
# # use the next one:
# - name: Install azd - daily or from PR
# # Update this scrip based on the OS - pool of your pipeline.
This example is for a linux pipeline installing daily build
# run: curl -fsSL https://aka.ms/install-azd.sh | bash -s -- --
version daily
# shell: pwsh

# azd set up Federated Credential by default. You can remove this

step if you are using Client Credentials
- name: Log in with Azure (Federated Credentials)
if: ${{ env.AZURE_CLIENT_ID != '' }}
run: |
azd auth login `
--client-id "$Env:AZURE_CLIENT_ID" `
--federated-credential-provider "github" `
--tenant-id "$Env:AZURE_TENANT_ID"
shell: pwsh

## If you set up your pipeline with Client Credentials, remove

previous step and uncomment this one
# - name: Log in with Azure (Client Credentials)
# if: ${{ env.AZURE_CREDENTIALS != '' }}
# run: |
# $info = $Env:AZURE_CREDENTIALS | ConvertFrom-Json -
AsHashtable;
# Write-Host "::add-mask::$($info.clientSecret)"

# azd auth login `

# --client-id "$($info.clientId)" `
# --client-secret "$($info.clientSecret)" `
# --tenant-id "$($info.tenantId)"
# shell: pwsh
# env:
# AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS }}

- name: Provision Infrastructure

run: azd provision --no-prompt
env:
# # uncomment this if you are using infrastructure parameters
# AZD_INITIAL_ENVIRONMENT_CONFIG: ${{
secrets.AZD_INITIAL_ENVIRONMENT_CONFIG }}
## Define the additional variables or secrets that are required
only for provision
# ADDITIONAL_VARIABLE_PLACEHOLDER: ${{
variables.ADDITIONAL_VARIABLE_PLACEHOLDER }}
# ADDITIONAL_SECRET_PLACEHOLDER: ${{
 secrets.ADDITIONAL_SECRET_PLACEHOLDER }}

- name: Deploy Application

run: azd deploy --no-prompt
env:
## Define the additional variables or secrets that are required
only for deploy
# ADDITIONAL_VARIABLE_PLACEHOLDER: ${{
variables.ADDITIONAL_VARIABLE_PLACEHOLDER }}
# ADDITIONAL_SECRET_PLACEHOLDER: ${{
secrets.ADDITIONAL_SECRET_PLACEHOLDER }}

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Monitor your app using Azure
Developer CLI
Article • 09/17/2024

In this article, you learn how to use Azure Developer CLI ( azd ) to monitor your app
health.

While we use the React Web App with Node.js API and MongoDB on Azure template
for this guide, you can use any of the Azure Developer CLI templates.

７ Note

The azd monitor command is still in beta. Read more about alpha and beta feature
support on the feature versioning and release strategy page.

Prerequisites
Install the Azure Developer CLI
Run azd init and azd up for the Node.js template

Configure your environment

Create monitoring activity in the app before running the azd monitor commands:

1. Open the ToDo app in your preferred code editor.

2. Create a new list and add a couple of items.

Monitor the app

To help with monitoring apps, azd provides a monitor command to launch various
Application Insights dashboards. Run the command with one of the following
parameters in the project directory to monitor app health:

ﾉ Expand table

Application Insights dashboard Command

Main dashboard azd monitor --overview

 Application Insights dashboard Command

Live metrics dashboard azd monitor --live

Logs dashboard azd monitor --logs

Clean up resources
When you no longer need the resources created in this article, run the azd down
command to delete the resource group:

Azure Developer CLI

azd down

See also
Azure Monitor documentation

Request help
For information on how to file a bug, request help, or propose a new feature for the
Azure Developer CLI, please visit the troubleshooting and support page.

Next steps
Make your project Azure Developer CLI (azd) compatible

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Resource Group Scoped Deployments
Article • 09/12/2024

Azure Developer CLI ( azd ) supports deployments at both the subscription and resource
group scopes. By default, azd creates a resource group that contains the provisioned
resources in the subscription you choose during the azd up workflow. However, azd
also allows you to deploy to an existing resource group. When you choose an existing
resource group, the scope of permissions needed to run azd provision is reduced from
subscription level to the resource group level.

In this article, you learn how to modify templates to enable resource group scoped
deployments.

７ Note

Resource Group Scoped Deployment is currently a beta feature. Learn more about
our versioning strategy.

Modify the target scope of a template

1. In main.bicep file of your azd template, change targetScope :

Bicep

targetScope = 'resourceGroup'

2. Remove scope: rg from all the module references in main.bicep .

3. Use resource group instead of subscription when you create a unique resource
token in main.bicep , .

Bicep

var resourceToken = toLower(uniqueString(resourceGroup().id,

environmentName, location))

4. Remove the following section of code in main.bicep that organizes resources into
a resource group.

Bicep
 // Organize resources in a resource group
resource rg 'Microsoft.Resources/resourceGroups@2021-04-01' = {
name: !empty(resourceGroupName) ? resourceGroupName :
'${abbrs.resourcesResourceGroups}${environmentName}'
location: location
tags: tags
}

5. If applicable, in the .azdo\pipelines\azure-dev.yml and .github\workflows\azure-

dev.yml files, add the Azure resource group environment variable to your tasks.

yml

AZURE_RESOURCE_GROUP: $(AZURE_RESOURCE_GROUP)

７ Note

For an example of these changes applied to the React Web App with Node.js API
and MongoDB on Azure template , see this GitHub comparison .

To set the resource group to deploy to manually, you can set AZURE_RESOURCE_GROUP in
your environment. Learn more about that here.

Alternatively, if you do not have a resource group specified in your environment, azd
prompts you to pick an existing resource group from your subscription or create a new
one when you run azd provision .

Next steps
Azure Developer CLI FAQ

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Use third-party container registries
Article • 09/13/2024

Azure Developer CLI ( azd ) supports external third-party container registries for
deployment. To use this feature, you need to manually authenticate to the external
container registry before calling azd deploy.

Authentication
Run docker login and authenticate to your external container registry. You may need to
follow additional setup or configuration steps for your specific registry provider.

Azure Developer CLI

docker login <your-registry>

Example scenarios
You can configure azd to push and pull images from an external container registry in
the azure.yaml file of your template. Support for additional container registries provides
greater flexibility for your deployment workflows.

Pull from external container registry

In this example, during azd deploy the container is pulled from
docker.io/username/nginx:latest and directly referenced by the container app service.

yml

name: todo-nodejs-mongo-aca
metadata:
template: todo-nodejs-mongo-aca@0.0.1-beta
services:
nginx:
image: docker.io/<username>/nginx:latest
host: containerapp

７ Note
 Your containerapp infra configuration must configure credentials when pulling
containers from private container registries.

Pull, tag & push to external registry

Consider an azure.yaml file with the following configuration:

yml

# azure.yaml

name: todo-nodejs-mongo-aca
metadata:
template: todo-nodejs-mongo-aca@0.0.1-beta
services:
nginx:
image: nginx
host: containerapp
docker:
registry: docker.io/<username>
image: nginx
tag: latest

During a call to azd deploy the nginx image will be pulled from the configured image. In
this case it is a public image on docker hub. The container/image will be retagged and
pushed to the docker registry.

Build, tag & push to external registry on azd deploy

Consider an azure.yaml file with the following configuration:

yml

# azure.yaml

name: todo-nodejs-mongo-aca
metadata:
template: todo-nodejs-mongo-aca@0.0.1-beta
services:
api:
project: ./src/api
host: containerapp
docker:
registry: docker.io/<username>
image: todo-api
During azd deploy the container source will be built, tagged and push to the docker
registry.

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Azure deployment stacks integration
with the Azure Developer CLI
Article • 10/29/2024

The Azure Developer CLI ( azd ) supports Azure deployment stacks for template
deployments. An Azure deployment stack is a resource that enables you to manage a
group of Azure resources as a single, cohesive unit. By using deployment stacks, you can
gain additional control over the set of resources associated with your azd template and
app.

In this article, you learn how to:

Enable Azure deployment stack support in azd .

Deploy azd templates using Azure deployment stacks.
Configure deployment stack behavior using azd configurations.

Enable Azure deployment stack support

Azure deployment stacks support must be enabled via the azd config command:

Bash

azd config set alpha.deployment.stacks on

７ Note

Azure deployment stacks support is currently an alpha feature, which is why it must
be enabled manually. However, deployment stacks will become the default
deployment behavior of azd in a future release. Learn more about our versioning
strategy.

Verify the feature was enabled successfully using the azd config show command:

Bash

azd config show

Deploy a template using deployment stacks

After you enable the deployment stacks feature, no further changes to your azd
templates are required to leverage the default behavior of this feature. azd
automatically wraps the provisioned template resources in an Azure deployment stack
when you run azd up :

Bash

azd up

azd uses the scope defined in the main.bicep file of your template for the Azure

deployment stack. For example, if your template is scoped to the subscription or

resource group level, you can view the associated deployment stack in the Azure portal
on the Deployment stacks page of the associated subscription or resource group page.

Select the deployment stack to view the management pages for it:
Delete a deployment stack
By default, you can delete a deployment stack and its associated resources using the
standard azd down command:

Bash

azd down

The exact behavior of azd down and deployment stacks is configured using the
azure.yaml file.

Configure the deployment stack

azd exposes various configuration settings through the infra section of the azure.yaml

file to influence the behavior of the Azure deployment stack. These settings map to the
standard options detailed in Deployment stacks documentation. Consider the following
azure.yaml example:

yml

name: todo-nodejs-mongo-aca
metadata:
template: todo-nodejs-mongo-aca@0.0.1-beta
infra:
provider: bicep
deploymentStacks:
actionOnUnmanage:
 resources: delete
resourceGroups: delete
denySettings:
mode: denyDelete
excludedActions:
- Microsoft.Resources/subscriptions/resourceGroups/delete
excludedResources:
- <your-resource-id-1>
- <your-resource-id-2>
excludedPrincipals:
- <your-targeted-principal-id-1>
- <your-targeted-principal-id-2>
applyToChildScopes: true
# ...
# Remaining file contents omitted
# ...

In the preceding example, the following options are defined in the deploymentStacks
section:

actionOnUnmanage: When a deployment stack is deleted, the associated Azure

resources are considered unmanaged. This setting determines how Azure will
handle unmanaged resources. Possible values include:
delete is the default value and destroys any resources managed by the deleted

deployment stack.
detach leaves resources in place but removes their association to the deleted

deployment stack.
denySettings: A subsection that provides nuanced control over the resources of
the deployment stack.
mode: Determines high level restrictions on the deployment stack resources.
Possible values include:
none is the default value and allows the deployment stack resources to be

deleted, or new resources to be added.

denyDelete prevents any deployment stack resources from being deleted.

denyWriteAndDelete prevents any deployment stack resources from being

deleted and also prevents new resources from being added to the
deployment stack.
excludedActions: Lists the Azure role-based access control (RBAC) actions that
are not allowed on the deployment stack resources.
excludedResources: Lists the resource IDs that are excluded from the
denySettings .

excludedPrincipals: Lists the service principal IDs that are excluded from the
denySettings .
 applyToChildScopes: A boolean value that sets whether the deny settings apply
to child resources of resources in the deployment stack. For example, a SQL
Server resource has child database resources.

Azure Developer CLI FAQ

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Deploy to an Azure AI Foundry/ML
studio online endpoint using the Azure
Developer CLI
Article • 01/08/2025

The Azure Developer CLI enables you to quickly and easily deploy to an Azure ML
Studio or Azure AI Foundry online endpoint. azd supports the following Azure AI
Foundry/ML studio features, which you'll learn to configure in the sections ahead:

Custom environments
Environments can be viewed with Azure ML Studio under the Environments
section.
Custom models
Models can be viewed with Azure ML Studio under the models section.
Prompt flows
Flows can be viewed with Azure ML Studio under the flows section.
Flows can be viewed with Azure AI Foundry portal under the flows section.
Online deployments (within Online-Endpoint)
Deployments can be viewed with Azure ML Studio under the deployments
section.
Deployments can be viewed with Azure AI Foundry portal under the
deployments section.

Prerequisites
To work with Azure AI Foundry/ML studio online endpoints, you'll need the following:

Azure Subscription with OpenAI access enabled

AI Hub Resource
AI Project
OpenAI Service
Online Endpoint
AI Search Service (Optional, enabled by default)

The Azure AI Foundry Starter template can help create all the required infrastructure
to get started with Azure AI Foundry endpoints.
Configure the Azure AI Foundry/ML studio
online endpoint
Configure support for AI/ML online endpoints in the services section of the azure.yaml
file:

Set the host value to ai.endpoint .

The config section for ai.endpoint supports the following configurations:
workspace: The name of the Azure AI Foundry workspace. Supports azd
environment variable substitutions and syntax.
If not specified, azd will look for environment variable with name
AZUREAI_PROJECT_NAME .

environment: Optional custom configuration for ML environments. azd creates

a new environment version from the referenced YAML file definition.
flow: Optional custom configuration for flows. azd creates a new prompt flow
from the specified file path.
model: Optional custom configuration for ML models. azd creates a new model
version from the referenced YAML file definition.
deployment: Required configuration for online endpoint deployments. azd
creates a new online deployment to the associated online endpoint from the
referenced YAML file definition.

Consider the following sample azure.yaml file that configures these features:

YAML

name: contoso-chat
metadata:
template: contoso-chat@0.0.1-beta
services:
chat:
# Referenced new ai.endpoint host type
host: ai.endpoint
# New config flow for AI project configuration
config:
# The name of the Azure AI Foundry workspace
workspace: ${AZUREAI_PROJECT_NAME}
# Optional: Path to custom ML environment manifest
environment:
path: deployment/docker/environment.yml
# Optional: Path to your prompt flow folder that contains the flow
manifest
flow:
path: ./contoso-chat
# Optional: Path to custom model manifest
 model:
path: deployment/chat-model.yaml
overrides:
"properties.azureml.promptflow.source_flow_id":
${AZUREAI_FLOW_NAME}
# Required: Path to deployment manifest
deployment:
path: deployment/chat-deployment.yaml
environment:
PRT_CONFIG_OVERRIDE:
deployment.subscription_id=${AZURE_SUBSCRIPTION_ID},deployment.resource_grou
p=${AZURE_RESOURCE_GROUP},deployment.workspace_name=${AZUREAI_PROJECT_NAME},
deployment.endpoint_name=${AZUREAI_ENDPOINT_NAME},deployment.deployment_name
=${AZUREAI_DEPLOYMENT_NAME}

The config.deployment section is required and creates a new online deployment to the
associated online endpoint from the referenced yaml file definition. This functionality
handles various concerns for you, including the following:

Associates environment and model will be referenced when available.

azd waits for deployment to enter a terminal provisioning state.

On successful deployments, all traffic is shifted to the new deployment version.

All previous deployments, are deleted to free up compute for future deployments.

Explore configuration options

Each supported feature for AI/ML online endpoints supports customizations for your
specific scenario using the options described in the following sections.

Flow
The flow configuration section is optional and supports the following values:

name: The name of the flow. Defaults to <service-name>-flow-<timestamp> if not

specified.

path: The relative path to a folder that contains the flow manifest.

overrides: Any custom overrides to apply to the flow.

７ Note

Each call to azd deploy creates a new timestamped flow.

Environment
The environment configuration section is optional and supports the following values:

name: The name of the custom environment. Defaults to <service-name>-

environment if not specified.

path: The relative path to a custom environment yaml manifest.

overrides: Any custom overrides to apply to the environment.

７ Note

Each call to azd deploy creates a new environment version.

Model
The model configuration section is optional and supports following values:

name: The name of the custom model. Defaults to <service-name>-model if not

specified.

path: The relative path to a custom model yaml manifest.

overrides: Any custom overrides to apply to the model.

７ Note

Each call to azd deploy creates a new environment version.

Deployment
The deployment configuration section is required and supports the following values:

name: The name of the custom deployment. Defaults to <service-name>-

deployment if not specified.

path: The relative path to a custom deployment yaml manifest.

environment: A map of key value pairs to set environment variables for the
deployment. Supports environment variable substitutions from OS/AZD
environment variables using ${VAR_NAME} syntax.
 overrides: Any custom overrides to apply to the deployment.

７ Note

Only supports managed online deployments.

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Configure service packaging file
exclusions
Article • 09/25/2024

The Azure Developer CLI ( azd ) allows you to add ignore files in your templates that
specify files and directories to exclude from the deployment package for App Service
and Function Apps. This features provides granular control at the service level over
which files are included in the packaging process.

Understand service packaging ignore files

There are two different types of ignore files you can use to influence the packaging
process:

.webappignore influences packaging exclusions for Azure App Service

deployments.
.funcignore influences packaging exclusions for Azure Functions deployments.

These ignore files are applied based on the targeted deployment service, ensuring users
can independently customize file exclusions when packaging for Azure App Service and
Azure Functions. Both types of packaging ignore files follow these rules:

.webappignore or .funcignore files should be placed in the root folder of the

relevant service in your azd template.

If a .webappignore or .funcignore file exists in a service directory, the packaging
process follows its rules, allowing granular control over which files are included or
excluded in the service's zip archive.
If no .webappignore or .funcignore file is present, default exclusions apply:
Python: __pycache__ and any venv files
Node.js: node_modules
The syntax for the ignore files followed the standard gitignore syntax . For
example, use the ! symbol to revert an exclusion.

Exclusion examples
In your azd template, add a .webappignore or .funcignore file to the root folder of the
service you intend to deploy to Azure App Service or Azure Functions. Update the
content of those ignore files to include or exclude files using the following patterns:
 Node.js

Exclude a folder or a specific file:

text

logs/*
testfile.js

Exclude folders or files that are ignored by default when the .webappignore or
.funcignore file is not present:

text

node_modules/

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Helm and Kustomize support
Article • 09/13/2024

The Azure Developer CLI provides support for Helm and Kustomize to improve the
provisioning and deployment process to Azure Kubernetes Service (AKS). Helm and
Kustomize are tools that help you configure and manage Kubernetes applications. In the
sections ahead, you'll learn how to enable and customize support for these tools in your
azd templates.

Enable Helm support

To enable Helm support, make sure you have the Helm CLI installed. Enable the azd
helm feature flag by running the azd config command:

Azure CLI

azd config set alpha.aks.helm on

Helm configuration and deployment

azd Helm support enables you to define a list of Helm charts to install for each azd
service. Use the helm and k8s configuration sections in the azure.yaml file to define a
list of helm repositories or releases to install.

yml

name: todo-nodejs-mongo-aks
metadata:
template: todo-nodejs-mongo-aks@0.0.1-beta
services:
argocd:
host: aks
k8s:
namespace: argo
service:
name: argocd-server
helm:
repositories:
- name: argo
url: https://argoproj.github.io/argo-helm
releases:
- name: argocd
chart: argo/argo-cd
verson: 5.51.4
 jupyterhub:
host: aks
k8s:
namespace: jupyterhub
service:
name: proxy-public
helm:
repositories:
- name: jupyterhub
url: https://hub.jupyter.org/helm-chart/
releases:
- name: jupyterhub
chart: jupyterhub/jupyterhub
version: 3.1.0

The azd deploy command handles the following tasks using the helm section:

Adds any referenced Helm repositories and/or updates them

Installs the referenced Helm charts
Waits for Helm release to transition to a deployed state
Lists relevant services and ingresses defined within the deployed resources

Enable Kustomize support

To enable Kustomize support, make sure you have the Kustomize CLI installed. Enable
the azd Kustomize feature flag using the azd config command:

Azure CLI

azd config set alpha.aks.kustomize on

Kustomize configuration and deployment

The Kustomize feature enables you to use Kustomize as part of Kubernetes deployments
and provides the following features:

Supports base and variant configurations

 edits that can be run before deployments
configMapGenerator with azd environments

Configure Kustomize features using the following azure.yaml sections:

dir : Relative path from the service to your Kustomize directory that contains a

kustomization.yaml file.

Supports environment variable substitution.

edits : Array of edit expression that are applied before deployment

Supports environment variable substitution

env : Map of key/value pairs generated before deployment

Map values support environment variable substitution

Use cases
The following Kustomize use cases are supported by azd .

Deploy k8s manifests

The following configuration performs a kubectl apply -k <dir> command that points
to your manifests folder that contains a kustomization.yaml :

yml

# azure.yaml

name: todo-nodejs-mongo-aks
metadata:
template: todo-nodejs-mongo-aks@0.0.1-beta
services:
api:
project: ./src/api
language: js
host: aks
k8s:
kustomize:
dir: ./kustomize/base

Use overlays to deploy to with different variants

This use case is typically used to have custom configurations for deploying to different
stages or environments, such as dev , test and prod . In the following example, the user
can specify the ${AZURE_ENV_NAME} environment variable within the kustomize directory
to automatically leverage the azd environments as your default overlay convention:

yml

# azure.yaml

name: todo-nodejs-mongo-aks
metadata:
template: todo-nodejs-mongo-aks@0.0.1-beta
services:
api:
project: ./src/api
language: js
host: aks
k8s:
kustomize:
dir: ./kustomize/overlays/${AZURE_ENV_NAME}

Modify kustomization.yaml before deployment

A common use case for modifying the kustomization.yaml is to modify the container
image names/versions used as part of your deployment.

The following example specifies an edits configuration and sets any valid kustomize
edit ... command. azd automatically interpolates any environment variables

referenced within the edit command.

yml

# azure.yaml

name: todo-nodejs-mongo-aks
metadata:
template: todo-nodejs-mongo-aks@0.0.1-beta
services:
api:
project: ./src/api
language: js
host: aks
k8s:
kustomize:
dir: ./kustomize/overlays/${AZURE_ENV_NAME}
edits:
- set image todo-api=${SERVICE_API_IMAGE_NAME}

Use azd environment variables within config maps

Config maps or secrets are critical in configuring your k8s clusters. Since kustomize does
not support any direct environment variable substitution we can leverage the
kustomize configMapGenerator with a .env file.

The kustomize configuration section supports a env section where one or many
key/value pairs can be defined. This configuration automatically generates a temporary
.env file within your kustomization directory that can be used by a configMapGenerator .

The following configuration will create a .env with the specified key/value pairs.

yml

# azure.yaml

name: todo-nodejs-mongo-aks
metadata:
template: todo-nodejs-mongo-aks@0.0.1-beta
services:
api:
project: ./src/api
language: js
host: aks
k8s:
kustomize:
dir: ./kustomize/overlays/${AZURE_ENV_NAME}
edits:
- set image todo-api=${SERVICE_API_IMAGE_NAME}
env:
AZURE_AKS_IDENTITY_CLIENT_ID: ${AZURE_AKS_IDENTITY_CLIENT_ID}
AZURE_KEY_VAULT_ENDPOINT: ${AZURE_KEY_VAULT_ENDPOINT}
APPLICATIONINSIGHTS_CONNECTION_STRING:
${APPLICATIONINSIGHTS_CONNECTION_STRING}

The configMapGenerator generates a k8s config map with the specified name and
contains all the key/value pairs referenced within the .env file.

yml

# kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
- deployment.yaml
- service.yaml
- ingress.yaml

configMapGenerator:
- name: todo-web-config
 envs:
- .env

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Remote Environments Support
Article • 09/13/2024

How do remote environments work?

To use remote environments, you can enable remote state to ensure the environment
state automatically persists to the configured remote store. Meaning any azd command
that writes to your azd .env or config.json file will automatically persist.

Configure remote state

Remote state for azd can be configured globally in azd 's config.json or by project
within the azure.yaml . If remote state is not set up, environment values and
configuration continue to be stored locally.

You can configure remote state within the state.remote element of azd configuration

backend: The name of the backend type used for remote state
config: Map of key/value pairs unique to each remote state provider

Enable by project

azure.yaml

YAML

name: azd-project-name
state:
remote:
backend: AzureBlobStorage
config:
accountName: saazdremotestate
containerName: myproject # Defaults to project name if not specified

Enable globally

azd config.json

JSON
 {
"state": {
"remote": {
"backend": "AzureBlobStorage",
"config": {
"accountName": "saazdremotestate"
}
}
}
}

Supported Remote state backends

Azure Blob Storage

azd writes .env and config.json files to an Azure storage blob container

Configuration
accountName: Name of the Azure storage account
containerName: Name of the container within the storage account where
configuration is stored. Defaults to the current azd project name if not specified
endpoint: Azure Endpoint used when configuring remote state. Defaults to
core.windows.net

Remote state and azd commands

azd env list

Lists all local and remote environments available. For example:

azd env select

When selecting an environment that does not exist locally, the remote state is copied to
a new local environment.

For example, consider the output from azd env list above. To copy the remote state,
dev to your local environment you would run the following:

Azure Developer CLI

azd env select dev

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Azure Developer CLI support for Azure
Deployment Environments
Article • 09/14/2024

The Azure Developer CLI (azd) provides support for Azure Deployment Environments.
An Azure Deployment Environment (ADE) is a preconfigured collection of Azure
resources deployed in predefined subscriptions. Azure governance is applied to those
subscriptions based on the type of environment, such as sandbox, testing, staging, or
production. With Azure Deployment Environments, your can enforce enterprise security
policies and provide a curated set of predefined infrastructure as code (IaC) templates.

Prerequisites
Verify you have completed the following prerequisites to work with Azure Deployment
Environments using azd :

Installed azd locally or have access to azd via Cloud Shell

Created and configured an Azure Deployment Environment with a dev center,

project, and template catalog

Configured environment types at the dev center level and project level

Ensure the developer has Deployment Environments User role on the project

 Tip

Understanding key concepts about Azure Deployment Environments is

essential for working with them via azd .

Enable Azure Deployment Environment

support
You can configure azd to provision and deploy resources to your deployment
environments using standard commands such as azd up or azd provision . To enable
support for Azure Deployment Environments, run the following command:

Bash
 azd config set platform.type devcenter

When platform.type is set to devcenter , all azd remote environment state and
provisioning will leverage new dev center components. This configuration also means
that the infra folder in your local templates will effectively be ignored. Instead, azd will
use one of the infrastructure templates defined in your dev center catalog for resource
provisioning.

You can also disable dev center support via the following command:

Bash

azd config unset platform

Work with Azure Deployment Evironments

When the dev center feature is enabled, the default behavior of some common azd
commands changes to work with these remote environments. The dev center feature
expands on functionality provided by standard azd remote environment support.

azd init
The azd init command experience in dev center mode shows all the azd compatible
ADE templates for selection from your configured catalog. During the init process, after
azd clones down the template code, the azure.yaml file will automatically be updated

to include a platform section with the selected configuration based on the template
that was chosen. The configuration includes the dev center name, catalog, and
environment definition.

Bash

`azd init`

azd up
The azd up command will package, provision, and deploy your application to Azure
Deployment Environments. However, the provision stage of the azd up command will
use the curated infrastructure-as-code templates in your remote dev center, while the
deployment stage will deploy the source code in your azd template. While dev center
mode is enabled, azd will ignore the infra folder in your local azd template and only
provision resources using the dev center templates. The command will also prompt you
for any necessary values, such as the Azure Deployment Environment project or
environment type.

Bash

azd up

azd template list

The azd template list command will display the available infrastructure templates in
your dev center catalog, rather than showing templates from the default AZD Awesome
gallery. Catalogs provide a set of curated and approved infrastructure-as-code
templates your development teams can use to create environments.

Bash

azd template list

azd provision
The azd provision command will create new dev center environments. The command
will prompt you for any missing values, such as the environment type or project. When
the command runs, it will use the associated infrastructure template to provision the
correct set of Azure resources for that environment. While dev center mode is enabled,
azd will ignore the infra folder in your local azd template and only provision resources

using the dev center templates.

Bash

azd provision

azd env list

The azd env list command will display the same list of environments you would see in
the developer portal.

Bash

azd env list

Tagging resources for Azure Deployment

Environments
azd provisioning for Azure Deployment Environments relies on curated templates from

the dev center catalog. Templates in the catalog may or may not assign tags to
provisioned Azure resources for you to associate your app services with in the
azure.yaml file. If the templates do not assign tags, you can address this issue in one of

two ways:

Work with your dev center catalog administrator to ensure the provisioned Azure
resources include tags to associate them with services defined in your azure.yaml
file.

Specify the resoureName in your azure.yaml file instead of using tags:

yml

services:
api:
project: ./src/api
host: containerapp
language: js
resourceName: sample-api-containerapp
web:
project: ./src/web
host: containerapp
language: js
resourceName: sample-web-containerapp

Configure dev center settings

You can define azd settings for your dev centers in multiple places. Settings are
combined from these locations to create the final set of configurations in the following
order of precedence:

1. Environment variables
 2. Azd environment configuration
3. Project configuration
4. User configuration

azd will automatically prompt you for any configuration values that are missing from

these sources. Each of these configuration options is detailed in the following sections.

Environment variables
The following environment variables will be discovered and used by azd :

AZURE_DEVCENTER_NAME
AZURE_DEVCENTER_PROJECT
AZURE_DEVCENTER_CATALOG
AZURE_DEVCENTER_ENVIRONMENT_DEFINITION
AZURE_DEVCENTER_ENVIRONMENT_TYPE
AZURE_DEVCENTER_ENVIRONMENT_USER

Define configurations
Define configurations for your dev centers at the azd environment scope in
.azure/<env>/config.json file:

JSON

{
"platform": {
"config": {
"catalog": "SampleCatalog",
"environmentDefinition": "Todo",
"environmentType": "Dev",
"name": "sample-devcenter",
"Project": "SampleProject"
}
}
}

Project scope
Define configurations for your dev centers at the azd project scope in the platform
node of the azure.yaml file:

YAML
 name: todo-nodejs-mongo-aca
metadata:
template: todo-nodejs-mongo-aca@0.0.1-beta
platform:
type: devcenter
config:
catalog: SampleCatalog
environmentDefinition: Todo
name: sample-devcenter
project: SampleProject
services:
api:
project: ./src/api
host: containerapp
language: js
web:
project: ./src/web
host: containerapp
language: js

User scope
Define configurations for your dev centers at the user scope in the
~/<user_profile>/.azd/config.json file:

JSON

{
"platform": {
"config": {
"catalog": "SampleCatalog",
"environmentDefinition": "Todo",
"environmentType": "Dev",
"name": "sample-devcenter",
"Project": "SampleProject"
}
}
}

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Manage environment variables
Article • 09/17/2024

Environment variables influence how resources are provisioned and deployed to Azure.
This is especially useful when running azd in CI/CD workflow scenarios.

Input Parameters Substitution

Environment variables can be referenced in parameter files ( *.parameters.json for
Bicep, *.tfvars.json for Terraform) as part of provisioning. When an environment
variable substitution syntax is encountered, azd automatically substitutes the reference
with the actual environment variable value set. Substitution also occurs for certain
configuration settings in azure.yaml (properties documented with 'Supports
environment variable substitution'), and in deployment configuration files, such as
deployment manifests for aks .

Input parameter substitution example (Bicep)

Suppose that you have the environment variable AZURE_LOCATION set:

Bash

export AZURE_LOCATION=westus3

PowerShell

$env:AZURE_LOCATION='westus3'

In the main.parameters.json file, you can reference AZURE_LOCATION and allow for
environment substitution using the following syntax:

JSON

{
"$schema": "https://schema.management.azure.com/schemas/2019-04-
01/deploymentParameters.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"location": {
"value": "${AZURE_LOCATION}"
}
 }
}

Environment-specific .env file

Outputs for infrastructure provisioning are automatically stored as environment
variables in an .env file, located under .azure/<environment name>/.env . This setup
allows for a local application, or deployment scripts, to use variables stored in the .env
file to reference Azure-hosted resources if needed. To see these outputs, run azd env
get-values , or azd env get-values --output json for JSON output.

Environment variables provided by azd

The following are variables that are automatically provided by azd :

ﾉ Expand table

Name Description Examples When available

AZURE_ENV_NAME The name of the todo-app-dev When an

environment in-use. environment is
created (after
running azd init or
azd env new, for
example).

AZURE_LOCATION The location of the eastus2 Right before an

environment in-use. environment is
provisioned for the
first time.

AZURE_PRINCIPAL_ID The running 925cff12-ffff- Determined

user/service principal. 4e9f-9580- automatically during
8c06239dcaa4 provisioning
(ephemeral).

AZURE_SUBSCRIPTION_ID The targeted 925cff12-ffff- Right before an

subscription. 4e9f-9580- environment is
8c06239dcaa4 provisioned for the
first time.

SERVICE_<service>_IMAGE_NAME The full name of the todoapp/web- After a successful

container image dev:azdev- publishing of a
published to Azure deploy- containerapp image
Container Registry for 1664988805
 Name Description Examples When available

container app
services.

User-provided environment variables

User-provided variables can be declared as an infrastructure output parameter (which is
automatically stored in .env ) in the main.bicep file, or set directly by the user in the
environment ( azd env set <key> <value> ). azd reads the values as configuration and
perform differently.

ﾉ Expand table

Name Description Examples Effects

AZURE_AKS_CLUSTER_NAME The name aks-my-cluster Required property

of the for deployment of
Azure an aks service.
Kubernetes
Service
cluster to
target.

AZURE_RESOURCE_GROUP The specific rg-todo-dev azd won't perform

resource resource group
group to discovery, and
target. Type instead references
string. this resource group.
azd also doesn't
control the authored
IaC configuration
files, thus changes
to IaC files may be
needed.

AZURE_CONTAINER_REGISTRY_ENDPOINT The Azure myexampleacr.azurecr.io Required property

Container for deployment of a
Registry containerapp or aks
endpoint to service.
publish
docker
image. Type
string.

SERVICE_<service>_ENDPOINTS The ['endpoint1', Sets the public

endpoints 'endpoint2'] endpoints for the
 Name Description Examples Effects

for the particular service will

particular be used by azd for
service. display. By default,
Type array azd discovers the
(bicep) / automatically
list- assigned hostnames
equivalent for a given host,
(terraform). such as
*.azurewebsites.net
for appservice .

Enable demo mode

azd includes a demo mode that hides your subscription ID in the console output. This

feature is useful for scenarios where you want to demo or present azd commands in a
public setting.

The demo mode introduces the environment variable: AZD_DEMO_MODE . To enable demo
mode, run:

Bash

export AZD_DEMO_MODE true

If you want demo mode to persist across reboots, you can also run:

Bash

setx AZD_DEMO_MODE true

or in PowerShell:

Bash

$env:AZD_DEMO_MODE="true"

Feedback
Was this page helpful?  Yes  No
Get help at Microsoft Q&A
Environment variables FAQ
Article • 09/13/2024

This article answers frequently asked questions about working with environment
variables and the Azure Developer CLI ( azd ).

What are the differences between azd environment

variables and system environment variables?
azd environment variables are stored in the .env file in the .azure/<environment name>

directory of your project and are separate from your system/OS environment variables.
azd environment variables configure template provisioning and deployment tasks and

are accessible using commands such as azd env or azd env get-values.

System environment variables are not directly accessible through azd commands and
should be managed with custom shell or PowerShell scripts, generally using azd hooks.
Can azd commands directly read and write system
environment variables?
No, azd commands cannot read or write system environment variables. Commands
such as azd env set or azd env get-values operate on values stored in the template .env
file for a specific azd environment. azd environments are managed using subfolders in
the .azure/<environment name> directory of your project template, which enables your
template to have multiple environments. Environment subfolders hold configuration
files such as .env that describe the environment.

Use custom shell or PowerShell scripts with azd hooks to read or write system level
environment variables.

What is the relationship between output variables set in

the main.bicep file and azd environment variables?
Output variables set in the main.bicep file are automatically stored in the .env file of
your azd template. Consider the following output variables in a main.bicep template
infrastructure file:

JSON

output API_BASE_URL string = api.outputs.SERVICE_API_URI

output REACT_APP_WEB_BASE_URL string = web.outputs.SERVICE_WEB_URI

After a successful azd up or azd provision , azd writes these two variables to the .env
file in the .azure/<environment name> directory of your project:

Output

API_BASE_URL="<example-api-url>"
output REACT_APP_WEB_BASE_URL="<example-app-url>"

You can then access those variables from the .env file using azd env get-values.

Which environment variables are set in the .env file by

default?
The following environment variables are set in the .env file by default:
 ﾉ Expand table

Name Description Example When available

values

AZURE_ENV_NAME The name of the todo-app-dev When an

environment in-use. environment is
created (after
running azd init or
azd env new, for
example).

AZURE_LOCATION The location of the eastus2 Right before an

environment in-use. environment is
provisioned for the
first time.

AZURE_PRINCIPAL_ID The running 925cff12-ffff- Determined

user/service principal. 4e9f-9580- automatically during
8c06239dcaa4 provisioning
(ephemeral).

AZURE_SUBSCRIPTION_ID The targeted 925cff12-ffff- Right before an

subscription. 4e9f-9580- environment is
8c06239dcaa4 provisioned for the
first time.

SERVICE_<service>_IMAGE_NAME The full name of the todoapp/web- After a successful

container image dev:azdev- publishing of a
published to Azure deploy- containerapp image
Container Registry for 1664988805
container app
services.

What is the recommended approach to retrieve azd

environment variables from the .env file? Why would I
need to do this?
Retrieve azd environment variables using the azd env get-values command.

Azure Developer CLI

azd env get-values

Common reasons to access azd environment variables include the following:

Perform additional configuration in hook scripts.

 Expose the .env values from the template to the application code framework, such
as Node.js or .NET.
Write the .env values to system environment variables.

 Tip

Use caution when setting system environment variables, as they can cause conflicts
with other templates that share the same environment variable names.

How do I manually set a new azd environment variable?

Set additional azd environment variables using the azd env set command, providing the
key and value for your variable.

Common reasons to set azd environment variables include the following:

Access Azure resource information created during provisioning that is needed

during deployment.
Override or change default azd environment variable values.
Provide additional custom configuration values for use in provisioning,
deployment, or custom scripts.

Azure Developer CLI

azd env set MY_KEY MyValue

How do I copy or write azd environment variables as

system environment variables?
In some scenarios you may want to copy azd environment variables to another
environment file or to your system environment for use by language frameworks. For
example, you may want to use endpoint URLs from provisioned Azure services to
connect to those services in your app code. Use custom scripts to retrieve azd
environment variables and then set them as system environment variables. It's common
to run these scripts as hooks during the azd lifecycle, as seen in the following example:

７ Note

Use caution when copying azd environment variables to your local system or other
operating environments. System environment variables with matching names can
 be picked up by azd and cause conflicts between different azd templates or
different azd environments.

yml

postprovision:
windows:
shell: pwsh
run: ./scripts/map-env-vars.ps1
interactive: false
continueOnError: false
posix:
shell: sh
run: ./scripts/map-env-vars.sh
interactive: false
continueOnError: false

The referenced shell script for Linux retrieves the azd environment variables and exports
them as system environment variables:

Bash

echo "Loading azd .env file from current environment..."

while IFS='=' read -r key value; do

value=$(echo "$value" | sed 's/^"//' | sed 's/"$//')
export "$key=$value"
done <<EOF
$(azd env get-values)
EOF

The referenced PowerShell script for Windows retrieves the azd environment variables
and exports them as system environment variables:

PowerShell

Write-Host "Loading azd .env file from current environment"

foreach ($line in (& azd env get-values)) {
if ($line -match "([^=]+)=(.*)") {
$key = $matches[1]
$value = $matches[2] -replace '^"|"$'
[Environment]::SetEnvironmentVariable($key, $value)
}
}

Next steps
 Manage environment variables

Customize workflows using command and event hooks

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Use Terraform as an infrastructure as
code tool for Azure Developer CLI
Article • 09/13/2024

Azure Developer CLI ( azd ) supports multiple infrastructures as code (IaC) providers,
including:

Bicep
Terraform

By default, azd assumes Bicep as the IaC provider. Refer to the Comparing Terraform
and Bicep article for help deciding which IaC provider is best for your project.

７ Note

Terraform is still in beta. Read more about alpha and beta feature support on the
feature versioning and release strategy page

Pre-requisites
Install and configure Terraform
Install and log into Azure CLI (v 2.38.0+)
Review the architecture diagram and the Azure resources you'll deploy in the
Node.js or Python Terraform template.

７ Note

While azd doesn't rely on an Azure CLI login, Terraform requires Azure CLI. Read
more about this requirement from Terraform's official documentation .

Configure Terraform as the IaC provider

1. Open the azure.yaml file found in the root of your project and make sure you have
the following lines to override the default, which is Bicep:

YAML
 infra:
provider: terraform

2. Add all your .tf files to the infra directory found in the root of your project.

3. Run azd up .

７ Note

Check out these two azd templates with Terraform as IaC Provider: Node.js and
Terraform and Python and Terraform .

azd pipeline config for Terraform

Terraform stores state about your managed infrastructure and configuration. Because of
this state file, you need to enable remote state before you run azd pipeline config to
set up your deployment pipeline in GitHub.

By default, azd assumes the use of local state file. If you ran azd up before enabling
remote state, you need to run azd down and switch to remote state file.

Local vs remote state

Terraform uses persisted state data to keep track of the resources it manages.

Scenarios for enabling remote state:

To allow shared access to the state data, and allow multiple people work together
on that collection of infrastructure resources
To avoid exposing sensitive information included in state file
To decrease the chance of inadvertent deletion because of storing state locally

Enable remote state

1. Make sure you configure a remote state storage account.

2. Add a new file called provider.conf.json in the infra folder.

JSON
 {
"storage_account_name": "${RS_STORAGE_ACCOUNT}",
"container_name": "${RS_CONTAINER_NAME}",
"key": "azd/azdremotetest.tfstate",
"resource_group_name": "${RS_RESOURCE_GROUP}"
}

3. Update provider.tf found in the infra folder to set the backend to be remote

Console

# Configure the Azure Provider

terraform {
required_version = ">= 1.1.7, < 2.0.0"
backend "azurerm" {
}

4. Run azd env set <key> <value> to add configuration in the .env file. For example:

Azure Developer CLI

azd env set RS_STORAGE_ACCOUNT your_storage_account_name

azd env set RS_CONTAINER_NAME your_terraform_container_name
azd env set RS_RESOURCE_GROUP your_storage_account_resource_group

5. Run the next azd command as per your usual workflow. When remote state is
detected, azd initializes Terraform with the configured backend configuration.

6. To share the environment with teammates, make sure they run azd env refresh -e
<environmentName> to refresh environment settings in the local system, and

perform Step 4 to add configuration in the .env file.

See also
Learn more about Terraform's dependency on Azure CLI .
For more on remote state, see store Terraform state in Azure Storage.
Template: React Web App with Node.js API and MongoDB (Terraform) on Azure

Next steps
Azure Developer CLI FAQ
Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Deploy a .NET Aspire project to Azure
Container Apps using the Azure
Developer CLI (in-depth guide)
Article • 06/15/2024

The Azure Developer CLI ( azd ) has been extended to support deploying .NET Aspire
projects. Use this guide to walk through the process of creating and deploying a .NET
Aspire project to Azure Container Apps using the Azure Developer CLI. In this tutorial,
you'll learn the following concepts:

＂ Explore how azd integration works with .NET Aspire projects

＂ Provision and deploy resources on Azure for a .NET Aspire project using azd
＂ Generate Bicep infrastructure and other template files using azd

Prerequisites
To work with .NET Aspire, you need the following installed locally:

.NET 8.0 or .NET 9.0

An OCI compliant container runtime, such as:
Docker Desktop or Podman . For more information, see Container runtime.
An Integrated Developer Environment (IDE) or code editor, such as:
Visual Studio 2022 version 17.9 or higher (Optional)
Visual Studio Code (Optional)
C# Dev Kit: Extension (Optional)
JetBrains Rider with .NET Aspire plugin (Optional)

For more information, see .NET Aspire setup and tooling, and .NET Aspire SDK.

You will also need to have the Azure Developer CLI installed locally. Common install
options include the following:

Windows

PowerShell

winget install microsoft.azd

How Azure Developer CLI integration works
The azd init workflow provides customized support for .NET Aspire projects. The
following diagram illustrates how this flow works conceptually and how azd and .NET
Aspire are integrated:

1. When azd targets a .NET Aspire project it starts the AppHost with a special
command ( dotnet run --project AppHost.csproj --output-path manifest.json --
publisher manifest ), which produces the Aspire manifest file.

2. The manifest file is interrogated by the azd provision sub-command logic to

generate Bicep files in-memory only (by default).
3. After generating the Bicep files, a deployment is triggered using Azure's ARM APIs
targeting the subscription and resource group provided earlier.
4. Once the underlying Azure resources are configured, the azd deploy sub-
command logic is executed which uses the same Aspire manifest file.
5. As part of deployment azd makes a call to dotnet publish using .NET's built in
container publishing support to generate container images.
6. Once azd has built the container images it pushes them to the ACR registry that
was created during the provisioning phase.
7. Finally, once the container image is in ACR, azd updates the resource using ARM
to start using the new version of the container image.

７ Note
 azd also enables you to output the generated Bicep to an infra folder in your

project, which you can read more about in the Generating Bicep from .NET Aspire
app model section.

Provision and deploy a .NET Aspire starter app

The steps in this section demonstrate how to create a .NET Aspire start app and handle
provisioning and deploying the app resources to Azure using azd .

Create the .NET Aspire starter app

Create a new .NET Aspire project using the dotnet new command. You can also create
the project using Visual Studio.

.NET CLI

dotnet new aspire-starter --use-redis-cache -o AspireSample

cd AspireSample
dotnet run --project AspireSample.AppHost\AspireSample.AppHost.csproj

The previous commands create a new .NET Aspire project based on the aspire-starter
template which includes a dependency on Redis cache. It runs the .NET Aspire project
which verifies that everything is working correctly.

Initialize the template

1. Open a new terminal window and cd into the directory of your .NET Aspire
solution.

2. Execute the azd init command to initialize your project with azd , which will
inspect the local directory structure and determine the type of app.

Azure Developer CLI

azd init

For more information on the azd init command, see azd init.

3. Select Use code in the current directory when azd prompts you with two app
initialization options.
 Output

? How do you want to initialize your app? [Use arrows to move, type to
filter]
> Use code in the current directory
Select a template

4. After scanning the directory, azd prompts you to confirm that it found the correct
.NET Aspire AppHost project. Select the Confirm and continue initializing my app
option.

Output

Detected services:

.NET (Aspire)
Detected in:
D:\source\repos\AspireSample\AspireSample.AppHost\AspireSample.AppHost.
csproj

azd will generate the files necessary to host your app on Azure using
Azure Container Apps.

? Select an option [Use arrows to move, type to filter]

> Confirm and continue initializing my app
Cancel and exit

5. Enter an environment name, which is used to name provisioned resources in Azure

and managing different environments such as dev and prod .

Output

Generating files to run your app on Azure:

(✓) Done: Generating ./azure.yaml

(✓) Done: Generating ./next-steps.md

SUCCESS: Your app is ready for the cloud!

You can provision and deploy your app to Azure by running the azd up
command in this directory. For more information on configuring your
app, see ./next-steps.md

azd generates a number of files and places them into the working directory. These files

are:

azure.yaml: Describes the services of the app, such as .NET Aspire AppHost project,
and maps them to Azure resources.
 .azure/config.json: Configuration file that informs azd what the current active
environment is.
.azure/aspireazddev/.env: Contains environment specific overrides.

The azure.yaml file has the following contents:

yml

# yaml-language-server:
$schema=https://raw.githubusercontent.com/Azure/azure-
dev/main/schemas/v1.0/azure.yaml.json

name: AspireSample
services:
app:
language: dotnet
project: .\AspireSample.AppHost\AspireSample.AppHost.csproj
host: containerapp

Resource naming
When you create new Azure resources, it's important to follow the naming
requirements. For Azure Container Apps, the name must be 2-32 characters long and
consist of lowercase letters, numbers, and hyphens. The name must start with a letter
and end with an alphanumeric character.

For more information, see Naming rules and restrictions for Azure resources.

Initial deployment
1. In order to deploy the .NET Aspire project, authenticate to Azure AD to call the
Azure resource management APIs.

Azure Developer CLI

azd auth login

The previous command will launch a browser to authenticate the command-line

session.

2. Once authenticated, run the following command from the AppHost project
directory to provision and deploy the application.

Azure Developer CLI

 azd up

） Important

To push container images to the Azure Container Registry (ACR), you need to
have Microsoft.Authorization/roleAssignments/write access. This can be
achieved by enabling an Admin user on the registry. Open the Azure Portal,
navigate to the ACR resource / Settings / Access keys, and then select the
Admin user checkbox. For more information, see Enable admin user.

3. When prompted, select the subscription and location the resources should be
deployed to. Once these options are selected the .NET Aspire project will be
deployed.

Output

By default, a service can only be reached from inside the Azure

Container Apps environment it is running in. Selecting a service here
will also allow it to be reached from the Internet.
? Select which services to expose to the Internet webfrontend
? Select an Azure Subscription to use: 1. <YOUR SUBSCRIPTION>
? Select an Azure location to use: 1. <YOUR LOCATION>

Packaging services (azd package)

Provisioning Azure resources (azd provision)

Provisioning Azure resources can take some time.

Subscription: <YOUR SUBSCRIPTION>

Location: <YOUR LOCATION>

You can view detailed progress in the Azure Portal:

<LINK TO DEPLOYMENT>

(✓) Done: Resource group: <YOUR RESOURCE GROUP>

(✓) Done: Container Registry: <ID>
(✓) Done: Log Analytics workspace: <ID>
(✓) Done: Container Apps Environment: <ID>

SUCCESS: Your application was provisioned in Azure in 1 minute 13

seconds.
You can view the resources created under the resource group <YOUR
RESOURCE GROUP> in Azure Portal:
<LINK TO RESOURCE GROUP OVERVIEW>

Deploying services (azd deploy)

 (✓) Done: Deploying service apiservice
- Endpoint: <YOUR UNIQUE apiservice APP>.azurecontainerapps.io/

(✓) Done: Deploying service webfrontend

- Endpoint: <YOUR UNIQUE webfrontend APP>.azurecontainerapps.io/

Aspire Dashboard: <LINK TO DEPLOYED .NET ASPIRE DASHBOARD>

SUCCESS: Your up workflow to provision and deploy to Azure completed in

3 minutes 50 seconds.

The final line of output from the azd command is a link to the Azure Portal that
shows all of the Azure resources that were deployed:

Three containers are deployed within this application:

webfrontend : Contains code from the web project in the starter template.
apiservice : Contains code from the API service project in the starter template.

cache : A Redis container image to supply a cache to the front-end.

Just like in local development, the configuration of connection strings has been handled
automatically. In this case, azd was responsible for interpreting the application model
and translating it to the appropriate deployment steps. As an example, consider the
connection string and service discovery variables that are injected into the webfrontend
container so that it knows how to connect to the Redis cache and apiservice .

For more information on how .NET Aspire projects handle connection strings and service
discovery, see .NET Aspire orchestration overview.

Deploy application updates

When the azd up command is executed the underlying Azure resources are provisioned
and a container image is built and deployed to the container apps hosting the .NET
Aspire project. Typically once development is underway and Azure resources are
deployed it won't be necessary to provision Azure resources every time code is updated
—this is especially true for the developer inner loop.

To speed up deployment of code changes, azd supports deploying code updates in the
container image. This is done using the azd deploy command:

Azure Developer CLI

azd deploy

Output
 Deploying services (azd deploy)

(✓) Done: Deploying service apiservice

- Endpoint: <YOUR UNIQUE apiservice APP>.azurecontainerapps.io/

(✓) Done: Deploying service webfrontend

- Endpoint: <YOUR UNIQUE webfrontend APP>.azurecontainerapps.io/

Aspire Dashboard: <LINK TO DEPLOYED .NET ASPIRE DASHBOARD>

It's not necessary to deploy all services each time. azd understands the .NET Aspire
project model, it's possible to deploy just one of the services specified using the
following command:

Azure Developer CLI

azd deploy webfrontend

For more information, see Azure Developer CLI reference: azd deploy.

Deploy infrastructure updates

Whenever the dependency structure within a .NET Aspire project changes, azd must re-
provision the underlying Azure resources. The azd provision command is used to apply
these changes to the infrastructure.

To see this in action, update the Program.cs file in the AppHost project to the following:

C#

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

// Add the locations database.

var locationsdb = builder.AddPostgres("db").AddDatabase("locations");

// Add the locations database reference to the API service.

var apiservice = builder.AddProject<Projects.AspireSample_ApiService>
("apiservice")
.WithReference(locationsdb);

builder.AddProject<Projects.AspireSample_Web>("webfrontend")
.WithReference(cache)
.WithReference(apiservice);
 builder.Build().Run();

Save the file and issue the following command:

Azure Developer CLI

azd provision

The azd provision command updates the infrastructure by creating a container app to
host the Postgres database. The azd provision command didn't update the connection
strings for the apiservice container. In order to have connection strings updated to
point to the newly provisioned Postgres database the azd deploy command needs to be
invoked again. When in doubt, use azd up to both provision and deploy.

Clean up resources
Remember to clean up the Azure resources that you've created during this walkthrough.
Because `azd knows the resource group in which it created the resources it can be used
to spin down the environment using the following command:

Azure Developer CLI

azd down

The previous command may take some time to execute, but when completed the
resource group and all its resources should be deleted.

Output

Deleting all resources and deployed code on Azure (azd down)

Local application code is not deleted when running 'azd down'.

Resource group(s) to be deleted:

• <YOUR RESOURCE GROUP>: <LINK TO RESOURCE GROUP OVERVIEW>

? Total resources to delete: 7, are you sure you want to continue? Yes
Deleting your resources can take some time.

(✓) Done: Deleting resource group: <YOUR RESOURCE GROUP>

SUCCESS: Your application was removed from Azure in 9 minutes 59 seconds.

Generate Bicep from .NET Aspire project model
Although development teams are free to use azd up (or azd provision and azd deploy )
commands for their deployments both for development and production purposes, some
teams may choose to generate Bicep files that they can review and manage as part of
version control (this also allows these Bicep files to be referenced as part of a larger
more complex Azure deployment).

azd includes the ability to output the Bicep it uses for provisioning via following

command:

Azure Developer CLI

azd config set alpha.infraSynth on

azd infra synth

After this command is executed in the starter template example used in this guide, the
following files are created in the AppHost project directory:

infra/main.bicep: Represents the main entry point for the deployment.

infra/main.parameters.json: Used as the parameters for main Bicep (maps to
environment variables defined in .azure folder).
infra/resources.bicep: Defines the Azure resources required to support the .NET
Aspire project model.
AspireSample.Web/manifests/containerApp.tmpl.yaml: The container app definition
for webfrontend .
AspireSample.ApiService/manifests/containerApp.tmpl.yaml: The container app
definition for apiservice .

The infra\resources.bicep file doesn't contain any definition of the container apps
themselves (with the exception of container apps which are dependencies such as Redis
and Postgres):

Bicep

@description('The location used for all deployed resources')

param location string = resourceGroup().location

@description('Tags that will be applied to all resources')

param tags object = {}

var resourceToken = uniqueString(resourceGroup().id)

resource managedIdentity
'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
 name: 'mi-${resourceToken}'
location: location
tags: tags
}

resource containerRegistry 'Microsoft.ContainerRegistry/registries@2023-07-

01' = {
name: replace('acr-${resourceToken}', '-', '')
location: location
sku: {
name: 'Basic'
}
tags: tags
}

resource caeMiRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-

04-01' = {
name: guid(containerRegistry.id, managedIdentity.id,
subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7f951dda-
4ed3-4680-a7ca-43fe172d538d'))
scope: containerRegistry
properties: {
principalId: managedIdentity.properties.principalId
principalType: 'ServicePrincipal'
roleDefinitionId:
subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7f951dda-
4ed3-4680-a7ca-43fe172d538d')
}
}

resource logAnalyticsWorkspace
'Microsoft.OperationalInsights/workspaces@2022-10-01' = {
name: 'law-${resourceToken}'
location: location
properties: {
sku: {
name: 'PerGB2018'
}
}
tags: tags
}

resource containerAppEnvironment 'Microsoft.App/managedEnvironments@2023-05-

01' = {
name: 'cae-${resourceToken}'
location: location
properties: {
appLogsConfiguration: {
destination: 'log-analytics'
logAnalyticsConfiguration: {
customerId: logAnalyticsWorkspace.properties.customerId
sharedKey: logAnalyticsWorkspace.listKeys().primarySharedKey
}
}
}
 tags: tags
}

resource cache 'Microsoft.App/containerApps@2023-05-02-preview' = {

name: 'cache'
location: location
properties: {
environmentId: containerAppEnvironment.id
configuration: {
service: {
type: 'redis'
}
}
template: {
containers: [
{
image: 'redis'
name: 'redis'
}
]
}
}
tags: union(tags, {'aspire-resource-name': 'cache'})
}

resource locations 'Microsoft.App/containerApps@2023-05-02-preview' = {

name: 'locations'
location: location
properties: {
environmentId: containerAppEnvironment.id
configuration: {
service: {
type: 'postgres'
}
}
template: {
containers: [
{
image: 'postgres'
name: 'postgres'
}
]
}
}
tags: union(tags, {'aspire-resource-name': 'locations'})
}
output MANAGED_IDENTITY_CLIENT_ID string =
managedIdentity.properties.clientId
output AZURE_CONTAINER_REGISTRY_ENDPOINT string =
containerRegistry.properties.loginServer
output AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID string =
managedIdentity.id
output AZURE_CONTAINER_APPS_ENVIRONMENT_ID string =
containerAppEnvironment.id
 output AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN string =
containerAppEnvironment.properties.defaultDomain

For more information on using Bicep to automate deployments to Azure see, What is
Bicep?

The definition of the container apps from the .NET service projects is contained within
the containerApp/tmpl.yaml files in the manifests directory in each project respectively.
Here is an example from the webfrontend project:

yml

location: {{ .Env.AZURE_LOCATION }}
identity:
type: UserAssigned
userAssignedIdentities:
? "{{ .Env.AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID }}"
: {}
properties:
environmentId: {{ .Env.AZURE_CONTAINER_APPS_ENVIRONMENT_ID }}
configuration:
activeRevisionsMode: single
ingress:
external: true
targetPort: 8080
transport: http
allowInsecure: false
registries:
- server: {{ .Env.AZURE_CONTAINER_REGISTRY_ENDPOINT }}
identity: {{ .Env.AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID }}
template:
containers:
- image: {{ .Env.SERVICE_WEBFRONTEND_IMAGE_NAME }}
name: webfrontend
env:
- name: AZURE_CLIENT_ID
value: {{ .Env.MANAGED_IDENTITY_CLIENT_ID }}
- name: ConnectionStrings__cache
value: {{ connectionString "cache" }}
- name: OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES
value: "true"
- name: OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES
value: "true"
- name: services__apiservice__0
value: http://apiservice.internal.{{
.Env.AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN }}
- name: services__apiservice__1
value: https://apiservice.internal.{{
.Env.AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN }}
tags:
 azd-service-name: webfrontend
aspire-resource-name: webfrontend

After executing the azd infra synth command, when azd provision and azd deploy
are called they use the Bicep and supporting generated files.

） Important

If azd infra synth is called again, it replaces any modified files with freshly
generated ones and prompts you for confirmation before doing so.

Isolated environments for debugging

Because azd makes it easy to provision new environments, it's possible for each team
member to have an isolated cloud-hosted environment for debugging code in a setting
that closely matches production. When doing this each team member should create
their own environment using the following command:

Azure Developer CLI

azd env new

This will prompt the user for subscription and resource group information again and
subsequent azd up , azd provision , and azd deploy invocations will use this new
environment by default. The --environment switch can be applied to these commands
to switch between environments.

Clean up resources
Run the following Azure CLI command to delete the resource group when you no longer
need the Azure resources you created. Deleting the resource group also deletes the
resources contained inside of it.

Azure CLI

az group delete --name <your-resource-group-name>

For more information, see Clean up resources in Azure.

Tutorial: Deploy a .NET Aspire project
using the Azure Developer CLI
Article • 01/26/2025

The Azure Developer CLI ( azd ) enables you to deploy .NET Aspire projects using GitHub
Actions or Azure Devops pipelines by automatically configuring the required
authentication and environment settings. This article walks you through the process of
creating and deploying a .NET Aspire project on Azure Container Apps using azd . You
learn the following concepts:

＂ Explore how azd integration works with .NET Aspire projects

＂ Create and configure a GitHub or Azure DevOps repository for a .NET Aspire project
using azd
＂ Monitor and explore GitHub Actions workflow or Azure DevOps pipeline executions
and Azure deployments

Prerequisites
To work with .NET Aspire, you need the following installed locally:

.NET 8.0 or .NET 9.0

An OCI compliant container runtime, such as:
Docker Desktop or Podman . For more information, see Container runtime.
An Integrated Developer Environment (IDE) or code editor, such as:
Visual Studio 2022 version 17.9 or higher (Optional)
Visual Studio Code (Optional)
C# Dev Kit: Extension (Optional)
JetBrains Rider with .NET Aspire plugin (Optional)

For more information, see .NET Aspire setup and tooling, and .NET Aspire SDK.

You also need to have the Azure Developer CLI installed locally (version 1.5.1 or higher).
Common install options include the following:

Windows

PowerShell

winget install microsoft.azd

Create a .NET Aspire solution
As a starting point, this article assumes that you've created a .NET Aspire solution from
the .NET Aspire Starter Application template. For more information, see Quickstart:
Build your first .NET Aspire app.

Initialize the template

1. Open a new terminal window and cd into the directory of your .NET Aspire
solution.

2. Execute the azd init command to initialize your project with azd , which will
inspect the local directory structure and determine the type of app.

Azure Developer CLI

azd init

For more information on the azd init command, see azd init.

3. Select Use code in the current directory when azd prompts you with two app
initialization options.

Output

? How do you want to initialize your app? [Use arrows to move, type to
filter]
> Use code in the current directory
Select a template

4. After scanning the directory, azd prompts you to confirm that it found the correct
.NET Aspire AppHost project. Select the Confirm and continue initializing my app
option.

Output

Detected services:

.NET (Aspire)
Detected in:
D:\source\repos\AspireSample\AspireSample.AppHost\AspireSample.AppHost.
csproj

azd will generate the files necessary to host your app on Azure using
Azure Container Apps.
 ? Select an option [Use arrows to move, type to filter]
> Confirm and continue initializing my app
Cancel and exit

5. Enter an environment name, which is used to name provisioned resources in Azure

and managing different environments such as dev and prod .

Output

Generating files to run your app on Azure:

(✓) Done: Generating ./azure.yaml

(✓) Done: Generating ./next-steps.md

SUCCESS: Your app is ready for the cloud!

You can provision and deploy your app to Azure by running the azd up
command in this directory. For more information on configuring your
app, see ./next-steps.md

azd generates a number of files and places them into the working directory. These files

are:

azure.yaml: Describes the services of the app, such as .NET Aspire AppHost project,
and maps them to Azure resources.
.azure/config.json: Configuration file that informs azd what the current active
environment is.
.azure/aspireazddev/.env: Contains environment specific overrides.

Create the GitHub repository and pipeline

The Azure Developer CLI enables you to automatically create CI/CD pipelines with the
correct configurations and permissions to provision and deploy resources to Azure. azd
can also create a GitHub repository for your app if it doesn't exist already.

1. Run the azd pipeline config command to configure your deployment pipeline
and securely connect it to Azure:

Azure Developer CLI

azd pipeline config

2. Select the subscription to provision and deploy the app resources to.
 3. Select the Azure location to use for the resources.

4. When prompted whether to create a new Git repository in the directory, enter y

and press Enter .

７ Note

Creating a GitHub repository required you being logged into GitHub. There
are a few selections that vary based on your preferences. After logging in, you
will be prompted to create a new repository in the current directory.

5. Select Create a new private GitHub repository to configure the git remote.

6. Enter a name of your choice for the new GitHub repository or press enter to use
the default name. azd creates a new repository in GitHub and configures it with
the necessary secrets required to authenticate to Azure.

7. Enter y to proceed when azd prompts you to commit and push your local
changes to start the configured pipeline.

Explore the GitHub Actions workflow and

deployment
1. Navigate to your new GitHub repository using the link output by azd .

2. Select the Actions tab to view the repository workflows. You should see the new
workflow either running or already completed. Select the workflow to view the job
steps and details in the logs of the run. For example, you can expand steps such as
Install .NET Aspire Workload or Deploy application to see the details of the
completed action.
3. Select Deploy Application to expand the logs for that step. You should see two
endpoint urls printed out for the apiservice and webfrontend . Select either of
these links to open them in another browser tab and explore the deployed
application.
Congratulations! You successfully deployed a .NET Aspire project using the Azure
Developer CLI and GitHub Actions.

Clean up resources
Run the following Azure CLI command to delete the resource group when you no longer
need the Azure resources you created. Deleting the resource group also deletes the
resources contained inside of it.

Azure CLI

az group delete --name <your-resource-group-name>

For more information, see Clean up resources in Azure.

Explore Azure Developer CLI
configuration
Article • 12/20/2024

The Azure Developer CLI ( azd ) allows you to manage azd configurations using a set of
azd config commands. These configuration settings include useful defaults such as

your Azure subscription and location, as well as settings used by other azd commands
or features. You can also get and set your own custom values and use them in scripts or
custom functionality.

In this article, you learn:

Key concepts about Azure Developer CLI configuration

How to work with azd config commands
How azd config integrates with other azd features

Explore the Azure Developer CLI config file

When you first install the Azure Developer CLI, a file named config.json is added in the
following location:

$HOME/.azd on Linux and macOS

%USERPROFILE%\.azd on Windows

 Tip

The configuration directory can be overridden by specifying a path in the

AZD_CONFIG_DIR environment variable.

The settings in this file manage functionality such as:

The default Azure subscription or location to use when you provision or deploy
resources
Which alpha features are enabled
Which template source locations are configured
Custom values set by the user for scripts or other purposes

By default, the config.json file contains only a few configurations for the default azd
template source locations. As you use various features of the Azure Developer CLI, some
values are populated in config.json automatically. For example, the first time you run
the azd up command, the subscription and location you select for provisioning and
deployment are stored in the defaults section of the file.

A simple config.json file might resemble the following:

JSON

{
"defaults": {
"location": "eastus2",
"subscription": "your-subscription-id"
},
"template": {
"sources": {
"awesome-azd": {
"key": "awesome-azd",
"location": "https://aka.ms/awesome-azd/templates.json",
"name": "Awesome AZD",
"type": "awesome-azd"
},
"default": {
"key": "default",
"name": "default"
}
}
}
}

Work with configuration commands

The Azure Developer CLI provides a set of commands to manage the settings in the
config.json file manually:

azd config get : Get a configuration value.

azd config list-alpha : Display the list of available features in alpha stage.

azd config reset : Reset configuration to default.

azd config set : Set a configuration.

azd config show : Show all of the configuration values.

azd config unset : Unset a configuration.

These commands are explored more in the following sections. You can also visit the
Azure Developer CLI commands reference page to learn more about azd commands.

Display configurations
View the current contents of the entire config.json file at any time by running the azd
config show command:

Azure Developer CLI

azd config show

Sample output:

JSON

{
"defaults": {
"location": "eastus2",
"subscription": "your-subscription-id"
},
"template": {
"sources": {
"awesome-azd": {
"key": "awesome-azd",
"location": "https://aka.ms/awesome-azd/templates.json",
"name": "Awesome AZD",
"type": "awesome-azd"
},
"default": {
"key": "default",
"name": "default"
}
}
}
}

Display a specific configuration value using the azd config get <key> command:

Azure Developer CLI

azd config get defaults

Sample output:

JSON

"defaults": {
"location": "eastus2",
"subscription": "your-subscription-id"
}
Enabling or disabling alpha features is a common configuration task, so azd also
includes a convenience command to view the current status of alpha features:

Azure Developer CLI

azd config list-alpha

Sample output:

Output

Name: aca.persistDomains
Description: Do not change custom domains when deploying Azure Container
Apps.
Status: Off

Name: aca.persistIngressSessionAffinity
Description: Do not change Ingress Session Affinity when deploying Azure
Container Apps.
Status: Off

Name: aks.helm
Description: Enable Helm support for AKS deployments.
Status: On

Name: aks.kustomize
Description: Enable Kustomize support for AKS deployments.
Status: Off

Name: azd.operations
Description: Extends provisioning providers with azd operations.
Status: Off

Name: compose
Description: Enable simplified app-centric modeling. Run `azd add` to add
Azure components to your project.
Status: On

Name: deployment.stacks
Description: Enables Azure deployment stacks for ARM/Bicep based
deployments.
Status: Off

Name: infraSynth
Description: Enable the `infra synth` command to write generated
infrastructure to disk.
Status: Off

Get and set configurations

You can get, set, or unset values in the config.json file using azd config commands.
Some specific configurations are used by other azd features and commands, such as
when enabling alpha features or setting template sources, but you can also set your own
custom values.

Manage configurations used by azd

Use the azd config set <key> <value> command to add a configuration setting to the
config.json file.

For example, to enable the azd compose alpha feature:

Azure Developer CLI

azd config set alpha.compose on

７ Note

Use . syntax to traverse JSON object structures when you get and set
configuration values, such as in the case of alpha.compose .

Verify the setting was enabled using the azd config get <key> command, such as the
following:

Azure Developer CLI

azd config get alpha.compose

Sample output:

JSON

"on"

In this scenario, you can also run azd config get alpha to view the entire JSON object
in the config.json file:

Azure Developer CLI

azd config get alpha

Sample output:

JSON

{
"compose": "on"
}

Manage custom configurations

You can also set custom configuration values to use in azd hooks and customer scripts.
These configuration values provide an alternative to using environment variables.

To set a custom configuration value:

Azure Developer CLI

azd config get customVal hello-world

Get the custom configuration value:

Azure Developer CLI

azd config get customVal

Sample output:

JSON

hello-world

Reset configurations
You can reset the Azure Developer CLI config.json file back to its defaults using the azd
config reset command, which deletes the contents of the file:

Azure Developer CLI

azd config reset

When you run azd config show after a reset, you will simply see an empty object:
 JSON

{}

Next steps
Create Azure Developer CLI templates overview

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Customize your Azure Developer CLI
workflows using command and event
hooks
Article • 10/22/2024

The Azure Developer CLI supports various extension points to customize your workflows
and deployments. The hooks middleware allows you to execute custom scripts before
and after azd commands and service lifecycle events. hooks follow a naming convention
using pre and post prefixes on the matching azd command or service event name.

For example, you may want to run a custom script in the following scenarios:

Use the prerestore hook to customize dependency management.

Use the predeploy hook to verify external dependencies or custom configurations
are in place before deploying your app.
Use the postup hook at the end of a workflow or pipeline to perform custom
cleanup or logging.

Available hooks
The following azd command hooks are available:

prerestore and postrestore : Run before and after package dependencies are

restored.
preprovision and postprovision : Run before and after Azure resources are

created.
predeploy and postdeploy : Run before and after the application code is deployed

to Azure.
preup and postup : Run before and after the combined deployment pipeline. Up is

a shorthand command that runs restore , provision , and deploy sequentially.

predown and postdown : Run before and after the resources are removed.

The following service lifecycle event hooks are available:

prerestore and postrestore : Run before and after the service packages and

dependencies are restored.

prebuild and postbuild : Run before and after the service source code or

container is built.
 prepackage and postpackage : Run before and after the app is packaged for

deployment.
predeploy and postdeploy : Run before and after the service code is deployed to

Azure.

Hook configuration
Hooks can be registered in your azure.yaml file at the root or within a specific service
configuration. All types of hooks support the following configuration options:

shell : sh | pwsh (automatically inferred from run if not specified).

Note: PowerShell 7 is required for pwsh .

run : Define an inline script or a path to a file.

continueOnError : When set will continue to execute even after a script error
occurred during a command hook (default false).
interactive : When set will bind the running script to the console stdin , stdout &
stderr (default false).

windows : Specifies that the nested configurations will only apply on windows OS. If

this configuration option is excluded, the hook executes on all platforms.

posix : Specifies that the nested configurations will only apply to POSIX based

OSes (Linux & MaxOS). If this configuration option is excluded, the hook executes
on all platforms.

Hook examples
The following examples demonstrate different types of hook registrations and
configurations.

Root command registration

Hooks can be configured to run for specific azd commands at the root of your
azure.yaml file.

The project directory (where the azure.yaml file is located) is the default current
working directory ( cwd ) for command hooks.

yml

name: todo-nodejs-mongo
metadata:
template: todo-nodejs-mongo@0.0.1-beta
 hooks:
prerestore: # Example of an inline script. (shell is required for inline
scripts)
shell: sh
run: echo 'Hello'
preprovision: # Example of external script (Relative path from project
root)
run: ./hooks/preprovision.sh
services:
web:
project: ./src/web
dist: build
language: js
host: appservice
api:
project: ./src/api
language: js
host: appservice

Service registration
Hooks can also be configured to run only for specific services defined in your .yaml file.

The service directory (same path as defined in the project property of the service
configuration in the azure.yaml file) is the default cwd for service hooks.

yml

name: todo-nodejs-mongo
metadata:
template: todo-nodejs-mongo@0.0.1-beta
services:
web:
project: ./src/web
dist: build
language: js
host: appservice
api:
project: ./src/api
language: js
host: appservice
hooks:
prerestore: # Example of an inline script. (shell is required for
inline scripts)
shell: sh
run: echo 'Restoring API service...'
prepackage: # Example of external script (Relative path from service
path)
run: ./hooks/prepackage.sh
OS specific hooks
Optionally, hooks can also be configured to run either on Windows or Posix (Linux &
MaxOS). By default, if the Windows or Posix configurations are excluded the hook
executes on all platforms.

yml

name: todo-nodejs-mongo
metadata:
template: todo-nodejs-mongo@0.0.1-beta
hooks:
prerestore:
posix: # Only runs on Posix environments
shell: sh
run: echo 'Hello'
windows: # Only runs on Windows environments
shell: pwsh
run: Write-Host "Hello"
services:
web:
project: ./src/web
dist: build
language: js
host: appservice
api:
project: ./src/api
language: js
host: appservice

Multiple hooks per event

You can configure multiple hooks per event across different scopes, such as the root
registration level or for a specific service:

yml

name: example-project
services:
api:
project: src/api
host: containerapp
language: ts
hooks:
postprovision:
- shell: sh
run: scripts/postprovision1.sh
- shell: sh
run: scripts/postprovision2.sh
hooks:
 postprovision:
- shell: sh
run: scripts/postprovision1.sh
- shell: sh
run: scripts/postprovision2.sh

Use environment variables with hooks

Hooks can get and set environment variables in the .env file using the azd env get-
values and azd set <key> <value> commands. Hooks can also retrieve environment

variables from your local environment using the ${YOUR_ENVIRONMENT VARIABLE} syntax.
azd automatically sets certain environment variables in the .env file when commands

are run, such as AZURE_ENV_NAME and AZURE_LOCATION . Output parameters from the
main.bicep file are also set in the .env file. The manage environment variables page

includes more information about environment variable workflows.

Hooks can get and set environment variables inline or through referenced scripts, as
demonstrated in the following example:

yml

name: azure-search-openai-demo
metadata:
template: azure-search-openai-demo@0.0.2-beta
services:
backend:
project: ./app/backend
language: py
host: appservice
hooks:
postprovision:
windows: # Run referenced script that uses environment variables (script
shown below)
shell: pwsh
run: ./scripts/prepdocs.ps1
interactive: true
continueOnError: false
posix:
shell: sh
run: ./scripts/prepdocs.sh
interactive: true
continueOnError: false
postdeploy: # Pull environment variable inline from local device and set
in .env file
shell: sh
run: azd env set REACT_APP_WEB_BASE_URL ${SERVICE_WEB_ENDPOINT_URL}
The referenced: prepdocs.sh script:

Bash

echo "Loading azd .env file from current environment"

# Use the `get-values` azd command to retrieve environment variables from

the `.env` file
while IFS='=' read -r key value; do
value=$(echo "$value" | sed 's/^"//' | sed 's/"$//')
export "$key=$value"
done <<EOF
$(azd env get-values)
EOF

echo 'Creating python virtual environment "scripts/.venv"'

python3 -m venv scripts/.venv

echo 'Installing dependencies from "requirements.txt" into virtual

environment'
./scripts/.venv/bin/python -m pip install -r scripts/requirements.txt

echo 'Running "prepdocs.py"'

./scripts/.venv/bin/python ./scripts/prepdocs.py './data/*'
--storageaccount "$AZURE_STORAGE_ACCOUNT"
--container "$AZURE_STORAGE_CONTAINER"
--searchservice "$AZURE_SEARCH_SERVICE"
--openaiservice "$AZURE_OPENAI_SERVICE"
--openaideployment "$AZURE_OPENAI_EMB_DEPLOYMENT"
--index "$AZURE_SEARCH_INDEX"
--formrecognizerservice "$AZURE_FORMRECOGNIZER_SERVICE"
--tenantid "$AZURE_TENANT_ID" -v

Request help
For information on how to file a bug, request help, or propose a new feature for the
Azure Developer CLI, please visit the troubleshooting and support page.

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Enable Azure Developer CLI demo mode
Article • 11/20/2024

By default, some Azure Developer CLI commands display Azure subscription IDs in the
console output. This behavior is useful during development to monitor deployments
and template behavior. However, azd also includes a demo mode to hide Azure
subscription IDs for scenarios such as public presentations that use azd commands,
screen sharing with other users, or any other situation where you want to keep your
subscription IDs hidden.

Enable demo mode

Demo mode behavior is based on the environment variable: AZD_DEMO_MODE . To enable
demo mode, run:

Bash

export AZD_DEMO_MODE true

To persist demo mode across reboots, you can also run:

Bash

Bash

setx AZD_DEMO_MODE true

７ Note

After setting the AZD_DEMO_MODE environment variables, you may need to close and
reopen your terminal window to reload the variable and apply the changes.

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Configure and consume template
sources
Article • 12/06/2024

The Azure Developer CLI is designed around a powerful template system that
streamlines deploying and provisioning Azure resources. While developing with azd ,
you have the option to either build your own template, or choose from a configurable
list of existing templates. In this article, you learn how to work with template lists and
configure your local azd installation to support different template list sources.

Understand template sources

An azd template source points to a JSON configuration file that describes a list of
available templates and their essential metadata, such as the name, description, and
location of the template source code (usually a GitHub repo). When you enable a
template source, the templates it defines are made available to azd through other
commands. For example, the template source JSON snippet below defines two
templates:

JSON

[
{
"name": "Starter - Bicep",
"description": "A starter template with Bicep as infrastructure
provider",
"repositoryPath": "azd-starter-bicep",
"tags": ["bicep"]
},
{
"name": "Starter - Terraform",
"description": "A starter template with Terraform as infrastructure
provider",
"repositoryPath": "azd-starter-terraform",
"tags": ["terraform"]
}
]

Each template entry in the JSON configuration file includes the following properties:

name: The display name of the template.

description: A brief summary of what the template does.
repositoryPath: The path to the template's source code, which can be:
 A fully qualified URI to a Git repository, like
"https://dev.azure.com/org/project/_git/repo".
"{owner}/{repo}" for GitHub repositories.
"{repo}" for GitHub repositories under the Azure-Samples organization.
tags: Keywords that help users filter templates with azd init --filter <tag> and
azd template list --filter <tag> .

For a full example, see this JSON file , which is the default template source included in
azd .

azd allows you to enable multiple template sources at a time. The following template

source options are currently available to choose from:

awesome-azd - A list of the templates from the Awesome AZD gallery that is
enabled by default.
default - A small set of curated templates to demonstrate different tech stacks.
file - A local/network path that points to a template source JSON configuration file.
url - An HTTP(S) addressable path that points to a template source JSON
configuration file.
gh - Points to a GitHub repository.
ade - Points to an Azure Deployment Environment template list. Learn more about
Azure Developer CLI support for Azure Deployment Environments.

Work with template sources

azd provides several commands to configure template sources.

Use the azd template source list command to list all currently configured template
sources:

Azure Developer CLI

azd template source list

Example output with two configured template sources:

Output

Key Name Type Location

awesome-azd Awesome AZD awesome-azd https://aka.ms/awesome-

azd/templates.json
default Default resource
Use the azd template source add command to add a new template source. This
command accepts the following parameters:

key: The technical name of the template source.

--type, -t: The template source type - valid values are file, url and gh for GitHub.
--location, -l: The template source location, which should be a local network or
HTTP(S) web URI.
--name, -n: The template source display name (optional, uses key if omitted).

Azure Developer CLI

azd template source add <key> --type <file-or-url-or-gh> --location <your-

uri> --name <your-display-name>

Use the azd template source remove command to remove a template source:

Azure Developer CLI

azd template source remove <key>

Use the azd config reset command to reset the template configuration back to default
settings:

Azure Developer CLI

azd config reset

Work with template lists

After you configure your template sources, use the azd template list command to list
the available templates from those sources:

Azure Developer CLI

azd template list

For example, a default installation of azd lists the following templates from the
awesome-azd template source:

Output

Name Source
Repository Path
 Event Driven Java Application with Azure Service Bus Awesome AZD
Azure-Samples/ASA-Samples-Event-Driven-Application
Static React Web App with Java API and PostgreSQL Awesome AZD
Azure-Samples/ASA-Samples-Web-Application
SAP CAP on Azure App Service Quickstart Awesome AZD
Azure-Samples/app-service-javascript-sap-cap-quickstart
SAP Cloud SDK on Azure App Service Quickstart (TypeScript) Awesome AZD
Azure-Samples/app-service-javascript-sap-cloud-sdk-quickstart
Java Spring Apps with Azure OpenAI Awesome AZD
Azure-Samples/app-templates-java-openai-springapps
WordPress with Azure Container Apps Awesome AZD
Azure-Samples/apptemplate-wordpress-on-ACA
Bicep template to bootstrap Azure Deployment Environments Awesome AZD
Azure-Samples/azd-deployment-environments
Starter - Bicep Awesome AZD
Azure-Samples/azd-starter-bicep
Starter - Terraform Awesome AZD
Azure-Samples/azd-starter-terraform
...
# Additional templates omitted

Include the --source flag to only list templates from a specific source:

Azure Developer CLI

azd template list --source <source-name>

To initialize a template from the displayed list, run the azd init command and provide
the repository path of the template:

Azure Developer CLI

azd init --template <path-value>

Work with Azure Deployment Environments

The Azure Developer CLI ( azd ) also provides support for Azure Deployment
Environments. An Azure Deployment Environment (ADE) is a preconfigured collection of
Azure resources deployed in predefined subscriptions. Azure governance is applied to
those subscriptions based on the type of environment, such as sandbox, testing, staging,
or production. With Azure Deployment Environments, your can enforce enterprise
security policies and provide a curated set of predefined infrastructure as code (IaC)
templates.
ADE integration is beyond the scope of this article. Learn more about configuring ade
support in the Azure Developer CLI support for Azure Deployment Environments
documentation.

Next steps
Azure Developer CLI support for Azure Deployment Environments

Template list command reference

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Use Azure Developer CLI in sovereign
clouds
Article • 03/15/2024

This guide explains how to configure the Azure Developer CLI to provision resources
and deploy applications in different clouds.

The Azure Developer CLI supports the following clouds:

Azure Public ( AzureCloud ) default

Azure China Cloud ( AzureChinaCloud )
Azure US Government ( AzureUSGovernment )

The Azure Public cloud is the default and will be used if no cloud is specified.

Authentication
When switching between clouds, run azd auth login to authenticate with the set cloud.

The following example sets a sovereign cloud and runs azd auth login to authenticate
with that cloud:

Bash

azd config set cloud.name AzureUSGovernment

azd auth login

Cloud configurations
Clouds can be configured at the user, project, or environment level. The order of
configuration precedence is:

1. Environment configuration is selected first

2. If no cloud is confiugred in the environment, the project configuration
(azure.yaml) is used
3. If no cloud is set in the project configuration, the user configuration ( azd config
set ) is used

4. If no cloud is set in the user configuration azd uses the public AzureCloud
Configure clouds with user settings (azd config set)
Set the cloud for all azd operations using azd config

Bash

azd config set cloud.name AzureCloud

Bash

azd config set cloud.name AzureChinaCloud

Bash

azd config set cloud.name AzureUSGovernment

Configure clouds in the project's azure.yaml file

Use the cloud object to set the name of the cloud in the project's azure.yaml file.

YAML

name: project-name
cloud:
name: AzureCloud
# ...

YAML

name: project-name
cloud:
name: AzureChinaCloud
# ...

YAML

name: project-name
cloud:
name: AzureUSGovernment
# ...

Configure clouds in an environment's config.json file

Configure cloud for specific environments by updating the environment configuration
file in .azure/<environment-name>/config.json . This enables, for example, deployment in
different clouds for different environments.

JSON

{
"cloud": {
"name": "AzureCloud"
}
}

JSON

{
"cloud": {
"name": "AzureChinaCloud"
}
}

JSON

{
"cloud": {
"name": "AzureUSGovernment"
}
}

Supported commands and platforms

Supported commands include

auth
config
deploy
down
env
provision
up
monitor
show

azd pipeline is not supported in Sovereign Clouds.

devcenter platform is not supported in Sovereign Clouds.

Deploying with Terraform

When deploying to a sovereign cloud using azd and Terraform, the az CLI must also be
configured to use the desired cloud. See Terraform's Authenticating using the Azure
CLI documentation.

Set the environment variable ARM_ENVIRONMENT to the desired environment. Common

values include:

public (default)
usgovernment

china

Select the appropriate cloud using the az CLI:

Bash

az cloud set --name AzureCloud

Bash

az cloud set --name AzureChinaCloud

Bash

az cloud set --name AzureUSGovernment

Troubleshoot Azure Developer CLI
Article • 09/14/2024

This article provides solutions to common problems that might arise when you're using
Azure Developer CLI (azd).

Get help and give feedback

If you're unable to find what you're looking for in this article or you want to provide
feedback, you can post questions to Azure Developer CLI Discussions .

You can also report bugs by opening GitHub Issues in the Azure Developer CLI GitHub
repository .

Using the --debug switch

If you encounter an unexpected issue while working with azd , rerun the command with
the --debug switch to enable additional debugging and diagnostic output.

Bash

azd up --debug

You can also send the debugging output to a local text file for improved usability. This
approach allows the debugging info to be ingested by other monitoring systems and
can also be useful when filing an issue on GitHub.

） Important

Make sure to redact any sensitive information when submitting debug logs on
GitHub or saving them to other diagnostics systems.

Bash

azd deploy --debug > "<your-file-path>.txt"

The .azure directory

Azure Developer CLI assumes that any directories that are stored in the .azure directory
are Azure Developer CLI environments. Don't run Azure Developer CLI commands from
the home directory of a user that has the Azure CLI installed.

Not logged in to Azure or token expired in

Visual Studio
After you've run azd init -t <template-name> in Visual Studio, you get the following
error: "To access remote: this repository, you must reauthorize the OAuth Application
Visual Studio ."

Solution
Run azd auth login to refresh the access token.

Updated Azure account permissions do not

refresh in azd
By default, azd caches your Azure credentials and permissions. If your Azure account is
assigned new roles and permissions, or is added to additional subscriptions, these
changes may not be immediately reflected in azd . To solve this issue, log out and then
log back in to azd using the following commands:

Bash

azd auth logout

azd auth login

Follow the prompts from the azd auth login command to complete the sign-in process
and update your cached credentials.

Cloud Shell limitations for azd

There are some limitations to running azd in Cloud Shell:

Docker support in Cloud Shell

Cloud Shell does not support running docker build or run commands because the
docker daemon is not running. For more information, see Cloud Shell Troubleshooting.

Cloud Shell timeout

Cloud Shell may time out during a long deployment or other long-running tasks. Make
sure the session does not become idle. See Cloud Shell Usage limits.

Cloud Shell interface

Cloud Shell is primarily a command-line interface and will have fewer features than an
integrated development environment like Visual Studio Code.

Cannot connect to the Docker daemon in Cloud Shell

Cloud Shell uses a container to host your shell environment, so tasks that require
running the Docker daemon aren't allowed.

Install different version of azd in Cloud Shell

In some cases it may be necessary to install a different version of azd than the version
already in use in Cloud Shell. To do this in bash:

1. Run mkdir -p ~/bin to ensure that the ~/bin folder is present

2. Run mkdir -p ~/azd to ensure that a local ~/azd folder is present
3. Run curl -fsSL https://aka.ms/install-azd.sh | bash -s -- --install-folder
~/azd --symlink-folder ~/bin --version <version> ( <version> would be stable

by default but a specific released version like 1.0.0 can also be specified).

Once installed, the version of azd symbolically linked in ~/bin will take precedence over
the version of azd symbolically linked in /usr/local/bin .

To revert to using the version of azd already installed on Cloud Shell in bash:

1. Run rm ~/bin/azd
2. Run rm -rf ~/azd

Solution
Use another host to perform tasks that require the docker daemon. One option is to use
docker-machine, as described in the Cloud Shell troubleshooting documentation.

Azure Bicep CLI requirement

azd up and azd provision require the latest release of Azure Bicep CLI. You might get

the following error message: "Error: failed to compile bicep template: failed running Az
PowerShell module bicep build: exit code: 1, stdout: , stderr: WARNING: A new Bicep
release is available: v0.4.1272."

Solution
Previously, Bicep was a preqrequisite for installing and using azd . azd now
automatically installs Bicep within the local azd scope (not globally) and this issue
should now be resolved. However, if you want to use a different version, you can set the
environment variable: AZD_BICEP_TOOL_PATH to point to the location of the version you
need.

azd up or azd provision fails

Things can sometimes go awry with azd up or azd provision . Common errors include:

"Can't provision certain resources in an Azure region because the region is out of
capacity."
"Relevant resource provider isn't present in that region."

The troubleshooting steps might differ, depending on the root cause.

Solution
1. Go to the Azure portal .

2. Locate your resource group, which is rg-<your-environment-name>.

3. Select Deployments to get more information.

4. Verify that you've specified an environment name that's the same as your
environment name.

5. Go to https://github.com/<your repo>/actions , and then refer to the log file in the

pipeline run for more information.
For other resources, see Troubleshoot common Azure deployment errors - Azure
Resource Manager.

azd init requires sudo

Before azd version = azure-dev-cli_0.2.0-beta.1 , azd would create an .azd folder
with drw-r--r-- access.

This will cause an issue, as using this or any prior version on any Linux set-up (WSL, ssh-
remote, devcontainer, etc.) already provides an .azd folder with read-only mode.

Solution
1. Manually delete the already provided .azd folder:

Bash

rm -r ~/.azd

2. Run azd init for azd to create the folder again with the right access levels.

azd monitor for development container

azd monitor is currently not supported if you use a development container as your

development environment.

Unable to authenticate in Codespaces

environments
If you are experiencing authentication issues in Codespaces, make sure the template
Dockerfile includes the sudo apt-get update && sudo apt-get install xdg-utils
commands. The xdg-utils command will open a browser tab that allows you to sign-in.

Static Web Apps fail to deploy despite success

message
A known issue exists when deploying to Azure Static Web Apps in which the default azd
up output may state the action was successful, but the changes were not actually
deployed. You can diagnose this problem by running the azd up command with the --
debug flag enabled. In the output logs you may see the following message:

Bash

Preparing deployment. Please wait...

An unknown exception has occurred

You are most likely to encounter this issue when azd is run from a GitHub action. As a
workaround, after you build your site, copy staticwebapp.config.json into the build
folder. You can automate this step this by using a prepackage or predeploy command
hook, which allows you to execute custom scripts at various points in the azd command
workflows.

The product team is working to resolve this issue.

GitHub Actions error - "Does not have secrets

get permission on key vault"
Sharing the same environment or resource group name when provisioning resources
locally and in GitHub Actions can produce the error Does not have secrets get
permission on key vault.. from the Key Vault service. Key Vault does not support

incremental permissions updates through Bicep, which effectively means the GitHub
Actions workflow overwrites the Access Policy permissions of the local user.

The recommended solution to this issue is to use separate environment names for local
development and GitHub Actions workflows. Read more about using multiple
environments with the azd env command on the FAQ page.

Text-based browser support

Text-based browsers are currently not supported by azd monitor .

azd pipeline config using AzDo for Java

templates on Windows
You may encounter a failure when running azd pipeline config with AzDo for Java
templates on Windows. For example, you've:

1. Run the following on Windows:

 Azure Developer CLI

azd init --template Azure-Samples/todo-java-mongo

azd pipeline config

2. Received the following error:

Solution
This is a known issue. While we address this issue, try the following command:

Bash

git update-index --chmod=+x src/api/mvnw && git commit -m "Fix executable

bit permissions" && git push

failed packaging service 'api': failed

invoking action 'package', failed to run NPM
script build, signal: segmentation fault
failure after upgrading azd on Apple Silicon
(M1/M2)
In some situations, upgrading from the x86_64 version of azd to an ARM64 binary may
result in failures for templates which have been built with the x86_64 version of azd .
This is because the template uses a version of v8-compile-cache which may try to load
bytecode built under x86_64 into an ARM64 process.

To fix this issue, upgrade the v8-compile-cache package in the affected project:
 1. Change directory to the service which failed ( src/api in the case of failed
packaging service 'api' )

2. Run npm upgrade v8-compile-cache

3. Change directory to the root of the repo and run the azd command (e.g. azd
package or azd up ) again

azd pipeline config failure due to Conditional

Access Policy
When running azd pipeline config , you may receive an error like the following:

Azure Developer CLI

ERROR: failed to create or update service principal: failed retrieving

application list, failed executing request: http
call(https://login.microsoftonline.com/common/oauth2/v2.0/token)(POST)
error: reply status code was 400:
{"error":"invalid_grant","error_description":"AADSTS50005: User tried to log
in to a device from a platform (Unknown) that's currently not supported
through Conditional Access policy. Supported device platforms are: iOS,
Android, Mac, and Windows flavors.\r\nTrace ID: be3438c1-42fc-4c37-96d8-
0e723ac54f01\r\nCorrelation ID: f535565f-9f3c-4014-ad65-
403f514bf892\r\nTimestamp: 2022-12-16 21:10:37Z","error_codes":
[50005],"timestamp":"2022-12-16 21:10:37Z","trace_id":"be3438c1-42fc-4c37-
96d8-0e723ac54f01","correlation_id":"f535565f-9f3c-4014-ad65-403f514bf892"}

This error is related to your Microsoft Entra tenant enablement of Conditional Access
Policies. The specific policy requires that you are signed in into a supported device
platform.

You may also be receiving this error due to being logged in using the device code
mechanism, which prevents Microsoft Entra ID from detecting your device platform
correctly.

Solution
To configure the workflow, you need to give GitHub permission to deploy to Azure on
your behalf. Authorize GitHub by creating an Azure Service Principal stored in a GitHub
secret named AZURE_CREDENTIALS . Select your Codespace host for steps:

Browser
 1. Make sure you're running on a device listed as supported, per the error
message.

2. Rerun azd auth login with the flag --use-device-code=false appended:

Azure Developer CLI

azd auth login --use-device-code=false

3. You may receive an error with message localhost refused to connect after
logging in. If so:
a. Copy the URL.
b. Run curl '<pasted url>' (URL in quotes) in a new Codespaces terminal.

In the original terminal, the login should now succeed.

4. After logging in, rerun azd pipeline config .

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Troubleshoot PowerShell issues with
Azure Developer CLI templates
Article • 02/26/2025

Azure Developer CLI ( azd ) templates often use hooks to execute custom scripts before
and after azd lifecycle events, such as provisioning and deployment. Users can choose
between Bash or PowerShell to write these custom scripts, depending on their
preference and the environment they're working in. If you plan to use templates that
rely on PowerShell to execute scripts, make sure you have PowerShell 7.4 or higher
installed to avoid potential errors.

PowerShell considerations
If a template relies on PowerShell to execute hook scripts, you'll encounter an error
when running commands like azd up if PowerShell version 7.x isn't installed. The Azure
Developer CLI ( azd ) doesn't check for PowerShell installation before running commands;
it only checks when executing a PowerShell hook script.

To avoid these errors:

Ensure PowerShell version 7.x is installed on your system

Verify whether the template relies on hook scripts before running azd commands.

Check your installed version of PowerShell

When you open PowerShell, it should print out the current version by default. You can
also manually check the installed version of PowerShell in any terminal window by
running the following command:

Bash

pwsh --version

Check if PowerShell is a dependency

Before running commands like azd up , users should verify if their template includes
PowerShell scripts by checking the hooks section of the azure.yaml file, which defines
custom scripts to run at various stages of the workflow.
Consider the following azure.yaml file that includes hooks:

YAML

name: my-azure-project
services:
- name: my-service
hooks:
postprovision:
windows:
shell: pwsh
run: ./scripts/prepdocs.ps1

For the postprovision hook, note that PowerShell is specified as the shell environment
for the prepdocs.ps1 script. This template would encounter an error during command
workflows such as azd up or azd provision if PowerShell 7.x isn't installed on the
device. When you see these types of PowerShell configurations in a template
azure.yaml file, verify that PowerShell is installed on your device before running the

template.

PowerShell version differences

There are a number of differences between PowerShell 7.x and PowerShell 5.1 that are
worth exploring, including the following:

PowerShell 7 is cross-platform (Windows, macOS, Linux), while PowerShell 5 is

Windows-only.
PowerShell 7 is built on .NET Core, whereas PowerShell 5 is built on .NET
Framework.
PowerShell 7 offers improved performance and faster startup.
PowerShell 7 includes new cmdlets, modules, operators, and other features.
PowerShell 7 is actively developed with regular updates, while PowerShell 5
receives only security updates and bug fixes.

Next steps
Customize your Azure Developer CLI workflows using command event hooks

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Azure Developer CLI FAQ
FAQ

This article answers commonly asked questions about Azure Developer CLI.

General
How do I uninstall Azure Developer CLI?
There are different options for uninstalling azd depending on how you originally installed it.
Visit the installation page for details.

What's the difference between the Azure Developer

CLI and the Azure CLI?
Azure Developer CLI ( azd ) and Azure CLI ( az ) are both command-line tools, but they help you
do different tasks.

azd focuses on the high level developer workflow. Apart from provisioning/managing Azure
resources, azd helps to stitch cloud components, local development configuration, and
pipeline automation together into a complete solution.

Azure CLI is a control plane tool for creating and administering Azure infrastructure such as
virtual machines, virtual networks, and storage. The Azure CLI is designed around granular
commands for specific administrative tasks.

What is an environment name?

Azure Developer CLI uses an environment name to set the AZURE_ENV_NAME environment
variable that's used by Azure Developer CLI templates. AZURE_ENV_NAME is also used to
prefix the Azure resource group name. Because each environment has its own set of
configurations, Azure Developer CLI stores all configuration files in environment directories.

txt

├── .Azure [This directory displays after you run add

init or azd up]
│ ├── <your environment1> [A directory to store all environment-related
configurations]
│ │ ├── .env [Contains environment variables]
│ │ └── main.parameters.json [A parameter file]
│ └── <your environment2> [A directory to store all environment-related
 configurations]
│ │ ├── .env [Contains environment variables]
│ │ └── main.parameters.json [A parameter file]
│ └──config.json

Can I set up more than one environment?

Yes. You can set up a various environments (for example, dev, test, production). You can use
azd env to manage these environments.

Where is the environment configuration (.env) file

stored?
The .env file path is <your-project-directory-name>\.azure\<your-environment-name>\.env .

How is the .env file used?

In Azure Developer CLI, the azd commands refer to the .env file for environment configuration.
Commands such as azd deploy also update the .env file with, for example, the db connection
string and the Azure Key Vault endpoint.

I have run `azd up` in Codespaces. Can I continue my

work in a local development environment?
Yes. You can continue development work locally.

1. Run azd init -t <template repo> to clone the template project to your local machine.
2. To pull down the existing env created using Codespaces, run azd env refresh . Make sure
you provide the same environment name, subscription and location as before.

How is the azure.yaml file used?

The azure.yaml file describes the apps and types of Azure resources that are included in the
template.

What is the behavior of the

`secretOrRandomPassword` function?
The secretOrRandomPassword function retrieves a secret from Azure Key Vault if parameters for
the key vault name and secret are provided. If these parameters aren't provided or a secret
can't be retrieved, the function returns a randomly generated password to use instead.

The following example demonstrates a common use case of the secretOrRandomPassword in a

main.parameters.json file. The ${AZURE_KEY_VAULT_NAME} and sqlAdminPassword variables are

passed as parameters for the names of the Key Vault and secret. If the value can't be retrieved,
a random password is generated instead.

JSON

"sqlAdminPassword": {
"value": "$(secretOrRandomPassword ${AZURE_KEY_VAULT_NAME} sqlAdminPassword)"
}

The output of secretOrRandomPassword should also be saved to Key Vault using Bicep for future
runs. Retrieving and reusing the same secrets across deploys can prevent errors or unintended
behaviors that can surface when repeatedly generating new values. To create a Key Vault and
store the generated secret in it, use the Bicep code below. You can view the full sample code
for these modules in the Azure Developer CLI GitHub repository .

JSON

module keyVault './core/security/keyvault.bicep' = {

name: 'keyvault'
scope: resourceGroup
params: {
name: '${take(prefix, 17)}-vault'
location: location
tags: tags
principalId: principalId
}
}

module keyVaultSecrets './core/security/keyvault-secret.bicep' = {

name: 'keyvault-secret-sqlAdminPassword'
scope: resourceGroup
params: {
keyVaultName: keyVault.outputs.name
name: 'sqlAdminPassword'
secretValue: sqlAdminPassword
}
}]

This Bicep setup enables the following workflow for managing your secrets:

1. If the specified secret exists, it's retrieved from Key Vault using the
secretOrRandomPassword function.
 2. If the secret doesn't exist, a Key Vault is created, and the randomly generated secret is
stored inside of it.
3. On future deploys, the secretOrRandomPassword method retrieves the stored secret now
that it exists in Key Vault. The Key Vault won't be recreated if it already exists, but the
same secret value will be stored again for the next run.

Can I use Azure Free Subscription?

Yes, but each Azure location can only have one deployment. If you've already used the selected
Azure location, you'll see the deployment error:

InvalidTemplateDeployment: The template deployment '<env_name>' isn't valid

according to the validation procedure. The tracking ID is '<tracking_id>'. See
inner errors for details.

You can select a different Azure location to fix the issue.

My app hosted with Azure App Service is triggering

a "Deceptive site ahead" warning. How can I fix it?
This might happen because of our method for naming resources.

Our 'Azure Dev' authored templates allow for configuring the name of the resource. To do so,
you can add an entry to the main.parameters.json in the infra folder. For example:

JSON

"webServiceName": {
"value": "my-unique-name"
}

This entry creates a new resource named "my-unique-name" instead of a randomized value
such as "app-web-aj84u2adj" the next time you provision your application. You can either
manually remove the old resource group using the Azure portal or run azd down to remove all
previous deployments. After removing the resources, run azd provision to create them again
with the new name.

This name will need to be globally unique, otherwise you will receive an ARM error during azd
provision when it tries to create the resource.
Command: azd provision
How does the command know what resources to
provision?
The command uses Bicep templates, which are found under <your-project-directory-
name>/infra to provision Azure resources.

Where can I find what resources are provisioned in

Azure?
Go to https://portal.azure.com and then look for your resource group, which is rg-<your-
environment-name> .

How do I find more information about Azure errors?

We use Bicep templates, which are found under <your-project-directory-name>/infra , to
provision Azure resources. If there are issues, we include the error message in the CLI output.

You can also go to https://portal.azure.com and then look for your resource group, which is
rg-<your-environment-name> . If any of the deployments fail, select the error link to get more

information.

For other resources, see Troubleshoot common Azure deployment errors - Azure Resource
Manager.

Is there a log file for `azd provision`?

Coming soon. This feature is planned for a future release.

Command: azd deploy

Can I rerun this command?
Yes.

How does azd find the Azure resource to deploy my

code to?
During deploy, azd first discovers all the resource groups that make up your application by
looking for groups tagged with azd-env-name and with a value that matches the name of your
environment. Then, it enumerates all the resources in each of these resource groups, looking
for a resource tagged with azd-service-name with a value that matches the name of your
service from azure.yaml .

While we recommend using tags on resources, you can also use the resourceName property in
azure.yaml to provide an explicit resource name. In that case, the above logic isn't run.

How do I deploy specific services in my project while

skipping others?
When deploying your project, you can choose to deploy specific services either by specifying
the service name in the command (i.e. azd deploy api ) or by navigating to a subfolder that
contains just the service(s) you want to deploy. When doing so, all other services will be listed
as - Skipped .

If you don't want to skip any services, be sure to either run your command from the root folder
or add the --all flag to your command.

Command: azd up
Can I rerun `azd up`?
Yes. We use the incremental deployment mode.

How do I find the log file for `azd up`?

Coming soon. This feature is planned for a future release.

Command: azd pipeline

What is an Azure service principal?
An Azure service principal is an identity that's created for use with apps, hosted services, and
automated tools to access Azure resources. This access is restricted by the roles that are
assigned to the service principal, which gives you control over which resources can be accessed
and at which level. For more information about authenticating from Azure to GitHub, see
Connect GitHub and Azure | Microsoft Docs.
Do I need to create an Azure service principal before
I run `azd pipeline config`?
No. The azd pipeline config command takes care of creating the Azure service principal and
performing the necessary steps to store the secrets in your GitHub repo.

What are all the secrets stored in GitHub?

The command stores four secrets in GitHub: AZURE_CREDENTIALS, AZURE_ENV_NAME,
AZURE_LOCATION, and AZURE_SUBSCRIPTION_ID. You can override the value of each secret by
going to https://github.com/<your-github-account>/<your-repo>/secrets/actions .

What is OpenID Connect (OIDC), and is it

supported?
With OpenID Connect , your workflows can exchange short-lived tokens directly from Azure.

While OIDC is supported as the default for GitHub Actions and Azure Pipeline (set as
federated), it isn't supported for Azure DevOps or Terraform.

For Azure DevOps, explicitly calling out --auth-type as federated will result in an error.
For Terraform:
If --auth-type isn't defined, it will fall back to clientcredentials and will result in a
warning.
If --auth-type is explicitly set to federated , it will result in an error.

How do I reset the Azure service principal that's

stored in GitHub Actions?
Go to https://github.com/<your-github-account>/<your-repo>settings/secrets/actions , and
then update AZURE_CREDENTIALS by copying and pasting the entire JSON object for the new
service principal. For example:

{
"clientId": "<GUID>",
"clientSecret": "<GUID>",
"subscriptionId": "<GUID>",
"tenantId": "<GUID>",
 (...)
}

Where is the GitHub Actions file stored?

The GitHub Actions file path is <your-project-directory-name>\.github\workflows\azure-
dev.yml .

In the azure-dev.yml file, can I deploy just the code

in the build step?
Yes. Replace run: azd up --no-prompt with run: azd deploy --no-prompt .

Where can I find the log for the GitHub Actions job
that I triggered when I ran `azd pipeline config`?
Go to https://github.com/<your-github-account>/<your-repo>/actions , and then refer to the
log file in the workflow run.

Building a container application locally

Why am I unable to locally run the container app
that I'm building?
When building container applications locally, you need to run azd auth login in the container
for the application to work with the AzureDeveloperCliCredential . Alternatively, you could
configure your application to use a service principal instead of the
AzureDeveloperCliCredential .
Azure Developer CLI's azure.yaml
schema
Article • 01/31/2025

azd templates are blueprint repositories that include proof-of-concept application code,
editor/IDE configurations, and infrastructure code written in Bicep or Terraform. These
templates are intended to be modified and adapted for your specific application
requirements and then used to get your application on Azure using the Azure Developer
CLI ( azd ). The azure.yaml schema defines and describes the apps and types of Azure
resources that are included in these templates.

Sample
Below is a generic example of an azure.yaml required for your azd template.

YAML

name: yourApp
metadata:
template: yourApp@0.0.1-beta
services:
web:
project: ./src/web # path to your web project
dist: build # relative path to service deployment artifacts
language: js # one of the supported languages
host: appservice # one of the supported Azure services

Compare with the azure.yaml from our ToDo NodeJs Mongo template :

YAML

name: todo-nodejs-mongo
metadata:
template: todo-nodejs-mongo@0.0.1-beta
services:
web:
project: ./src/web
dist: build
language: js
host: appservice
api:
project: ./src/api
language: js
host: appservice
Property descriptions
ﾉ Expand table

Element Name Required Description

name Y (string) Name of the application.

resourceGroup N (string) Name of the Azure resource group. When specified, will
override the resource group name used for infrastructure
provisioning.

metadata N (object) See metadata properties for more details.

infra N (object) Provides extra configuration for Azure infrastructure

provisioning. See infra properties for more details.

services Y (object) Definition of services that comprise the application. See

services properties for more details.

pipeline N (object) Definition of continuous integration pipeline. See pipeline

properties for more details.

hooks N Command level hooks. Hooks should match azd command

names prefixed with pre or post depending on when the script
should execute. When specifying paths they should be relative to
the project path. See Customize your Azure Developer CLI
workflows using command and event hooks for more details.

requiredVersions N A range of supported versions of azd for this project. If the

version of azd is outside this range, the project will fail to load.
Optional (allows all versions if absent). Example: >= 0.6.0-beta.3

metadata properties

ﾉ Expand table

Element Required Description Example

Name

template N (string) Identifier of the template from which todo-nodejs-

the application was created. mongo@0.0.1-beta

infra properties
 ﾉ Expand table

Element Required Description Example

Name

provider N (string) The infrastructure provider for the See the Terraform
application's Azure resources. (Default: bicep). sample below. bicep ,
terraform

path N (string) The relative folder path to the location

containing Azure provisioning templates for
the specified provider. (Default: infra).

module N (string) The name of the default module

withing the Azure provisioning templates.
(Default: main).

Terraform as IaC provider sample

YAML

name: yourApp-terraform
metadata:
template: yourApp-terraform@0.0.1-beta
services:
web:
project: ./src/web
dist: build
language: js
host: appservice
api:
project: ./src/api
language: js
host: appservice
infra:
provider: terraform

services properties

ﾉ Expand table

Element Required Description Example

Name

resourceName N (string) Name of the Azure prodapi

resource that implements
the service. If not specified,
azd will look for a resource
Element Required Description Example
Name

by azd-env-name and azd-

service-name tags. If not
found, it will look for a
resource name constructed
from the current
environment name,
concatenated with the
service name ( <environment-
name><resource-name> ).

project Y (string) Path to the service

source code directory.

host Y (string) Type of Azure appservice , containerapp , function ,

resource used for service staticwebapp , aks (only for projects
implementation. If omitted, deployable via kubectl apply -f ),
App Service will be assumed. springapp (when enabled - learn
more about alpha features)

language Y (string) Service dotnet , csharp , fsharp , py , python ,

implementation language. js , ts , java

module Y (string) Path of the

infrastructure module used
to deploy the service relative
to the root infra folder. If
omitted, the CLI will assume
the module name is the
same as the service name.

dist Y (string) Relative path to the build

service deployment artifacts.
The CLI will use files under
this path to create the
deployment artifact (.zip
file). If omitted, all files under
the service project directory
will be included.

docker N Only applicable when host See the custom Docker sample below.
is containerapp . Can't path (string): Path to the Dockerfile.
contain extra properties. Default: ./Dockerfile ; context
(string): The docker build context.
When specified, overrides default
context. Default: . ; platform (string):
The platform target. Default: amd64 ;
Element Required Description Example
Name

remoteBuild (boolean): Enables

remote ACR builds. Default: false

k8s N The Azure Kubernetes See the AKS sample below.

Service (AKS) configuration deploymentPath (string): Optional. The
options. relative path from the service path to
the k8s deployment manifests. When
set, it will override the default
deployment path location for k8s
deployment manifests. Default:
manifests ; namespace (string):
Optional. The k8s namespace of the
deployed resources. When specified,
a new k8s namespace will be created
if it does not already exist. Default:
Project name ; deployment (object):
See deployment properties; service
(object): See service properties;
ingress (object): See ingress
properties.

hooks N Service level hooks. Hooks See Customize your Azure Developer
should match service event CLI workflows using command and
names prefixed with pre or event hooks for more details.
post depending on when
the script should execute.
When specifying paths they
should be relative to the
service path.

apiVersion N Specify an explicit api- apiVersion: 2024-02-02-preview

version when deploying
services hosted by Azure
Container Apps (ACA). This
feature helps you avoid
using an incompatible API
version and makes
deployment more loosely
coupled to avoid losing
custom configuration data
during JSON marshaling to a
hard-coded Azure SDK
library version.

Docker options sample

In the following example, we declare Docker options for a container app.

YAML

name: yourApp-aca
metadata:
template: yourApp-aca@0.0.1-beta
services:
api:
project: ./src/api
language: js
host: containerapp
docker:
path: ./Dockerfile
context: ../
web:
project: ./src/web
language: js
host: containerapp
docker:
remoteBuild: true

AKS deployment properties

ﾉ Expand table

Element Required Description Example

Name

name N (string) Optional. The name of the k8s deployment resource api
to use during deployment. Used during deployment to
ensure if the k8s deployment rollout has been completed. If
not set, will search for a deployment resource in the same
namespace that contains the service name. Default: Service
name

AKS service properties

ﾉ Expand table

Element Required Description Example

Name

name N (string) Optional. The name of the k8s service resource to use api
as the default service endpoint. Used when determining
endpoints for the default service resource. If not set, will
Element Required Description Example
Name

search for a deployment resource in the same namespace

that contains the service name. (Default: Service name)

AKS ingress properties

ﾉ Expand table

Element Required Description Example

Name

name N (string) Optional. The name of the k8s ingress resource to api
use as the default service endpoint. Used when
determining endpoints for the default ingress resource. If
not set, will search for a deployment resource in the same
namespace that contains the service name. Default:
Service name

relativePath N (string) Optional. The relative path to the service from the
root of your ingress controller. When set, will be
appended to the root of your ingress resource path.

AKS sample with service level hooks

YAML

metadata:
template: todo-nodejs-mongo-aks@0.0.1-beta
services:
web:
project: ./src/web
dist: build
language: js
host: aks
hooks:
postdeploy:
shell: sh
run: azd env set REACT_APP_WEB_BASE_URL ${SERVICE_WEB_ENDPOINT_URL}
api:
project: ./src/api
language: js
host: aks
k8s:
ingress:
relativePath: api
hooks:
postdeploy:
 shell: sh
run: azd env set REACT_APP_API_BASE_URL ${SERVICE_API_ENDPOINT_URL}

pipeline properties

ﾉ Expand table

Element Required Description Example

Name

provider N (string) The pipeline provider to be used for continuous github ,

integration. (Default: github ). azdo

Azure Pipelines (AzDo) as a CI/CD pipeline sample

YAML

name: yourApp
services:
web:
project: src/web
dist: build
language: js
host: appservice
pipeline:
provider: azdo

workflows properties

ﾉ Expand table

Element Type Required Description

Name

up object No When specified will override the default behavior for the azd
up workflow.

up properties

ﾉ Expand table
 Element Name Type Required Description

steps array Yes The steps to execute in the workflow.

steps properties

ﾉ Expand table

Element Name Type Required Description

azd string Yes The name and args of the azd command to execute.

Sample workflow
The following azure.yaml file changes the default behavior of azd up to move the azd
package step after the azd provision step using a workflow. This example could be used

in scenarios where you need to know the URLs of resources during the build or
packaging process.

yml

name: todo-nodejs-mongo
metadata:
template: todo-nodejs-mongo@0.0.1-beta
workflows:
up:
steps:
- azd: provision
- azd: deploy --all

Request help
For information on how to file a bug, request help, or propose a new feature for the
Azure Developer CLI, please visit the troubleshooting and support page.

Next steps
Learn more about Azure Developer CLI
Get started with azd init and azd up
Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A

Azure Developer CLI reference
Article • 04/15/2025

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
application on Azure

Options
Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--docs Opens the documentation for azd in your web browser.
-h, --help Gets help for azd.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd add: Add a component to your project. (Alpha)
azd auth: Authenticate with Azure.
azd config: Manage azd configurations (ex: default Azure subscription, location).
azd deploy: Deploy the application's code to Azure.
azd down: Delete Azure resources for an application.
azd env: Manage environments.
azd hooks: Develop, test and run hooks for an application. (Beta)
azd infra: Manage your Azure infrastructure.
azd init: Initialize a new application.
azd monitor: Monitor a deployed application. (Beta)
azd package: Packages the application's code to be deployed to Azure. (Beta)
azd pipeline: Manage and configure your deployment pipelines. (Beta)
azd provision: Provision the Azure resources for an application.
azd restore: Restores the application's dependencies. (Beta)
azd show: Display information about your app and its resources.
azd template: Find and view template details. (Beta)
azd up: Provision Azure resources, and deploy your project with a single command.
azd version: Print the version number of Azure Developer CLI.
azd add
Add a component to your project. (Alpha)

Azure Developer CLI

azd add [flags]

Options
Azure Developer CLI

--docs Opens the documentation for azd add in your web browser.
-h, --help Gets help for add.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
Back to top

azd auth
Authenticate with Azure.

Options
Azure Developer CLI

--docs Opens the documentation for azd auth in your web browser.
-h, --help Gets help for auth.

Options inherited from parent commands

 Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd auth login: Log in to Azure.
azd auth logout: Log out of Azure.
Back to top

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.

Azure Developer CLI

azd auth login [flags]

Options
Azure Developer CLI

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

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd auth: Authenticate with Azure.
Back to top

azd auth logout

Log out of Azure.

Synopsis
Log out of Azure

Azure Developer CLI

 azd auth logout [flags]

Options
Azure Developer CLI

--docs Opens the documentation for azd auth logout in your web browser.
-h, --help Gets help for logout.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd auth: Authenticate with Azure.
Back to top

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
Azure Developer CLI

--docs Opens the documentation for azd config in your web browser.
-h, --help Gets help for config.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd config get: Gets a configuration.
azd config list-alpha: Display the list of available features in alpha stage.
azd config reset: Resets configuration to default.
azd config set: Sets a configuration.
azd config show: Show all the configuration values.
azd config unset: Unsets a configuration.
Back to top

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.

Azure Developer CLI

azd config get <path> [flags]

Options
Azure Developer CLI

--docs Opens the documentation for azd config get in your web browser.
-h, --help Gets help for get.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd config: Manage azd configurations (ex: default Azure subscription, location).
Back to top

azd config list-alpha

Display the list of available features in alpha stage.

Azure Developer CLI

azd config list-alpha [flags]

Options
 Azure Developer CLI

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

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd config: Manage azd configurations (ex: default Azure subscription, location).
Back to top

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.

Azure Developer CLI

azd config reset [flags]

Options
 Azure Developer CLI

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

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd config: Manage azd configurations (ex: default Azure subscription, location).
Back to top

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.

Azure Developer CLI

azd config set <path> <value> [flags]

Examples
 Azure Developer CLI

azd config set defaults.subscription <yourSubscriptionID>

azd config set defaults.location eastus

Options
Azure Developer CLI

--docs Opens the documentation for azd config set in your web browser.
-h, --help Gets help for set.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd config: Manage azd configurations (ex: default Azure subscription, location).
Back to top

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.
 Azure Developer CLI

azd config show [flags]

Options
Azure Developer CLI

--docs Opens the documentation for azd config show in your web browser.
-h, --help Gets help for show.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd config: Manage azd configurations (ex: default Azure subscription, location).
Back to top

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.
 Azure Developer CLI

azd config unset <path> [flags]

Examples
Azure Developer CLI

azd config unset defaults.location

Options
Azure Developer CLI

--docs Opens the documentation for azd config unset in your web browser.
-h, --help Gets help for unset.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd config: Manage azd configurations (ex: default Azure subscription, location).
Back to top

azd deploy
Deploy the application's code to Azure.

Azure Developer CLI

azd deploy <service> [flags]

Options
Azure Developer CLI

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

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
Back to top

azd down
Delete Azure resources for an application.

Azure Developer CLI

azd down [flags]

Options
Azure Developer CLI

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

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
Back to top

azd env
Manage environments.

Options
Azure Developer CLI

--docs Opens the documentation for azd env in your web browser.
-h, --help Gets help for env.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd env get-value: Get specific environment value.
azd env get-values: Get all environment values.
 azd env list: List environments.
azd env new: Create a new environment and set it as the default.
azd env refresh: Refresh environment settings by using information from a previous
infrastructure provision.
azd env select: Set the default environment.
azd env set: Manage your environment settings.
azd env set-secret: Set a <name> as a reference to a Key Vault secret in the environment.
Back to top

azd env get-value

Get specific environment value.

Azure Developer CLI

azd env get-value <keyName> [flags]

Options
Azure Developer CLI

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

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd env: Manage environments.
Back to top
azd env get-values
Get all environment values.

Azure Developer CLI

azd env get-values [flags]

Options
Azure Developer CLI

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

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd env: Manage environments.
Back to top

azd env list

List environments.

Azure Developer CLI

azd env list [flags]

Options
 Azure Developer CLI

--docs Opens the documentation for azd env list in your web browser.
-h, --help Gets help for list.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd env: Manage environments.
Back to top

azd env new

Create a new environment and set it as the default.

Azure Developer CLI

azd env new <environment> [flags]

Options
Azure Developer CLI

--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 Name or ID of an Azure subscription to use for the
new environment

Options inherited from parent commands

Azure Developer CLI
 -C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd env: Manage environments.
Back to top

azd env refresh

Refresh environment settings by using information from a previous infrastructure provision.

Azure Developer CLI

azd env refresh <environment> [flags]

Options
Azure Developer CLI

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

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd env: Manage environments.
Back to top
azd env select
Set the default environment.

Azure Developer CLI

azd env select <environment> [flags]

Options
Azure Developer CLI

--docs Opens the documentation for azd env select in your web browser.
-h, --help Gets help for select.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd env: Manage environments.
Back to top

azd env set

Manage your environment settings.

Azure Developer CLI

azd env set <key> <value> [flags]

Options
Azure Developer CLI
 --docs Opens the documentation for azd env 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

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd env: Manage environments.
Back to top

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.

Azure Developer CLI

azd env set-secret <name> [flags]

Options
Azure Developer CLI

--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
Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd env: Manage environments.
Back to top

azd hooks
Develop, test and run hooks for an application. (Beta)

Options
Azure Developer CLI

--docs Opens the documentation for azd hooks in your web browser.
-h, --help Gets help for hooks.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd hooks run: Runs the specified hook for the project and services
Back to top

azd hooks run

Runs the specified hook for the project and services

Azure Developer CLI

azd hooks run <name> [flags]

Options
Azure Developer CLI

--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.
--platform string Forces hooks to run for the specified platform.
--service string Only runs hooks for the specified service.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd hooks: Develop, test and run hooks for an application. (Beta)
Back to top

azd infra
Manage your Azure infrastructure.

Options
Azure Developer CLI

--docs Opens the documentation for azd infra in your web browser.
-h, --help Gets help for infra.
Options inherited from parent commands
Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd infra synth: Write IaC for your project to disk, allowing you to manage it by hand.
(Alpha)
Back to top

azd infra synth

Write IaC for your project to disk, allowing you to manage it by hand. (Alpha)

Azure Developer CLI

azd infra synth [flags]

Options
Azure Developer CLI

--docs Opens the documentation for azd infra synth 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 synth.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.
See also
azd infra: Manage your Azure infrastructure.
Back to top

azd init
Initialize a new application.

Azure Developer CLI

azd init [flags]

Options
Azure Developer CLI

-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
-s, --subscription string Name or ID of an Azure subscription to use for the
new environment
-t, --template string Initializes a new application from a template. You
can use Full URI, <owner>/<repository>, or <repository> if it's part of the azure-
samples organization.
--up Provision and deploy to Azure after initializing the
project from a template.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.
See also
Back to top

azd monitor
Monitor a deployed application. (Beta)

Azure Developer CLI

azd monitor [flags]

Options
Azure Developer CLI

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

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
Back to top

azd package
Packages the application's code to be deployed to Azure. (Beta)
 Azure Developer CLI

azd package <service> [flags]

Options
Azure Developer CLI

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

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
Back to top

azd pipeline
Manage and configure your deployment pipelines. (Beta)

Options
Azure Developer CLI

--docs Opens the documentation for azd pipeline in your web browser.
-h, --help Gets help for pipeline.

Options inherited from parent commands

 Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd pipeline config: Configure your deployment pipeline to connect securely to Azure.
(Beta)
Back to top

azd pipeline config

Configure your deployment pipeline to connect securely to Azure. (Beta)

Azure Developer CLI

azd pipeline config [flags]

Options
Azure Developer CLI

-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 (Only valid for GitHub
provider). Valid values: federated, client-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

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd pipeline: Manage and configure your deployment pipelines. (Beta)
Back to top

azd provision
Provision the Azure resources for an application.

Azure Developer CLI

azd provision [flags]

Options
Azure Developer CLI

--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.
--no-state Do not use latest Deployment State (bicep only).
--preview Preview changes to Azure resources.

Options inherited from parent commands

Azure Developer CLI
 -C, --cwd string Sets the current working directory.
--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
Back to top

azd restore
Restores the application's dependencies. (Beta)

Azure Developer CLI

azd restore <service> [flags]

Options
Azure Developer CLI

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

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
Back to top
azd show
Display information about your app and its resources.

Azure Developer CLI

azd show [flags]

Options
Azure Developer CLI

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

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
Back to top

azd template
Find and view template details. (Beta)

Options
Azure Developer CLI

--docs Opens the documentation for azd template in your web browser.
-h, --help Gets help for template.
Options inherited from parent commands
Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd template list: Show list of sample azd templates. (Beta)
azd template show: Show details for a given template. (Beta)
azd template source: View and manage template sources. (Beta)
Back to top

azd template list

Show list of sample azd templates. (Beta)

Azure Developer CLI

azd template list [flags]

Options
Azure Developer CLI

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

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
 --no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd template: Find and view template details. (Beta)
Back to top

azd template show

Show details for a given template. (Beta)

Azure Developer CLI

azd template show <template> [flags]

Options
Azure Developer CLI

--docs Opens the documentation for azd template show in your web browser.
-h, --help Gets help for show.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd template: Find and view template details. (Beta)
Back to top

azd template source

View and manage template sources. (Beta)
Options
Azure Developer CLI

--docs Opens the documentation for azd template source in your web
browser.
-h, --help Gets help for source.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd template: Find and view template details. (Beta)
azd template source add: Adds an azd template source with the specified key. (Beta)
azd template source list: Lists the configured azd template sources. (Beta)
azd template source remove: Removes the specified azd template source (Beta)
Back to top

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

Azure Developer CLI

azd template source add <key> [flags]

Options
 Azure Developer CLI

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

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd template source: View and manage template sources. (Beta)
Back to top

azd template source list

Lists the configured azd template sources. (Beta)

Azure Developer CLI

azd template source list [flags]

Options
Azure Developer CLI

--docs Opens the documentation for azd template source list in your web
browser.
-h, --help Gets help for list.

Options inherited from parent commands

 Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd template source: View and manage template sources. (Beta)
Back to top

azd template source remove

Removes the specified azd template source (Beta)

Azure Developer CLI

azd template source remove <key> [flags]

Options
Azure Developer CLI

--docs Opens the documentation for azd template source remove in your web
browser.
-h, --help Gets help for remove.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
azd template source: View and manage template sources. (Beta)
Back to top
azd up
Provision Azure resources, and deploy your project with a single command.

Azure Developer CLI

azd up [flags]

Options
Azure Developer CLI

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

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
Back to top

azd version
Print the version number of Azure Developer CLI.

Azure Developer CLI

azd version [flags]

Options
 Azure Developer CLI

--docs Opens the documentation for azd version in your web browser.
-h, --help Gets help for version.

Options inherited from parent commands

Azure Developer CLI

-C, --cwd string Sets the current working directory.

--debug Enables debugging and diagnostics logging.
--no-prompt Accepts the default value instead of prompting, or it fails
if there is no default.

See also
Back to top
CDN changes for the Azure Developer
CLI installation endpoints
Article • 01/09/2025

The Content Delivery Network (CDN) endpoint used to download and install azd is
changing due to the Azure CDN from Edgio retirement effective January 15, 2025. If you
install azd using a script, it's recommended you use the latest install scripts hosted at
https://aka.ms/install-azd.ps1 and https://aka.ms/install-azd.sh . Customers who

use this approach will not be impacted by the CDN change.

７ Note

Hard coding the CDN hostname directly to reference install scripts isn't a
supported scenario. If your logic depends on the hostname, then future changes to
hostnames could result in a breaking change to your application.

Who is impacted by this change?

Your application or system may be impacted and require updates due to the CDN
change if you're using any of the following in your application:

The azure/setup-azd@1.0.0 GitHub Action (and earlier versions)

Older downloaded versions of install-azd.ps1 and install-azd.sh scripts
The latest versions are available at https://aka.ms/install-azd.ps1 and
https://aka.ms/install-azd.sh

Any hardcoded references in your system to the older CDN endpoints

Recommended actions
Complete or verify the following to ensure your system is compatible with the CDN
changes:

Ensure you're using the latest GitHub Action ( v2 ) for azure/setup-azd in your
workflows.
Ensure you're using the latest Azure DevOps task version .
Ensure any custom install scripts reference the new host name. There's no change
to file paths after the host name.
Additional information and resources
For more on this change, follow the issue in the azd repository or read the FAQs on
Microsoft Learn documentation.

If you run into any problems or have suggestions, file an issue or start a discussion in
the Azure Developer CLI repository . You can also explore the troubleshooting
documentation .

Feedback
Was this page helpful?  Yes  No

Get help at Microsoft Q&A