feat: add azd CLI evaluation and testing framework by spboyer · Pull Request #7202 · Azure/azure-dev

spboyer · 2026-03-19T03:40:50Z

Problem

We have no visibility into how GitHub Copilot CLI interacts with azd. Unlike the microsoft/github-copilot-for-azure skills repo — which has a comprehensive test, eval, and CI setup — the azd CLI has zero coverage for measuring LLM interactions, command discoverability, or human usability patterns. We have no idea whether Copilot CLI can successfully discover commands, interpret help text, handle errors gracefully, or guide users through common workflows.

Solution

This PR adds a comprehensive evaluation and testing framework at cli/azd/test/eval/ inspired by the GHCP4A setup. It covers both LLM eval (how well an AI agent uses azd) and non-LLM unit tests (how well azd surfaces information for human and AI consumption).

What's included

125 passing tests across 7 suites:

Command Registry (15) — verifies all 14 core commands respond to --help
Help Text Quality (43) — validates Usage/Flags sections, meaningful descriptions
Command Sequencing (4) — ensures commands fail with guidance in empty directories
Flag Validation (13) — --output json, --no-prompt, -e/--environment flags
Human CLI Workflow (6 + 4 skipped E2E) — setup verification, local-only commands
Command Discovery (20) — root help, subcommand help, flag docs, completion, consistency
Error Recovery (10) — missing project, invalid config, unknown commands/flags

15 Python grader unit tests (pytest):

app_health.py — HTTP health checks with retry logic
cleanup_validator.py — ARM API validation for post-azd down cleanup
infra_validator.py — ARM API validation for post-azd provision resources

14 Waza LLM eval task definitions (YAML):

Deploy, lifecycle, environment, troubleshoot, and negative scenarios
Custom graders for infra validation, app health, and cleanup

4 CI workflows:

eval-unit.yml — runs unit tests + waza validate on PR
eval-waza.yml — Waza LLM evals 3x/day (Tue-Sat)
eval-e2e.yml — weekly E2E with Azure resource validation
eval-report.yml — weekly report generation + auto-issue creation

Setup Required Before Going Live

Secrets to configure (Settings → Secrets and variables → Actions)

Secret	Required For	How to Get
`AZURE_CLIENT_ID`	`eval-e2e.yml`	Create a service principal in Entra ID with OIDC federated credential for GitHub Actions
`AZURE_TENANT_ID`	`eval-e2e.yml`	Microsoft Entra ID → Overview → Tenant ID
`AZURE_SUBSCRIPTION_ID`	`eval-e2e.yml` + graders	Azure Portal → Subscriptions (pick a dev/test sub)
`COPILOT_CLI_TOKEN`	`eval-waza.yml`, `eval-e2e.yml`	Copilot CLI API token for Waza executor
`GITHUB_TOKEN`	`eval-report.yml`	Auto-provided — no setup needed

Service principal setup

# 1. Create SP with Contributor on target subscription
az ad sp create-for-rbac --name "azd-eval-ci" --role Contributor \
  --scopes /subscriptions/<SUBSCRIPTION_ID>

# 2. Add OIDC federated credential for GitHub Actions
az ad app federated-credential create \
  --id <APP_OBJECT_ID> \
  --parameters '{
    "name": "azd-eval-github",
    "issuer": "https://token.actions.githubusercontent.com",
    "subject": "repo:Azure/azure-dev:ref:refs/heads/main",
    "audiences": ["api://AzureADTokenExchange"]
  }'

# 3. Add secrets to the repo: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID

What works without any setup

Command	Description
`npm run test:unit`	75 Jest unit tests — no Azure, no LLM
`npm run test:human`	50 human usability tests — no Azure, no LLM
`npm run waza:run:mock`	Mock LLM evals — offline, fast
`eval-unit.yml` CI	Runs automatically on PRs to `cli/azd/test/eval/**`

What needs secrets

Workflow	Secrets Needed	Trigger
`eval-waza.yml`	`COPILOT_CLI_TOKEN`	Scheduled 3x daily
`eval-e2e.yml`	`AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_SUBSCRIPTION_ID`, `COPILOT_CLI_TOKEN`	Weekly
`eval-report.yml`	`GITHUB_TOKEN` (auto)	Weekly

No test ever opens a browser. Unit/human tests use --no-prompt and AZD_FORCE_TTY=false. E2E uses OIDC service principal auth (headless). See the README for full details.

Testing

All tests pass locally:

Jest:   7 suites, 125 passed, 4 skipped
Pytest: 15 grader tests passed

spboyer · 2026-03-19T03:56:54Z

@jongio & @wbreza - would appreciate a review here. Using waza and jests for testing evals .

Copilot

Pull request overview

Adds a new cli/azd/test/eval/ evaluation framework intended to measure how well GitHub Copilot CLI (and humans) can discover and use azd commands, plus scheduled GitHub Actions workflows to run these evals and publish artifacts/reports.

Changes:

Introduces a Node/TypeScript Jest test harness for unit-style CLI surface validation (help text, flags, sequencing).
Adds Waza task YAMLs (deploy/troubleshoot/environment/lifecycle/negative scenarios) and Python grader scripts for infra/app validation.
Adds GitHub Actions workflows to run unit tests on PRs and scheduled Waza/E2E/report jobs.

Reviewed changes

