az prototype

Preview

Note

This reference is part of the prototype extension for the Azure CLI (version 2.50.0 or higher). The extension will automatically install the first time you run an az prototype command. Learn more about extensions.

This command group is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Rapidly create Azure prototypes using AI-driven agent teams.

The az prototype extension empowers you to build functional Azure prototypes using intelligent agent teams powered by GitHub Copilot or Azure OpenAI.

Workflow: init → design → build → deploy

Each stage can be run independently (with prerequisite guards) and most stages are re-entrant — you can return to refine your design or rebuild specific components.

Analysis commands let you diagnose errors and estimate costs at any point.

Commands

Name	Description	Type	Status
az prototype agent	Manage AI agents for prototype generation.	Extension	Preview
az prototype agent add	Add a custom agent to the project.	Extension	Preview
az prototype agent export	Export any agent (including built-in) as a YAML file.	Extension	Preview
az prototype agent list	List all available agents (built-in and custom).	Extension	Preview
az prototype agent override	Override a built-in agent with a custom definition.	Extension	Preview
az prototype agent remove	Remove a custom agent or override.	Extension	Preview
az prototype agent show	Show details of a specific agent.	Extension	Preview
az prototype agent test	Send a test prompt to any agent and display the response.	Extension	Preview
az prototype agent update	Update an existing custom agent's properties.	Extension	Preview
az prototype analyze	Analyze errors, costs, and diagnostics for the prototype.	Extension	Preview
az prototype analyze costs	Estimate Azure costs at Small/Medium/Large t-shirt sizes.	Extension	Preview
az prototype analyze error	Analyze an error and get a fix with redeployment instructions.	Extension	Preview
az prototype build	Generate infrastructure and application code in staged output.	Extension	Preview
az prototype config	Manage prototype project configuration.	Extension	Preview
az prototype config get	Get a single configuration value.	Extension	Preview
az prototype config init	Interactive setup to create a prototype.yaml configuration file.	Extension	Preview
az prototype config set	Set a configuration value.	Extension	Preview
az prototype config show	Display current project configuration.	Extension	Preview
az prototype deploy	Deploy prototype to Azure with interactive staged deployments.	Extension	Preview
az prototype design	Analyze requirements and generate architecture design.	Extension	Preview
az prototype generate	Generate documentation and spec-kit artifacts.	Extension	Preview
az prototype generate backlog	Generate a backlog and push work items to GitHub or Azure DevOps.	Extension	Preview
az prototype generate docs	Generate documentation from templates with AI population.	Extension	Preview
az prototype generate speckit	Generate the spec-kit documentation bundle with AI population.	Extension	Preview
az prototype init	Initialize a new prototype project.	Extension	Preview
az prototype knowledge	Manage knowledge base contributions.	Extension	Preview
az prototype knowledge contribute	Submit a knowledge base contribution as a GitHub Issue.	Extension	Preview
az prototype status	Show current project status across all stages.	Extension	Preview

az prototype build

Preview

Command group 'prototype' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Generate infrastructure and application code in staged output.

Uses the architecture design to generate Terraform/Bicep modules, application code, database scripts, and documentation.

Interactive by default — the build session uses Claude Code-inspired bordered prompts, progress indicators, policy enforcement, and a conversational review loop.

All output is organized into fine-grained, dependency-ordered deployment stages. Each infrastructure component, database system, and application gets its own stage. Workload templates are used as optional starting points when they match the design.

After generation, a build report shows what was built and you can provide feedback to regenerate specific stages. Type 'done' to accept the build.

Slash commands during build: /status - Show stage completion summary /stages - Show full deployment plan /files - List all generated files /policy - Show policy check summary /help - Show available commands

Use --dry-run for a non-interactive preview.

az prototype build [--auto-accept]
                   [--dry-run]
                   [--reset]
                   [--scope {all, apps, db, docs, infra}]
                   [--status]

Examples

Interactive build session (default)

az prototype build

Show current build progress

az prototype build --status

Clear build state and start fresh

az prototype build --reset

Build only infrastructure code

az prototype build --scope infra

