Azure Developer CLI (azd)

The Azure Developer CLI (azd) is a developer-oriented command-line tool that can provision Azure resources and deploy applications from your local environment or CI/CD pipelines. It integrates with Aspire by consuming the deployment manifest format to understand your app model and automatically provision the corresponding Azure resources.

Recommended: aspire deploy

For new Azure deployments, we recommend using aspire deploy directly. It offers a simpler workflow, supports more Azure targets, and doesn’t require an intermediate manifest. See Deploy using the Aspire CLI.

When to use azd

While aspire deploy is the recommended path, azd remains useful in several scenarios:

• You have existing azd workflows and infrastructure templates you want to continue using.
• You need azd pipeline config for automated CI/CD setup with GitHub Actions or Azure DevOps.
• You want to use azd environment management features to manage multiple deployment environments.
• You’re working with teams already familiar with azd conventions and tooling.

Prerequisites

• Azure Developer CLI installed
• An active Azure subscription — create one for free
• Aspire CLI installed

Basic workflow

1. Initialize your project — run azd init from your AppHost directory. When prompted, select Use code in the current directory so azd detects the Aspire app model.

   Initialize azd in the AppHost directory

   azd init

2. Provision and deploy — run azd up to provision the required Azure resources and deploy your application in a single step. This combines the azd provision and azd deploy commands.

   Provision infrastructure and deploy

   azd up

3. Redeploy without reprovisioning — after the initial deployment, use azd deploy to push code changes without reprovisioning infrastructure.

   Deploy updated code

   azd deploy

aspire deploy vs azd comparison

Feature	aspire deploy	azd
Azure Container Apps	✅	✅
Azure App Service	✅	❌
Infrastructure provisioning	Built-in	Built-in
CI/CD pipeline setup	Manual	azd pipeline config
Environment management	State caching	azd env
Manifest dependency	No	Yes

Resource naming

The aspire deploy path and azd use different resource naming schemes by default. If you’re upgrading from an existing azd deployment to aspire deploy, use WithAzdResourceNaming() to preserve the original naming convention. This avoids creating duplicate Azure resources:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureContainerAppEnvironment("env")
    .WithAzdResourceNaming();

TypeScript

apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const env = await builder.addAzureContainerAppEnvironment('env');
await env.withAzdResourceNaming();

Deployment manifest

The azd tool relies on the deployment manifest format to understand your application topology. The manifest is a JSON document generated from the AppHost that describes resources, bindings, and parameters. It’s produced automatically when azd invokes the AppHost during deployment.

Attention

The deployment manifest format is deprecated and no longer being evolved. New features and deployment targets are delivered through the aspire deploy path. See Deploy using the Aspire CLI.

See also

• Deploy using the Aspire CLI — recommended deployment path
• Deployment manifest format
• Azure Developer CLI documentation