Copilot reviewed 36 out of 38 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
cli/azd/test/eval/tsconfig.json	TypeScript build configuration for eval tests/tools
cli/azd/test/eval/package.json	Node package + scripts for running Jest/Waza/reporting
cli/azd/test/eval/package-lock.json	Locked dependency tree for reproducible installs
cli/azd/test/eval/jest.config.ts	Jest configuration (ts-jest + junit in CI)
cli/azd/test/eval/.gitignore	Ignores build outputs and generated reports
cli/azd/test/eval/reports/.gitkeep	Keeps `reports/` directory in git
cli/azd/test/eval/eval.yaml	Waza eval configuration (executor/model/metrics/task globs)
cli/azd/test/eval/README.md	Documentation for running/extending eval framework
cli/azd/test/eval/tests/unit/command-registry.test.ts	Verifies core commands exist and respond to `--help`
cli/azd/test/eval/tests/unit/help-text-quality.test.ts	Checks help output contains expected sections/descriptions
cli/azd/test/eval/tests/unit/flag-validation.test.ts	Validates key flags appear/behave as expected
cli/azd/test/eval/tests/unit/command-sequencing.test.ts	Ensures commands fail with guidance in empty dirs
cli/azd/test/eval/tests/human/cli-workflow.test.ts	“Human baseline” tests for responsiveness/basic UX expectations
cli/azd/test/eval/tests/human/command-discovery.test.ts	“Human baseline” tests focused on discovering commands/flags
cli/azd/test/eval/tests/human/error-recovery.test.ts	“Human baseline” tests for actionable errors and recovery hints
cli/azd/test/eval/tasks/deploy/deploy-python-webapp.yaml	Waza task: deploy Python app guidance
cli/azd/test/eval/tasks/deploy/deploy-node-api.yaml	Waza task: deploy Node API guidance
cli/azd/test/eval/tasks/deploy/deploy-existing-project.yaml	Waza task: deploy existing azd project (avoid init)
cli/azd/test/eval/tasks/environment/create-staging.yaml	Waza task: create staging environment workflow
cli/azd/test/eval/tasks/environment/switch-env.yaml	Waza task: switch environments
cli/azd/test/eval/tasks/environment/delete-env.yaml	Waza task: teardown + delete environment workflow
cli/azd/test/eval/tasks/lifecycle/full-lifecycle.yaml	Waza task: init→provision→deploy→down sequence
cli/azd/test/eval/tasks/lifecycle/teardown-only.yaml	Waza task: down/cleanup guidance
cli/azd/test/eval/tasks/troubleshoot/auth-error.yaml	Waza task: troubleshoot auth error guidance
cli/azd/test/eval/tasks/troubleshoot/config-error.yaml	Waza task: troubleshoot malformed azure.yaml
cli/azd/test/eval/tasks/troubleshoot/quota-error.yaml	Waza task: troubleshoot quota error
cli/azd/test/eval/tasks/troubleshoot/provision-role-conflict.yaml	Waza task: troubleshoot RBAC role assignment conflict
cli/azd/test/eval/tasks/negative/raw-azure-cli.yaml	Waza negative task: use `az` not `azd`
cli/azd/test/eval/tasks/negative/not-azure.yaml	Waza negative task: non-Azure question should avoid azd
cli/azd/test/eval/tasks/negative/general-coding.yaml	Waza negative task: general coding response without azd
cli/azd/test/eval/graders/infra_validator.py	Python grader stub for ARM resource existence validation
cli/azd/test/eval/graders/cleanup_validator.py	Python grader stub for post-`azd down` cleanup validation
cli/azd/test/eval/graders/app_health.py	Python grader stub for HTTP endpoint health validation
cli/azd/.vscode/cspell.yaml	Adds spelling dictionary overrides for eval docs
.github/workflows/eval-unit.yml	PR workflow to build azd + run Jest unit suite
.github/workflows/eval-waza.yml	Scheduled workflow to run Waza evaluations
.github/workflows/eval-e2e.yml	Scheduled workflow intended for E2E lifecycle evals with Azure login
.github/workflows/eval-report.yml	Scheduled workflow intended to generate weekly comparison/regression issues

You can also share your feedback on Copilot code review. Take the survey.

cli/azd/test/eval/package.json

cli/azd/test/eval/tests/human/error-recovery.test.ts

cli/azd/test/eval/tests/human/command-discovery.test.ts

cli/azd/test/eval/README.md

.github/workflows/eval-report.yml

.github/workflows/eval-e2e.yml

cli/azd/test/eval/tests/human/cli-workflow.test.ts

.github/workflows/eval-unit.yml

cli/azd/test/eval/README.md

jongio

Good initiative - adding eval coverage for Copilot CLI interactions with azd fills a real gap. The Waza task definitions are well-structured, grader weights are mathematically correct across all 14 tasks, and the CI workflow design (unit on PR, Waza 3x/day, E2E weekly) is sensible.

However, there are structural and reliability issues that should be addressed before merge:

The azd() test helper is copy-pasted across 7 files with subtle inconsistencies (NO_COLOR vs AZD_DEBUG_FORCE_NO_TTY, e: any vs e: unknown) - this is already causing bugs and will make maintenance painful
Human test files don't set NO_COLOR: "1", so regex assertions against help text will be flaky when ANSI escape codes are present
The eval.yaml system prompt omits azd env delete, but delete-env.yaml expects the LLM to suggest it - this task will score poorly by design
app_health.py has inconsistent retry logic: status mismatches retry, but body-content mismatches return failure immediately
Two npm devDependencies (@azure/arm-resources, @azure/identity) are never imported anywhere

I've excluded items already covered by the existing review.

cli/azd/test/eval/tests/unit/command-registry.test.ts

cli/azd/test/eval/tests/human/cli-workflow.test.ts

cli/azd/test/eval/graders/app_health.py

cli/azd/test/eval/eval.yaml

cli/azd/test/eval/package.json

cli/azd/test/eval/graders/app_health.py

cli/azd/test/eval/jest.config.ts

.github/workflows/eval-unit.yml

cli/azd/test/eval/tests/unit/command-registry.test.ts

cli/azd/test/eval/tsconfig.json

Resolves all issues raised in PR #7202 review: - Extract shared azd() test helper to tests/test-utils.ts (eliminates duplication across 7 files, consistent NO_COLOR + AZD_FORCE_TTY) - Fix AZD_DEBUG_FORCE_NO_TTY → AZD_FORCE_TTY=false in all test files - Add NO_COLOR=1 to human tests (prevents ANSI flakiness) - Use catch(e: unknown) with proper type narrowing everywhere - Add azd env delete to eval.yaml system prompt (fixes delete-env task) - Fix app_health.py retry logic for body-content mismatches - Remove unused @azure/arm-resources and @azure/identity deps - Remove missing scripts/ references from package.json and tsconfig - Reduce jest timeout from 5min to 30s - eval-unit.yml: add permissions block and waza:validate step - eval-waza.yml: fix PATH via GITHUB_PATH instead of env.PATH - eval-e2e.yml: align waza install, fix cleanup step working directory - eval-report.yml: use gh CLI for cross-run artifact download - Remove non-existent eval-human.yml from README CI table - Add cspell overrides for grader/task/test files All 7 suites pass (125 tests + 4 skipped E2E). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

spboyer · 2026-03-19T20:44:12Z

@jongio - thanks for the feedback. Everything has been addressed here. Ready for another review.

@rajeshkamal5050 / @wbreza - going to need someone here with admin to setup the CI portions and TOKENS and subscription. See PR description on the how.

spboyer · 2026-03-19T21:00:10Z