Preview what would be generated

az prototype build --scope all --dry-run

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--auto-accept

Automatically accept the default recommendation for policy violations and standards conflicts.

Property	Value
Default value:	False

--dry-run

Preview what would be generated without writing files.

Property	Value
Default value:	False

--reset

Clear existing build state and start fresh.

Property	Value
Default value:	False

--scope

What to build.

Property	Value
Default value:	all
Accepted values:	all, apps, db, docs, infra

--status -s

Show current build progress without starting a session.

Property	Value
Default value:	False

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az prototype deploy

Preview

Command group 'prototype' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Deploy prototype to Azure with interactive staged deployments.

Interactive by default — runs preflight checks (subscription, IaC tool, resource group, resource providers), then deploys stages sequentially with progress tracking and QA-first error routing.

After deployment, enters a conversational loop where you can check status, rollback, redeploy, or preview changes using slash commands.

Slash commands during deploy: /status - Show stage completion summary /stages - Show full stage breakdown (alias for /status) /deploy N - Deploy a specific stage (or 'all' for pending) /rollback N - Roll back a specific stage (or 'all' in reverse order) /redeploy N - Roll back and redeploy a stage /plan N - What-if / terraform plan for a stage /outputs - Show captured deployment outputs /preflight - Re-run preflight checks /help - Show available commands

Use --dry-run for non-interactive what-if / terraform plan preview. Use --stage N for non-interactive single-stage deploy. Use --stage N --dry-run for what-if preview of a single stage. Use --outputs to show captured deployment outputs. Use --rollback-info to show rollback instructions. Use --generate-scripts to generate deploy.sh for application directories.

az prototype deploy [--client-id]
                    [--client-secret]
                    [--dry-run]
                    [--force]
                    [--generate-scripts]
                    [--outputs]
                    [--reset]
                    [--rollback-info]
                    [--script-registry]
                    [--script-resource-group]
                    [--script-type {container_app, function, webapp}]
                    [--service-principal]
                    [--stage]
                    [--status]
                    [--tenant]
                    [--tenant-id]

Examples

Interactive deploy session (default)

az prototype deploy

Show current deploy progress

az prototype deploy --status

Preview all stages (what-if / terraform plan)

az prototype deploy --dry-run

Deploy only stage 2

az prototype deploy --stage 2

Force full redeployment

az prototype deploy --force

Show captured deployment outputs

az prototype deploy --outputs

Show rollback instructions

az prototype deploy --rollback-info

Generate App Service deployment scripts

az prototype deploy --generate-scripts --script-type webapp

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--client-id

Service principal application/client ID (or set via config).

--client-secret

Service principal client secret (or set via config).

--dry-run

Preview what would be deployed (what-if for Bicep, plan for Terraform).

Property	Value
Default value:	False

--force

Force full deployment, ignoring change tracking.

Property	Value
Default value:	False

--generate-scripts

Generate deploy.sh scripts for application directories.

Property	Value
Default value:	False

--outputs

Show captured deployment outputs from Terraform / Bicep.

Property	Value
Default value:	False

--reset

Clear deploy state and start fresh.

Property	Value
Default value:	False

--rollback-info

Show rollback instructions based on deployment history.

Property	Value
Default value:	False

--script-registry

Container registry URL for --generate-scripts (container_app type).

--script-resource-group

Default resource group name for --generate-scripts.

--script-type

Azure deployment target type for --generate-scripts.

Property	Value
Default value:	webapp
Accepted values:	container_app, function, webapp

--service-principal

Authenticate using a service principal before deploying.

Property	Value
Default value:	False

--stage

Deploy only a specific stage number (use --status to see stages).

--status -s

Show current deploy progress without starting a session.

Property	Value
Default value:	False

--tenant

Azure AD tenant ID for cross-tenant deployment.

--tenant-id

Tenant ID for service principal authentication (or set via config).

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az prototype design

Preview

Command group 'prototype' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Analyze requirements and generate architecture design.

Reads artifacts (documents, diagrams, specs), engages the biz-analyst agent to identify gaps, and generates architecture documentation.

