Explore the Azure Developer CLI initialization workflows

2025-08-13

The Azure Developer CLI (azd) provides a set of commands to streamline developing, provisioning, and deploying app on Azure. The azd init command helps you set up new or existing projects by generating the files and configurations needed to work with azd. This article explains the different initialization workflows available and how to select the best option for your development scenario.

Initialization workflows

The azd init command supports several workflows to prepare your app to work with azd:

Scan current directory: Analyzes an existing app codebase to generate appropriate azd configuration files and resources.
Select a template: Clones and initializes a template from an azd template gallery.
Create a minimal project: Initializes a basic azure.yaml file as a starting point for building your own azd template from scratch.

Choose the approach that best fits your project. All of these flows are outlined in more detail in the Create templates overview and related articles. The following sections provide a conceptual overview of each flow.

Scan current directory

Use this workflow when you have an existing app codebase and want to prepare it for deployment to Azure using azd.

Navigate to your project's root directory.
Run the azd init command:
```
azd init
```

Select Scan current directory. azd will:

Scan your directory to determine the language or framework your app uses.
Select an appropriate hosting platform, such as Azure Container Apps.
Prompt you to add or remove discovered services if needed.

? How do you want to initialize your app? Scan current directory

  (✓) Done: Scanning app code in current directory

Detected services:

  .NET
  Detected in: src

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
  Remove a detected service
  Add an undetected service

Select Confirm and continue initializing my app to complete the workflow. azd creates the following in your app directory:
- An azure.yaml file that defines your app services and maps them to hosting resources.
- A .azure folder to hold configuration settings such as your environment name.
- A .gitignore file configured for your app language and hosting platform.
Optionally, run azd up to create the Azure Container Apps resources and deploy your app.

Your app is now structured as an azd template you can continue to develop and expand with more Azure resources and services.

Select a template

This workflow lets you start with a prebuilt azd template that usually includes both application code and the necessary Azure infrastructure definitions.

Run the azd init command:
```
azd init
```
Note

You can also run azd init with the --template parameter to directly initialize a template by name and skip the workflow selection.

Choose Select a template. azd displays a list of available templates from your configured template sources.

? How do you want to initialize your app? Select a template
? Select a project template:  [Use arrows to move, type to filter]
> Deploy Phoenix to Azure
  (Arize-ai/phoenix-on-azure)

  API Center Reference Sample
  (Azure-Samples/APICenter-Reference)

  Event Driven Java Application with Azure Service Bus on Azure Spring Apps
  (Azure-Samples/ASA-Samples-Event-Driven-Application)

  Static React Web App with Java API and PostgreSQL
  (Azure-Samples/ASA-Samples-Web-Application)

Type to filter the results and search for the Hello AZD template. Press Enter to clone and initialize the template.
Optionally, run azd up to provision and deploy the template resources to Azure.

You can also use the initialized template as a starting point for further development.

Create a minimal project

For advanced users who want to start with a minimal setup and customize everything manually, this option provides just the essential configuration.

Run the azd init command with the --minimal flag:
```
azd init --minimal
```
When prompted, enter a name for your azd template and press Enter.
```
? How do you want to initialize your app? Create a minimal project
? What is the name of your project? (empty) hello-azd
? What is the name of your project? hello-azd

SUCCESS: Generated azure.yaml project file.
Run azd add to add new Azure components to your project.
```
The --minimal flag creates only the following:
- A basic azure.yaml file with just the project name and schemaVersion
- A .azure directory for environment configuration
- A .gitignore file with appropriate entries for Azure Developer CLI
This streamlined initialization is ideal when you:
- Want to build your infrastructure from scratch
- Need to integrate azd with an existing complex project
- Plan to use the azd add command to incrementally build your architecture
- Prefer full control over your project structure
After initialization, you can:
- Manually create your infrastructure files in an infra folder
- Use the azd add compose feature to start adding Azure resources to your app
- Customize your azure.yaml file to define your services and resources

Project and Azure resource naming

When you initialize a new or existing project, the project name is set in azure.yaml. The project name acts as a prefix for Azure resource names created during the provisioning process. By adhering to the validation rules, you ensure that generated Azure resource names will also be valid.

In Bicep or Terraform templates, the project name is often used as a base for constructing resource names, combined with the environment name and other elements. For example:

var resourceToken = '${name}-${environmentName}'

Where name refers to the project name and environmentName is the name of your azd environment.

Project name validation rules

When using azd init to initialize a project or when creating a new project name in the azure.yaml file, the following validation rules are applied:

Rule	Description
Allowed characters	Project names can include lowercase letters, numbers, and hyphens only.
Starting character	Project names must start with a letter.
Ending character	Project names must not end with a hyphen.
Length	Project names must be between 2 and 63 characters long.
No consecutive hyphens	Project names cannot contain consecutive hyphens.

These validation rules ensure that your project name will be compatible with the naming requirements of Azure resources and prevent service packaging failures during deployment.

Next steps

After initializing your project with azd init, you can:

Modify the generated infrastructure files to customize your Azure resources.
Use azd provision to create the required resources in Azure.
Use azd deploy to deploy your application code to the provisioned resources.
Learn about the Azure Developer CLI up workflow to combine provisioning and deployment in a single command.

Feedback

Was this page helpful?