@jongio All review feedback addressed and CI is fully green. Changes: shared test-utils.ts helper, 15 pytest grader tests, app_health.py retry fix, azd env delete in eval.yaml, removed unused deps, jest timeout reduction, workflow fixes (permissions, PATH, artifacts, cleanup), cspell overrides. PR body updated with full setup instructions. Ready for re-review!

jongio

Solid foundation for measuring Copilot CLI + azd interactions. The task YAML structure is well-designed, grader weight math is correct, and the CI pipeline layout (unit on PR, Waza scheduled, E2E weekly) makes sense. I've skipped items already raised in the existing reviews and focused on issues I haven't seen mentioned.

The graders have a logic gap in how urlopen handles non-2xx responses - it throws before your status comparison runs, so expected_status only works for 2xx codes. The get_access_token() function is copy-pasted across two grader files. The report workflow is entirely non-functional (placeholder echo + missing dependency file). A couple of the task YAML graders are either redundant or too strict in what they require from the LLM response.

cli/azd/test/eval/graders/app_health.py

cli/azd/test/eval/graders/cleanup_validator.py

.github/workflows/eval-report.yml

cli/azd/test/eval/tasks/lifecycle/teardown-only.yaml

cli/azd/test/eval/tasks/deploy/deploy-existing-project.yaml

cli/azd/test/eval/tests/test-utils.ts

Resolves all issues raised in PR #7202 review: - Extract shared azd() test helper to tests/test-utils.ts (eliminates duplication across 7 files, consistent NO_COLOR + AZD_FORCE_TTY) - Fix AZD_DEBUG_FORCE_NO_TTY → AZD_FORCE_TTY=false in all test files - Add NO_COLOR=1 to human tests (prevents ANSI flakiness) - Use catch(e: unknown) with proper type narrowing everywhere - Add azd env delete to eval.yaml system prompt (fixes delete-env task) - Fix app_health.py retry logic for body-content mismatches - Remove unused @azure/arm-resources and @azure/identity deps - Remove missing scripts/ references from package.json and tsconfig - Reduce jest timeout from 5min to 30s - eval-unit.yml: add permissions block and waza:validate step - eval-waza.yml: fix PATH via GITHUB_PATH instead of env.PATH - eval-e2e.yml: align waza install, fix cleanup step working directory - eval-report.yml: use gh CLI for cross-run artifact download - Remove non-existent eval-human.yml from README CI table - Add cspell overrides for grader/task/test files All 7 suites pass (125 tests + 4 skipped E2E). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

spboyer · 2026-03-20T14:35:24Z

@jongio Round 2 feedback addressed, rebased on main, and all CI passing locally. Changes: HTTPError non-2xx handling in app_health.py, shared azure_auth.py module, cleaned up eval-report.yml, relaxed teardown-only.yaml grader, fixed duplicate grader in deploy-existing-project.yaml, Windows .exe support in test-utils.ts. Replied to each comment individually. Ready for re-review!

jongio

Both rounds of feedback are fully addressed - test helper extraction, grader reliability fixes (HTTPError handling, retry consistency, access token dedup), task YAML corrections, and CI hardening all look good. Thanks for the thorough follow-through.

.github/workflows/eval-e2e.yml

cli/azd/test/eval/eval.yaml

cli/azd/test/eval/tasks/deploy/deploy-python-webapp.yaml

cli/azd/test/eval/README.md

Resolves all issues raised in PR #7202 review: - Extract shared azd() test helper to tests/test-utils.ts (eliminates duplication across 7 files, consistent NO_COLOR + AZD_FORCE_TTY) - Fix AZD_DEBUG_FORCE_NO_TTY → AZD_FORCE_TTY=false in all test files - Add NO_COLOR=1 to human tests (prevents ANSI flakiness) - Use catch(e: unknown) with proper type narrowing everywhere - Add azd env delete to eval.yaml system prompt (fixes delete-env task) - Fix app_health.py retry logic for body-content mismatches - Remove unused @azure/arm-resources and @azure/identity deps - Remove missing scripts/ references from package.json and tsconfig - Reduce jest timeout from 5min to 30s - eval-unit.yml: add permissions block and waza:validate step - eval-waza.yml: fix PATH via GITHUB_PATH instead of env.PATH - eval-e2e.yml: align waza install, fix cleanup step working directory - eval-report.yml: use gh CLI for cross-run artifact download - Remove non-existent eval-human.yml from README CI table - Add cspell overrides for grader/task/test files All 7 suites pass (125 tests + 4 skipped E2E). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jongio

Previous comments addressed. One gap from the new error-handling change:

graders/infra_validator.py:85 - list_resources() call unprotected after it was changed to re-raise non-404 HTTPErrors

Same pattern exists in cleanup_validator.py for list_remaining_resources().

cli/azd/test/eval/graders/infra_validator.py

jongio

Issues to address:

graders/cleanup_validator.py:97 - list_remaining_resources() call isn't wrapped in try/except (same class as the open thread on infra_validator.py:85)
.github/workflows/eval-waza.yml:40 - missing timeout-minutes on Waza run step

Minor:

tasks/troubleshoot/quota-error.yaml:20 - must_not_match: "contact support" penalizes valid advice

cli/azd/test/eval/graders/cleanup_validator.py

.github/workflows/eval-waza.yml

cli/azd/test/eval/tasks/troubleshoot/quota-error.yaml

Resolves all issues raised in PR #7202 review: - Extract shared azd() test helper to tests/test-utils.ts (eliminates duplication across 7 files, consistent NO_COLOR + AZD_FORCE_TTY) - Fix AZD_DEBUG_FORCE_NO_TTY → AZD_FORCE_TTY=false in all test files - Add NO_COLOR=1 to human tests (prevents ANSI flakiness) - Use catch(e: unknown) with proper type narrowing everywhere - Add azd env delete to eval.yaml system prompt (fixes delete-env task) - Fix app_health.py retry logic for body-content mismatches - Remove unused @azure/arm-resources and @azure/identity deps - Remove missing scripts/ references from package.json and tsconfig - Reduce jest timeout from 5min to 30s - eval-unit.yml: add permissions block and waza:validate step - eval-waza.yml: fix PATH via GITHUB_PATH instead of env.PATH - eval-e2e.yml: align waza install, fix cleanup step working directory - eval-report.yml: use gh CLI for cross-run artifact download - Remove non-existent eval-human.yml from README CI table - Add cspell overrides for grader/task/test files All 7 suites pass (125 tests + 4 skipped E2E). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.github/workflows/eval-e2e.yml