When run without parameters, starts an interactive dialogue to capture requirements through guided questions.

With --interactive, enters a refinement loop after architecture generation so you can review the design and request changes.

The biz-analyst agent is always engaged — even when --context is provided — to check for missing requirements and unstated assumptions.

This stage is re-entrant — run it again to refine the design.

az prototype design [--artifacts]
                    [--context]
                    [--interactive]
                    [--reset]
                    [--skip-discovery]
                    [--status]

Examples

Interactive design session (guided dialogue)

az prototype design

Interactive design with architecture refinement loop

az prototype design --interactive

Design from artifact directory

az prototype design --artifacts ./requirements/

Add context to existing design

az prototype design --context "Add Redis caching layer"

Reset and start design fresh

az prototype design --reset

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--artifacts

Path to directory containing requirement documents, diagrams, or other artifacts.

--context

Additional context or requirements as free text.

--interactive -i

Enter an interactive refinement loop after architecture generation.

Property	Value
Default value:	False

--reset

Reset design state and start fresh.

Property	Value
Default value:	False

--skip-discovery

Skip the discovery conversation and generate architecture directly from existing discovery state.

Property	Value
Default value:	False

--status -s

Show current discovery status (open items, confirmed items) without starting a session.

Property	Value
Default value:	False

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az prototype init

Preview

Command group 'prototype' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Initialize a new prototype project.

Sets up project scaffolding, creates the project configuration file, and optionally authenticates with GitHub (validates Copilot license).

GitHub authentication is only required for the copilot and github-models AI providers. When using azure-openai, GitHub auth is skipped entirely.

If the target directory already contains a prototype.yaml, the command will prompt before overwriting.

az prototype init [--ai-provider {azure-openai, copilot, github-models}]
                  [--environment {dev, prod, staging}]
                  [--iac-tool {bicep, terraform}]
                  [--location]
                  [--model]
                  [--name]
                  [--output-dir]
                  [--template]

Examples

Create a new prototype project

az prototype init --name my-prototype --location eastus

Initialize with Bicep preference

az prototype init --name my-app --location westus2 --iac-tool bicep

Use Azure OpenAI (skips GitHub auth)

az prototype init --name my-app --location eastus --ai-provider azure-openai

Specify environment and model

az prototype init --name my-app --location eastus --environment staging --model gpt-4o

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--ai-provider

AI provider for agent interactions.

Property	Value
Default value:	copilot
Accepted values:	azure-openai, copilot, github-models

--environment

Target environment for the prototype.

Property	Value
Default value:	dev
Accepted values:	dev, prod, staging

--iac-tool

Infrastructure-as-code tool preference.

Property	Value
Default value:	terraform
Accepted values:	bicep, terraform

--location -l

Azure region for resource deployment (e.g., eastus).

--model

AI model to use (default: claude-sonnet-4.5 for copilot, gpt-4o for others).

--name

Name of the prototype project.

--output-dir

Output directory for project files.

Property	Value
Default value:	.

--template

Project template to use (e.g., web-app, data-pipeline, ai-app).

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az prototype status

Preview

Command group 'prototype' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Show current project status across all stages.

Displays a summary of the prototype project including configuration, stage progress (design, build, deploy), and pending changes.

By default shows a human-readable summary. Use --json for machine-readable output suitable for scripting. Use --detailed for expanded per-stage details.

az prototype status [--detailed]
                    [--json]

Examples

Show project status

az prototype status

Show detailed status with per-stage breakdown

az prototype status --detailed

Get machine-readable JSON output

az prototype status --json

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--detailed -d

Show expanded per-stage details.

Property	Value
Default value:	False

--json -j

Output machine-readable JSON instead of formatted display.

Property	Value
Default value:	False

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

Feedback

Was this page helpful?

Share via

az prototype

Commands

az prototype build

Examples

Optional Parameters

az prototype deploy

Examples

Optional Parameters

az prototype design

Examples

Optional Parameters

az prototype init

Examples

Optional Parameters

az prototype status

Examples

Optional Parameters

Feedback