Add a comprehensive eval/test framework for measuring how GitHub Copilot CLI interacts with azd. Includes: - 75 unit tests across 4 suites: command registry, help text quality, command sequencing, and flag validation - Human-scenario test stubs for CLI workflow, command discovery, and error recovery evaluation - Waza-compatible task YAML definitions for LLM eval (deploy, lifecycle, environment, troubleshoot, negative scenarios) - Custom graders for infrastructure validation, app health, and cleanup - CI workflows for unit tests, E2E tests, Waza runs, and report generation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…d tests Covers: - Step-by-step Waza LLM eval task creation with full YAML reference - Grader reference table (text, action_sequence, behavior, code) - Custom Python grader authoring with Azure ARM API example - Jest unit test and human scenario test templates - Directory structure reference - Regex tips and common patterns Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- command-registry: exclude beta-gated commands (build) from root --help assertion - command-sequencing: accept auth-related errors in CI where no Azure login exists - cspell: add waza/urlopen to eval README overrides Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Removing AZD_CONFIG_DIR override prevents tests from wiping auth state and triggering browser-based Azure login. Tests only need an empty cwd to verify azd fails gracefully without a project. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ntee Adds test tier table showing which tests need auth, step-by-step service principal setup for CI, and local subscription configuration. Clarifies that no test should ever open a browser. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Resolves all issues raised in PR #7202 review: - Extract shared azd() test helper to tests/test-utils.ts (eliminates duplication across 7 files, consistent NO_COLOR + AZD_FORCE_TTY) - Fix AZD_DEBUG_FORCE_NO_TTY → AZD_FORCE_TTY=false in all test files - Add NO_COLOR=1 to human tests (prevents ANSI flakiness) - Use catch(e: unknown) with proper type narrowing everywhere - Add azd env delete to eval.yaml system prompt (fixes delete-env task) - Fix app_health.py retry logic for body-content mismatches - Remove unused @azure/arm-resources and @azure/identity deps - Remove missing scripts/ references from package.json and tsconfig - Reduce jest timeout from 5min to 30s - eval-unit.yml: add permissions block and waza:validate step - eval-waza.yml: fix PATH via GITHUB_PATH instead of env.PATH - eval-e2e.yml: align waza install, fix cleanup step working directory - eval-report.yml: use gh CLI for cross-run artifact download - Remove non-existent eval-human.yml from README CI table - Add cspell overrides for grader/task/test files All 7 suites pass (125 tests + 4 skipped E2E). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- app_health.py: handle non-2xx expected_status via HTTPError.code comparison - Extract shared get_access_token() to graders/azure_auth.py (was duplicated in cleanup_validator.py and infra_validator.py) - eval-report.yml: remove non-functional regression issue step, drop issues:write permission, add TODO for future report generation script - teardown-only.yaml: relax --purge from must_match to must_match_any (--force without --purge is a valid response) - deploy-existing-project.yaml: replace duplicate grader with check for --no-prompt, azure.yaml, service, or --all - test-utils.ts: add .exe extension on Windows for cross-platform support - Add 2 new pytest tests for HTTPError expected_status matching Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ling - Fix mock patch targets: patch cleanup_validator/infra_validator instead of azure_auth to correctly intercept imported names - Replace azd env delete with azd env remove (correct CLI command) - Add pytest step to eval-unit.yml for grader tests - Remove continue-on-error from waza validate step - Catch HTTPError in grade() functions to return score 0 gracefully - Fix README grader signature: grade(context) not grade(inputs, params) - Filter eval-report.yml artifact downloads to main branch only Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The waza CLI is not available in the CI runner environment. Make the validation step conditional to unblock the workflow. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Jon Gallant <2163001+jongio@users.noreply.github.com>

- README: update code examples to use shared test-utils.ts import (removes catch(e:any), AZD_DEBUG_FORCE_NO_TTY, inline helpers) - README: remove nonexistent scripts/ from directory structure - README: fix CI table eval-report description (removed auto-issue ref) - README: align Waza install method with CI (npm install -g waza) - README: clarify code graders are for E2E lifecycle only - eval-e2e.yml: fix cleanup step to use correct working directory - deploy-existing-project.yaml: make grader 4 check for deployment explanation instead of duplicating command/flag checks from grader 1 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Fix shell injection in test-utils.ts (use execFileSync) - Fix app_health.py HTTPError body check - Tighten command-sequencing test assertions - Remove continue-on-error masking in eval-waza.yml (staged separately) - Fix action_sequence grader to accept azd up shorthand Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Eval failures should fail the workflow. Results are still uploaded via if: always() on the artifact upload step. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Narrow azure_auth.py exception handling to expected failures - Fix cleanup_validator.py to only swallow 404, not all HTTPErrors - Fix eval-e2e.yml cleanup step to not depend on azure.yaml Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Fix list_resources() to re-raise non-404 HTTPError instead of silently returning empty list. Matches cleanup_validator.py pattern. - Fix README build path: cd ../../ (not ../../../) from test/eval/. - Remove unused tsx devDependency from package.json. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Wrap list_resources/list_remaining_resources callers in try/except to handle non-404 HTTPError after upstream fix. - Add timeout-minutes: 30 to eval-waza.yml workflow step. - Narrow 'contact support' negative match to 'only contact support' so mentioning support alongside actionable steps isn't penalized. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Per danieljurek's feedback, tag resource groups with DeleteAfter before deleting so the cleanup script can detect and remove resources that resist deletion. Switched to PowerShell for consistency with the cleanup script. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

azure-sdk · 2026-04-02T20:30:48Z

Azure Dev CLI Install Instructions

Install scripts

MacOS/Linux

May elevate using sudo on some platforms and configurations

bash:

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

pwsh:

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

Windows

PowerShell install

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

MSI install

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

Standalone Binary

MSI

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

Documentation

learn.microsoft.com documentation

title: Azure Developer CLI reference
description: This article explains the syntax and parameters for the various Azure Developer CLI commands.
author: alexwolfmsft
ms.author: alexwolf
ms.date: 04/02/2026
ms.service: azure-dev-cli
ms.topic: conceptual
ms.custom: devx-track-azdevcli

Azure Developer CLI reference

This article explains the syntax and parameters for the various Azure Developer CLI commands.

azd

The Azure Developer CLI (azd) is an open-source tool that helps onboard and manage your project on Azure

Options

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --docs         Opens the documentation for azd in your web browser.
  -h, --help         Gets help for azd.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd add

Add a component to your project.

azd add [flags]

Options

      --docs   Opens the documentation for azd add in your web browser.
  -h, --help   Gets help for add.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd auth

Authenticate with Azure.

Options

      --docs   Opens the documentation for azd auth in your web browser.
  -h, --help   Gets help for auth.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

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.

azd auth login [flags]

Options

      --check-status                           Checks the log-in status instead of logging in.
      --client-certificate string              The path to the client certificate for the service principal to authenticate with.
      --client-id string                       The client id for the service principal to authenticate with.
      --client-secret string                   The client secret for the service principal to authenticate with. Set to the empty string to read the value from the console.
      --docs                                   Opens the documentation for azd auth login in your web browser.
      --federated-credential-provider string   The provider to use to acquire a federated token to authenticate with. Supported values: github, azure-pipelines, oidc
  -h, --help                                   Gets help for login.
      --managed-identity                       Use a managed identity to authenticate.
      --redirect-port int                      Choose the port to be used as part of the redirect URI during interactive login.
      --tenant-id string                       The tenant id or domain name to authenticate with.
      --use-device-code[=true]                 When true, log in by using a device code instead of a browser.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd auth logout

Log out of Azure.

Synopsis

Log out of Azure

azd auth logout [flags]

Options

      --docs   Opens the documentation for azd auth logout in your web browser.
  -h, --help   Gets help for logout.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd auth status

Show the current authentication status.

Synopsis

Display whether you are logged in to Azure and the associated account information.

azd auth status [flags]

Options

      --docs   Opens the documentation for azd auth status in your web browser.
  -h, --help   Gets help for status.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd completion

Generate shell completion scripts.

Synopsis

Generate shell completion scripts for azd.

The completion command allows you to generate autocompletion scripts for your shell,
currently supports bash, zsh, fish and PowerShell.

See each sub-command's help for details on how to use the generated script.

Options

      --docs   Opens the documentation for azd completion in your web browser.
  -h, --help   Gets help for completion.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd completion bash

Generate bash completion script.

azd completion bash

Options

      --docs   Opens the documentation for azd completion bash in your web browser.
  -h, --help   Gets help for bash.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd completion fig

Generate Fig autocomplete spec.

azd completion fig

Options

      --docs   Opens the documentation for azd completion fig in your web browser.
  -h, --help   Gets help for fig.

Options inherited from parent commands

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

azd completion fish

Generate fish completion script.

azd completion fish

Options

      --docs   Opens the documentation for azd completion fish in your web browser.
  -h, --help   Gets help for fish.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd completion powershell

Generate PowerShell completion script.

azd completion powershell

Options

      --docs   Opens the documentation for azd completion powershell in your web browser.
  -h, --help   Gets help for powershell.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd completion zsh

Generate zsh completion script.

azd completion zsh

Options

      --docs   Opens the documentation for azd completion zsh in your web browser.
  -h, --help   Gets help for zsh.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd config

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

Synopsis

Manage the Azure Developer CLI user configuration, which includes your default Azure subscription and location.

Available since azure-dev-cli_0.4.0-beta.1.

The easiest way to configure azd for the first time is to run azd init. The subscription and location you select will be stored in the config.json file located in the config directory. To configure azd anytime afterwards, you'll use azd config set.

The default value of the config directory is:

$HOME/.azd on Linux and macOS
%USERPROFILE%.azd on Windows

The configuration directory can be overridden by specifying a path in the AZD_CONFIG_DIR environment variable.

Options

      --docs   Opens the documentation for azd config in your web browser.
  -h, --help   Gets help for config.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd config get

Gets a configuration.

Synopsis

Gets a configuration in the configuration path.

The default value of the config directory is:

$HOME/.azd on Linux and macOS
%USERPROFILE%\.azd on Windows

The configuration directory can be overridden by specifying a path in the AZD_CONFIG_DIR environment variable.

azd config get <path> [flags]

Options

      --docs   Opens the documentation for azd config get in your web browser.
  -h, --help   Gets help for get.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd config list-alpha

Display the list of available features in alpha stage.

azd config list-alpha [flags]

Options

      --docs   Opens the documentation for azd config list-alpha in your web browser.
  -h, --help   Gets help for list-alpha.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd config options

List all available configuration settings.

Synopsis

List all possible configuration settings that can be set with azd, including descriptions and allowed values.

azd config options [flags]

Options

      --docs   Opens the documentation for azd config options in your web browser.
  -h, --help   Gets help for options.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd config reset

Resets configuration to default.

Synopsis

Resets all configuration in the configuration path.

The default value of the config directory is:

$HOME/.azd on Linux and macOS
%USERPROFILE%\.azd on Windows

The configuration directory can be overridden by specifying a path in the AZD_CONFIG_DIR environment variable to the default.

azd config reset [flags]

Options

      --docs    Opens the documentation for azd config reset in your web browser.
  -f, --force   Force reset without confirmation.
  -h, --help    Gets help for reset.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd config set

Sets a configuration.

Synopsis

Sets a configuration in the configuration path.

The default value of the config directory is:

$HOME/.azd on Linux and macOS
%USERPROFILE%\.azd on Windows

The configuration directory can be overridden by specifying a path in the AZD_CONFIG_DIR environment variable.

azd config set <path> <value> [flags]

Examples

azd config set defaults.subscription <yourSubscriptionID>
azd config set defaults.location eastus

Options

      --docs   Opens the documentation for azd config set in your web browser.
  -h, --help   Gets help for set.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd config show

Show all the configuration values.

Synopsis

Show all configuration values in the configuration path.

The default value of the config directory is:

$HOME/.azd on Linux and macOS
%USERPROFILE%\.azd on Windows

The configuration directory can be overridden by specifying a path in the AZD_CONFIG_DIR environment variable.

azd config show [flags]

Options

      --docs   Opens the documentation for azd config show in your web browser.
  -h, --help   Gets help for show.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd config unset

Unsets a configuration.

Synopsis

Removes a configuration in the configuration path.

The default value of the config directory is:

$HOME/.azd on Linux and macOS
%USERPROFILE%\.azd on Windows

The configuration directory can be overridden by specifying a path in the AZD_CONFIG_DIR environment variable.

azd config unset <path> [flags]

Examples

azd config unset defaults.location

Options

      --docs   Opens the documentation for azd config unset in your web browser.
  -h, --help   Gets help for unset.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd copilot

Manage GitHub Copilot agent settings. (Preview)

Options

      --docs   Opens the documentation for azd copilot in your web browser.
  -h, --help   Gets help for copilot.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd copilot consent

Manage tool consent.

Synopsis

Manage consent rules for tool execution.

Options

      --docs   Opens the documentation for azd copilot consent in your web browser.
  -h, --help   Gets help for consent.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd copilot consent grant

Grant consent trust rules.

Synopsis

Grant trust rules for tools and servers.

This command creates consent rules that allow tools to execute
without prompting for permission. You can specify different permission
levels and scopes for the rules.

Examples:

Grant always permission to all tools globally

azd copilot consent grant --global --permission always

Grant project permission to a specific tool with read-only scope

azd copilot consent grant --server my-server --tool my-tool --permission project --scope read-only

azd copilot consent grant [flags]

Options

      --action string       Action type: 'all' or 'readonly' (default "all")
      --docs                Opens the documentation for azd copilot consent grant in your web browser.
      --global              Apply globally to all servers
  -h, --help                Gets help for grant.
      --operation string    Operation type: 'tool' or 'sampling' (default "tool")
      --permission string   Permission: 'allow', 'deny', or 'prompt' (default "allow")
      --scope string        Rule scope: 'global', or 'project' (default "global")
      --server string       Server name
      --tool string         Specific tool name (requires --server)

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd copilot consent list

List consent rules.

Synopsis

List all consent rules for tools.

azd copilot consent list [flags]

Options

      --action string       Action type to filter by (readonly, any)
      --docs                Opens the documentation for azd copilot consent list in your web browser.
  -h, --help                Gets help for list.
      --operation string    Operation to filter by (tool, sampling)
      --permission string   Permission to filter by (allow, deny, prompt)
      --scope string        Consent scope to filter by (global, project). If not specified, lists rules from all scopes.
      --target string       Specific target to operate on (server/tool format)

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd copilot consent revoke

Revoke consent rules.

Synopsis

Revoke consent rules for tools.

azd copilot consent revoke [flags]

Options

      --action string       Action type to filter by (readonly, any)
      --docs                Opens the documentation for azd copilot consent revoke in your web browser.
  -h, --help                Gets help for revoke.
      --operation string    Operation to filter by (tool, sampling)
      --permission string   Permission to filter by (allow, deny, prompt)
      --scope string        Consent scope to filter by (global, project). If not specified, revokes rules from all scopes.
      --target string       Specific target to operate on (server/tool format)

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd deploy

Deploy your project code to Azure.

azd deploy <service> [flags]

Options

      --all                   Deploys all services that are listed in azure.yaml
      --docs                  Opens the documentation for azd deploy in your web browser.
  -e, --environment string    The name of the environment to use.
      --from-package string   Deploys the packaged service located at the provided path. Supports zipped file packages (file path) or container images (image tag).
  -h, --help                  Gets help for deploy.
      --timeout int           Maximum time in seconds for azd to wait for each service deployment. This stops azd from waiting but does not cancel the Azure-side deployment. (default: 1200) (default 1200)

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd down

Delete your project's Azure resources.

azd down [<layer>] [flags]

Options

      --docs                 Opens the documentation for azd down in your web browser.
  -e, --environment string   The name of the environment to use.
      --force                Does not require confirmation before it deletes resources.
  -h, --help                 Gets help for down.
      --purge                Does not require confirmation before it permanently deletes resources that are soft-deleted by default (for example, key vaults).

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd env

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

Options

      --docs   Opens the documentation for azd env in your web browser.
  -h, --help   Gets help for env.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd env config

Manage environment configuration (ex: stored in .azure//config.json).

Options

      --docs   Opens the documentation for azd env config in your web browser.
  -h, --help   Gets help for config.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd env config get

Gets a configuration value from the environment.

Synopsis

Gets a configuration value from the environment's config.json file.

azd env config get <path> [flags]

Options

      --docs                 Opens the documentation for azd env config get in your web browser.
  -e, --environment string   The name of the environment to use.
  -h, --help                 Gets help for get.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd env config set

Sets a configuration value in the environment.

Synopsis

Sets a configuration value in the environment's config.json file.

Values are automatically parsed as JSON types when possible. Booleans (true/false),
numbers (42, 3.14), arrays ([...]), and objects ({...}) are stored with their native
JSON types. Plain text values are stored as strings. To force a JSON-typed value to be
stored as a string, wrap it in JSON quotes (e.g. '"true"' or '"8080"').

azd env config set <path> <value> [flags]

Examples

azd env config set myapp.endpoint https://example.com
azd env config set myapp.debug true
azd env config set myapp.count 42
azd env config set infra.parameters.tags '{"env":"dev"}'
azd env config set myapp.port '"8080"'

Options

      --docs                 Opens the documentation for azd env config set in your web browser.
  -e, --environment string   The name of the environment to use.
  -h, --help                 Gets help for set.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd env config unset

Unsets a configuration value in the environment.

Synopsis

Removes a configuration value from the environment's config.json file.

azd env config unset <path> [flags]

Examples

azd env config unset myapp.endpoint

Options

      --docs                 Opens the documentation for azd env config unset in your web browser.
  -e, --environment string   The name of the environment to use.
  -h, --help                 Gets help for unset.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd env get-value

Get specific environment value.

azd env get-value <keyName> [flags]

Options

      --docs                 Opens the documentation for azd env get-value in your web browser.
  -e, --environment string   The name of the environment to use.
  -h, --help                 Gets help for get-value.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd env get-values

Get all environment values.

azd env get-values [flags]

Options

      --docs                 Opens the documentation for azd env get-values in your web browser.
  -e, --environment string   The name of the environment to use.
  -h, --help                 Gets help for get-values.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd env list

List environments.

azd env list [flags]

Options

      --docs   Opens the documentation for azd env list in your web browser.
  -h, --help   Gets help for list.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd env new

Create a new environment and set it as the default.

azd env new <environment> [flags]

Options

      --docs                  Opens the documentation for azd env new in your web browser.
  -h, --help                  Gets help for new.
  -l, --location string       Azure location for the new environment
      --subscription string   ID of an Azure subscription to use for the new environment

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd env refresh

Refresh environment values by using information from a previous infrastructure provision.

azd env refresh <environment> [flags]

Options

      --docs                 Opens the documentation for azd env refresh in your web browser.
  -e, --environment string   The name of the environment to use.
  -h, --help                 Gets help for refresh.
      --hint string          Hint to help identify the environment to refresh
      --layer string         Provisioning layer to refresh the environment from.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd env remove

Remove an environment.

azd env remove <environment> [flags]

Options

      --docs                 Opens the documentation for azd env remove in your web browser.
  -e, --environment string   The name of the environment to use.
      --force                Skips confirmation before performing removal.
  -h, --help                 Gets help for remove.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd env select

Set the default environment.

azd env select [<environment>] [flags]

Options

      --docs   Opens the documentation for azd env select in your web browser.
  -h, --help   Gets help for select.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd env set

Set one or more environment values.

Synopsis

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

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

Options

      --docs                 Opens the documentation for azd env set in your web browser.
  -e, --environment string   The name of the environment to use.
      --file string          Path to .env formatted file to load environment values from.
  -h, --help                 Gets help for set.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd env set-secret

Set a name as a reference to a Key Vault secret in the environment.

Synopsis

You can either create a new Key Vault secret or select an existing one.
The provided name is the key for the .env file which holds the secret reference to the Key Vault secret.

azd env set-secret <name> [flags]

Options

      --docs                 Opens the documentation for azd env set-secret in your web browser.
  -e, --environment string   The name of the environment to use.
  -h, --help                 Gets help for set-secret.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd extension

Manage azd extensions.

Options

      --docs   Opens the documentation for azd extension in your web browser.
  -h, --help   Gets help for extension.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd extension install

Installs specified extensions.

azd extension install <extension-id> [flags]

Options

      --docs             Opens the documentation for azd extension install in your web browser.
  -f, --force            Force installation, including downgrades and reinstalls
  -h, --help             Gets help for install.
  -s, --source string    The extension source to use for installs
  -v, --version string   The version of the extension to install

Options inherited from parent commands

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

azd extension list

List available extensions.

azd extension list [--installed] [flags]

Options

      --docs            Opens the documentation for azd extension list in your web browser.
  -h, --help            Gets help for list.
      --installed       List installed extensions
      --source string   Filter extensions by source
      --tags strings    Filter extensions by tags

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd extension show

Show details for a specific extension.

azd extension show <extension-id> [flags]

Options

      --docs            Opens the documentation for azd extension show in your web browser.
  -h, --help            Gets help for show.
  -s, --source string   The extension source to use.

Options inherited from parent commands

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

azd extension source

View and manage extension sources

Options

      --docs   Opens the documentation for azd extension source in your web browser.
  -h, --help   Gets help for source.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd extension source add

Add an extension source with the specified name

azd extension source add [flags]

Options

      --docs              Opens the documentation for azd extension source add in your web browser.
  -h, --help              Gets help for add.
  -l, --location string   The location of the extension source
  -n, --name string       The name of the extension source
  -t, --type string       The type of the extension source. Supported types are 'file' and 'url'

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd extension source list

List extension sources

azd extension source list [flags]

Options

      --docs   Opens the documentation for azd extension source list in your web browser.
  -h, --help   Gets help for list.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd extension source remove

Remove an extension source with the specified name

azd extension source remove <name> [flags]

Options

      --docs   Opens the documentation for azd extension source remove in your web browser.
  -h, --help   Gets help for remove.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd extension source validate

Validate an extension source's registry.json file.

Synopsis

Validate an extension source's registry.json file.

Accepts a source name (from 'azd extension source list'), a local file path,
or a URL. Checks required fields, valid capabilities, semver version format,
platform artifact structure, and extension ID format.

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

Options

      --docs     Opens the documentation for azd extension source validate in your web browser.
  -h, --help     Gets help for validate.
      --strict   Enable strict validation (require checksums)

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd extension uninstall

Uninstall specified extensions.

azd extension uninstall [extension-id] [flags]

Options

      --all    Uninstall all installed extensions
      --docs   Opens the documentation for azd extension uninstall in your web browser.
  -h, --help   Gets help for uninstall.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd extension upgrade

Upgrade specified extensions.

azd extension upgrade [extension-id] [flags]

Options

      --all              Upgrade all installed extensions
      --docs             Opens the documentation for azd extension upgrade in your web browser.
  -h, --help             Gets help for upgrade.
  -s, --source string    The extension source to use for upgrades
  -v, --version string   The version of the extension to upgrade to

Options inherited from parent commands

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

azd hooks

Develop, test and run hooks for a project.

Options

      --docs   Opens the documentation for azd hooks in your web browser.
  -h, --help   Gets help for hooks.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd hooks run

Runs the specified hook for the project and services

azd hooks run <name> [flags]

Options

      --docs                 Opens the documentation for azd hooks run in your web browser.
  -e, --environment string   The name of the environment to use.
  -h, --help                 Gets help for run.
      --platform string      Forces hooks to run for the specified platform.
      --service string       Only runs hooks for the specified service.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd infra

Manage your Infrastructure as Code (IaC).

Options

      --docs   Opens the documentation for azd infra in your web browser.
  -h, --help   Gets help for infra.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd infra generate

Write IaC for your project to disk, allowing you to manually manage it.

azd infra generate [flags]

Options

      --docs                 Opens the documentation for azd infra generate in your web browser.
  -e, --environment string   The name of the environment to use.
      --force                Overwrite any existing files without prompting
  -h, --help                 Gets help for generate.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd init

Initialize a new application.

azd init [flags]

Options

  -b, --branch string         The template branch to initialize from. Must be used with a template argument (--template or -t).
      --docs                  Opens the documentation for azd init in your web browser.
  -e, --environment string    The name of the environment to use.
  -f, --filter strings        The tag(s) used to filter template results. Supports comma-separated values.
      --from-code             Initializes a new application from your existing code.
  -h, --help                  Gets help for init.
  -l, --location string       Azure location for the new environment
  -m, --minimal               Initializes a minimal project.
  -s, --subscription string   ID of an Azure subscription to use for the new environment
  -t, --template string       Initializes a new application from a template. You can use a Full URI, <owner>/<repository>, <repository> if it's part of the azure-samples organization, or a local directory path (./dir, ../dir, or absolute path).
      --up                    Provision and deploy to Azure after initializing the project from a template.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd mcp

Manage Model Context Protocol (MCP) server. (Alpha)

Options

      --docs   Opens the documentation for azd mcp in your web browser.
  -h, --help   Gets help for mcp.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd mcp start

Starts the MCP server.

Synopsis

Starts the Model Context Protocol (MCP) server.

This command starts an MCP server that can be used by MCP clients to access
azd functionality through the Model Context Protocol interface.

azd mcp start [flags]

Options

      --docs   Opens the documentation for azd mcp start in your web browser.
  -h, --help   Gets help for start.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd monitor

Monitor a deployed project.

azd monitor [flags]

Options

      --docs                 Opens the documentation for azd monitor in your web browser.
  -e, --environment string   The name of the environment to use.
  -h, --help                 Gets help for monitor.
      --live                 Open a browser to Application Insights Live Metrics. Live Metrics is currently not supported for Python apps.
      --logs                 Open a browser to Application Insights Logs.
      --overview             Open a browser to Application Insights Overview Dashboard.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd package

Packages the project's code to be deployed to Azure.

azd package <service> [flags]

Options

      --all                  Packages all services that are listed in azure.yaml
      --docs                 Opens the documentation for azd package in your web browser.
  -e, --environment string   The name of the environment to use.
  -h, --help                 Gets help for package.
      --output-path string   File or folder path where the generated packages will be saved.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd pipeline

Manage and configure your deployment pipelines.

Options

      --docs   Opens the documentation for azd pipeline in your web browser.
  -h, --help   Gets help for pipeline.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd pipeline config

Configure your deployment pipeline to connect securely to Azure. (Beta)

azd pipeline config [flags]

Options

  -m, --applicationServiceManagementReference string   Service Management Reference. References application or service contact information from a Service or Asset Management database. This value must be a Universally Unique Identifier (UUID). You can set this value globally by running azd config set pipeline.config.applicationServiceManagementReference <UUID>.
      --auth-type string                               The authentication type used between the pipeline provider and Azure for deployment (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

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

azd provision

Provision Azure resources for your project.

azd provision [<layer>] [flags]

Options

      --docs                  Opens the documentation for azd provision in your web browser.
  -e, --environment string    The name of the environment to use.
  -h, --help                  Gets help for provision.
  -l, --location string       Azure location for the new environment
      --no-state              (Bicep only) Forces a fresh deployment based on current Bicep template files, ignoring any stored deployment state.
      --preview               Preview changes to Azure resources.
      --subscription string   ID of an Azure subscription to use for the new environment

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd publish

Publish a service to a container registry.

azd publish <service> [flags]

Options

      --all                   Publishes all services that are listed in azure.yaml
      --docs                  Opens the documentation for azd publish in your web browser.
  -e, --environment string    The name of the environment to use.
      --from-package string   Publishes the service from a container image (image tag).
  -h, --help                  Gets help for publish.
      --to string             The target container image in the form '[registry/]repository[:tag]' to publish to.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd restore

Restores the project's dependencies.

azd restore <service> [flags]

Options

      --all                  Restores all services that are listed in azure.yaml
      --docs                 Opens the documentation for azd restore in your web browser.
  -e, --environment string   The name of the environment to use.
  -h, --help                 Gets help for restore.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd show

Display information about your project and its resources.

azd show [resource-name|resource-id] [flags]

Options

      --docs                 Opens the documentation for azd show in your web browser.
  -e, --environment string   The name of the environment to use.
  -h, --help                 Gets help for show.
      --show-secrets         Unmask secrets in output.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd template

Find and view template details.

Options

      --docs   Opens the documentation for azd template in your web browser.
  -h, --help   Gets help for template.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd template list

Show list of sample azd templates. (Beta)

azd template list [flags]

Options

      --docs             Opens the documentation for azd template list in your web browser.
  -f, --filter strings   The tag(s) used to filter template results. Supports comma-separated values.
  -h, --help             Gets help for list.
  -s, --source string    Filters templates by source.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd template show

Show details for a given template. (Beta)

azd template show <template> [flags]

Options

      --docs   Opens the documentation for azd template show in your web browser.
  -h, --help   Gets help for show.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd template source

View and manage template sources. (Beta)

Options

      --docs   Opens the documentation for azd template source in your web browser.
  -h, --help   Gets help for source.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd template source add

Adds an azd template source with the specified key. (Beta)

Synopsis

The key can be any value that uniquely identifies the template source, with well-known values being:
・default: Default templates
・awesome-azd: Templates from https://aka.ms/awesome-azd

azd template source add <key> [flags]

Options

      --docs              Opens the documentation for azd template source add in your web browser.
  -h, --help              Gets help for add.
  -l, --location string   Location of the template source. Required when using type flag.
  -n, --name string       Display name of the template source.
  -t, --type string       Kind of the template source. Supported types are 'file', 'url' and 'gh'.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd template source list

Lists the configured azd template sources. (Beta)

azd template source list [flags]

Options

      --docs   Opens the documentation for azd template source list in your web browser.
  -h, --help   Gets help for list.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd template source remove

Removes the specified azd template source (Beta)

azd template source remove <key> [flags]

Options

      --docs   Opens the documentation for azd template source remove in your web browser.
  -h, --help   Gets help for remove.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd up

Provision and deploy your project to Azure with a single command.

azd up [flags]

Options

      --docs                  Opens the documentation for azd up in your web browser.
  -e, --environment string    The name of the environment to use.
  -h, --help                  Gets help for up.
  -l, --location string       Azure location for the new environment
      --subscription string   ID of an Azure subscription to use for the new environment

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

azd version

Print the version number of Azure Developer CLI.

azd version [flags]

Options

      --docs   Opens the documentation for azd version in your web browser.
  -h, --help   Gets help for version.

Options inherited from parent commands

  -C, --cwd string   Sets the current working directory.
      --debug        Enables debugging and diagnostics logging.
      --no-prompt    Accepts the default value instead of prompting, or it fails if there is no default.

+                    - azd config set <key> <value>: Set configuration
+                    - azd restore: Restore project dependencies
+                    - azd build: Build application services
+                    - azd package: Package application for deployment

+              jobs:
+                unit-tests:
+                  runs-on: ubuntu-latest

	runs-on: ubuntu-latest
	runs-on: ubuntu-latest
	timeout-minutes: 15

+              from urllib.error import HTTPError, URLError
+              import app_health
+              import cleanup_validator

Conversation

spboyer commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

What's included

Setup Required Before Going Live

Secrets to configure (Settings → Secrets and variables → Actions)

Service principal setup

What works without any setup

What needs secrets

Testing

Uh oh!

spboyer commented Mar 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jongio left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

spboyer commented Mar 19, 2026

Uh oh!

spboyer commented Mar 19, 2026

Uh oh!

jongio left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

spboyer commented Mar 20, 2026

Uh oh!

jongio left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jongio left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jongio left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

azure-sdk commented Apr 2, 2026

Azure Dev CLI Install Instructions

spboyer commented Mar 19, 2026 •

edited

Loading

jongio left a comment •

edited

Loading

jongio left a comment •

edited

Loading

title: Azure Developer CLI reference
description: This article explains the syntax and parameters for the various Azure Developer CLI commands.
author: alexwolfmsft
ms.author: alexwolf
ms.date: 04/02/2026
ms.service: azure-dev-cli
ms.topic: conceptual
ms.custom: devx-track-azdevcli