Skip to content

Command Reference

Jump to bottom
Joshua Davis edited this page Mar 26, 2026 · 4 revisions

Command Reference

This is the definitive reference for all az prototype commands. All commands are in preview.

Global flag: Every command accepts --json / -j to output machine-readable JSON instead of formatted display.

Table of Contents

prototype

Core commands for the prototype lifecycle.

prototype init

Initialize a new prototype project. Creates the project directory structure, prototype.yaml configuration, and .prototype/ state directory.

az prototype init --name <name>
                  --location <location>
                  [--iac-tool {terraform,bicep}]
                  [--ai-provider {github-models,azure-openai,copilot}]
                  [--output-dir <path>]
                  [--template <template>]
                  [--environment {dev,staging,prod}]
                  [--model <model>]
Parameter Type Default Description
--name String Required Name of the prototype project.
--location String Required Azure region for resource deployment (e.g., eastus).
--iac-tool Enum: terraform, bicep terraform Infrastructure-as-code tool preference.
--ai-provider Enum: github-models, azure-openai, copilot copilot AI provider for agent interactions.
--output-dir String . Output directory for project files.
--template String None Project template to use (e.g., web-app, data-pipeline, ai-app).
--environment Enum: dev, staging, prod dev Target environment for the prototype.
--model String None AI model to use (default: claude-sonnet-4.5 for copilot, gpt-4o for others).

Examples:

# Initialize a project with defaults (Terraform + Copilot)
az prototype init --name my-poc --location eastus

# Initialize with Bicep, Azure OpenAI, and a template
az prototype init --name api-poc --location westus2 --iac-tool bicep \
  --ai-provider azure-openai --template serverless-api --environment staging

prototype launch

Open the interactive TUI dashboard. See TUI Dashboard for full documentation.

az prototype launch [--stage {design,build,deploy}]
Parameter Type Default Description
--stage Enum: design, build, deploy Auto-detected Start the TUI at a specific stage instead of auto-detecting.

Examples:

# Launch with auto-detection
az prototype launch

# Launch directly into the build stage
az prototype launch --stage build

prototype design

Run the design stage: an interactive discovery conversation followed by architecture generation. The discovery session uses a joint business-analyst and cloud-architect AI session to gather requirements, identify constraints, and produce an architecture document.

az prototype design [--artifacts <path>]
                    [--context <text>]
                    [--reset]
                    [--interactive]
                    [--status]
                    [--skip-discovery]
Parameter Type Default Description
--artifacts String None Path to directory containing requirement documents, diagrams, or other artifacts.
--context String None Additional context or requirements as free text.
--reset Flag false Reset design state and start fresh.
--interactive, -i Flag false Enter an interactive refinement loop after architecture generation.
--status, -s Flag false Show current discovery status (open items, confirmed items) without starting a session.
--skip-discovery Flag false Skip the discovery conversation and generate architecture directly from existing discovery state.

Examples:

# Start an interactive design session
az prototype design

# Provide artifacts and context upfront
az prototype design --artifacts ./specs --context "Must support 10k concurrent users"

# Check discovery progress without starting a session
az prototype design --status

# Regenerate architecture from existing discovery state
az prototype design --skip-discovery

prototype build

Run the build stage: generates infrastructure-as-code (Bicep or Terraform) and application code based on the design output.

az prototype build [--scope {all,infra,apps,db,docs}]
                   [--dry-run]
                   [--status]
                   [--reset]
                   [--auto-accept]
Parameter Type Default Description
--scope Enum: all, infra, apps, db, docs all What to build.
--dry-run Flag false Preview what would be generated without writing files.
--status, -s Flag false Show current build progress without starting a session.
--reset Flag false Clear existing build state and start fresh.
--auto-accept Flag false Automatically accept the default recommendation for policy violations and standards conflicts.

Examples:

# Run a full build
az prototype build

# Preview what would be generated
az prototype build --dry-run

# Build only infrastructure code
az prototype build --scope infra

# Check build progress
az prototype build --status

prototype deploy

Run the deploy stage: executes infrastructure deployment, application deployment, and output capture. Supports interactive and non-interactive modes, service principal authentication, and cross-tenant deployment.

az prototype deploy [--stage <number>]
                    [--force]
                    [--dry-run]
                    [--status]
                    [--reset]
                    [--tenant <tenant-id>]
                    [--service-principal]
                    [--client-id <id>]
                    [--client-secret <secret>]
                    [--tenant-id <id>]
                    [--outputs]
                    [--rollback-info]
                    [--generate-scripts]
                    [--script-type {webapp,container_app,function}]
                    [--script-rg <name>]
                    [--script-registry <url>]
Parameter Type Default Description
--stage Integer None Deploy only a specific stage number (use --status to see stages).
--force Flag false Force full deployment, ignoring change tracking.
--dry-run Flag false Preview what would be deployed (what-if for Bicep, plan for Terraform).
--status, -s Flag false Show current deploy progress without starting a session.
--reset Flag false Clear deploy state and start fresh.
--tenant String None Azure AD tenant ID for cross-tenant deployment.
--service-principal Flag false Authenticate using a service principal before deploying.
--client-id String None Service principal application/client ID (or set via config).
--client-secret String None Service principal client secret (or set via config).
--tenant-id String None Tenant ID for service principal authentication (or set via config).
--outputs Flag false Show captured deployment outputs from Terraform/Bicep.
--rollback-info Flag false Show rollback instructions based on deployment history.
--generate-scripts Flag false Generate deploy.sh scripts for application directories.
--script-type Enum: webapp, container_app, function webapp Azure deployment target type for --generate-scripts.
--script-rg String None Default resource group name for --generate-scripts.
--script-registry String None Container registry URL for --generate-scripts (container_app type).

Examples:

# Interactive deploy session
az prototype deploy

# Deploy a single stage non-interactively
az prototype deploy --stage 2

# Dry-run preview
az prototype deploy --dry-run

# Deploy with service principal authentication
az prototype deploy --service-principal --client-id <id> --client-secret <secret> --tenant-id <tid>

# Show deployment outputs
az prototype deploy --outputs

# Generate deploy scripts for container apps
az prototype deploy --generate-scripts --script-type container_app --script-registry myregistry.azurecr.io

prototype status

Show overall project status across all stages.

az prototype status [--detailed]
Parameter Type Default Description
--detailed, -d Flag false Show expanded per-stage details.

Examples:

# Quick status overview
az prototype status

# Detailed status with per-stage breakdown
az prototype status --detailed

prototype analyze

Commands for analyzing errors and costs.

prototype analyze error

Analyze an error using the QA engineer agent. Accepts inline error strings, log file paths, or screenshot images.

az prototype analyze error --input <error-input>
Parameter Type Default Description
--input String Required Error input to analyze. Can be an inline error string, path to a log file, or path to a screenshot image.

Examples:

# Analyze an inline error message
az prototype analyze error --input "Error: subscription not registered for Microsoft.ContainerService"

# Analyze a log file
az prototype analyze error --input ./deploy.log

# Analyze a screenshot
az prototype analyze error --input ./error-screenshot.png

prototype analyze costs

Generate a cost analysis report for the prototype's Azure resources.

az prototype analyze costs [--table]
                           [--report]
                           [--refresh]
Parameter Type Default Description
--table Flag false Display only the cost summary table (no file save).
--report Flag false Display the full detailed cost report.
--refresh Flag false Force fresh analysis, bypassing cached results.

Examples:

# Show cost summary table and save full report (default)
az prototype analyze costs

# Show only the summary table (no file save)
az prototype analyze costs --table

# Show full detailed report
az prototype analyze costs --report

# Get machine-readable JSON output
az prototype analyze costs --json

prototype config

Commands for managing project configuration (prototype.yaml and prototype.secrets.yaml).

prototype config init

Initialize project configuration interactively. Creates prototype.yaml with default settings.

az prototype config init

No additional parameters.

Examples:

az prototype config init

prototype config show

Display the current project configuration.

az prototype config show

No additional parameters.

Examples:

az prototype config show

prototype config get

Retrieve a specific configuration value by its dot-separated key path.

az prototype config get --key <key>
Parameter Type Default Description
--key String Required Configuration key to retrieve (dot-separated path, e.g., ai.provider).

Examples:

# Get the current AI provider
az prototype config get --key ai.provider

# Get the project name
az prototype config get --key project.name

prototype config set

Set a configuration value. Sensitive keys (e.g., API keys, subscription IDs) are automatically routed to prototype.secrets.yaml.

az prototype config set --key <key> --value <value>
Parameter Type Default Description
--key String Required Configuration key (dot-separated path, e.g., ai.provider).
--value String Required Configuration value to set.

Examples:

# Set the AI provider
az prototype config set --key ai.provider --value azure-openai

# Set an API key (automatically stored in secrets file)
az prototype config set --key ai.azure_openai.api_key --value sk-abc123

prototype generate

Commands for generating project artifacts from design and build output.

prototype generate backlog

Generate a product backlog from the design output. Supports interactive refinement, push to GitHub Issues or Azure DevOps work items.

az prototype generate backlog [--provider {github,devops}]
                              [--org <org>]
                              [--project <project>]
                              [--table]
                              [--quick]
                              [--refresh]
                              [--status]
                              [--push]
Parameter Type Default Description
--provider Enum: github, devops None Backlog provider: github for GitHub Issues, devops for Azure DevOps work items.
--org String None Organization or owner name (GitHub org/user or Azure DevOps org).
--project String None Project name (Azure DevOps project or GitHub repo).
--table Flag false Display backlog as a table instead of markdown.
--quick Flag false Skip interactive session -- generate, confirm, and push.
--refresh Flag false Force fresh AI generation, bypassing cached items.
--status, -s Flag false Show current backlog state without starting a session.
--push Flag false In quick mode, auto-push after generation.

Examples:

# Interactive backlog generation
az prototype generate backlog

# Quick generation and push to GitHub
az prototype generate backlog --provider github --org myorg --project myrepo --quick --push

# Check backlog status
az prototype generate backlog --status

prototype generate docs

Generate project documentation from design and build output. Produces documents such as architecture decision records, deployment guides, and operations runbooks.

az prototype generate docs [--path <output-dir>]
Parameter Type Default Description
--path String concept/docs/ Output directory for generated documents.

Examples:

# Generate docs in the default location
az prototype generate docs

# Generate docs to a specific directory
az prototype generate docs --path ./docs

prototype generate speckit

Generate a spec-kit bundle containing architecture specifications, design documents, and deployment templates packaged for handoff.

az prototype generate speckit [--path <output-dir>]
Parameter Type Default Description
--path String None Output directory for the spec-kit bundle.

Examples:

# Generate spec-kit in the default location
az prototype generate speckit

# Generate to a specific directory
az prototype generate speckit --path ./handoff

prototype knowledge

Commands for contributing to the shared knowledge base.

prototype knowledge contribute

Submit a knowledge contribution (e.g., a service pattern, pitfall, or new service documentation) to the knowledge base.

az prototype knowledge contribute --service <service>
                                  --description <description>
                                  [--file <path>]
                                  [--draft]
                                  [--type {Service pattern update,New service,Tool pattern,Language pattern,Pitfall}]
                                  [--section <section>]
Parameter Type Default Description
--service String Required Azure service name (e.g., cosmos-db, key-vault).
--description String Required Brief description of the knowledge contribution.
--file String None Path to a file containing the contribution content.
--draft Flag false Preview the contribution without submitting.
--type Enum: Service pattern update, New service, Tool pattern, Language pattern, Pitfall Pitfall Type of knowledge contribution.
--section String None Target section within the knowledge file.

Examples:

# Submit a pitfall for Cosmos DB
az prototype knowledge contribute --service cosmos-db \
  --description "Throughput autoscale requires partition key" \
  --file ./cosmos-pitfall.md

# Preview a contribution without submitting
az prototype knowledge contribute --service key-vault \
  --description "Access policy vs RBAC migration" --draft

# Contribute a new service pattern
az prototype knowledge contribute --service container-apps \
  --description "Dapr sidecar configuration pattern" \
  --type "Service pattern update" --section "Configuration Patterns"

prototype agent

Commands for managing the agent registry. Agents are resolved in priority order: custom, override, then built-in.

prototype agent list

List all registered agents.

az prototype agent list [--show-builtin] [--detailed]
Parameter Type Default Description
--show-builtin Flag true Include built-in agents in the listing.
--detailed, -d Flag false Show expanded capability details for each agent.

Examples:

# List all agents
az prototype agent list

# List with detailed capabilities
az prototype agent list --detailed

prototype agent add

Add a custom agent to the project registry.

az prototype agent add --name <name>
                       [--file <path>]
                       [--definition <builtin-name>]
Parameter Type Default Description
--name String Required Unique name for the custom agent (used as filename and registry key).
--file String None Path to a YAML or Python agent definition file. Mutually exclusive with --definition.
--definition String None Name of a built-in definition to copy as a starting point (e.g., cloud_architect, bicep_agent, terraform_agent). Mutually exclusive with --file.

Examples:

# Add a custom agent from a YAML file
az prototype agent add --name my-agent --file ./my-agent.yaml

# Add a custom agent based on a built-in definition
az prototype agent add --name my-architect --definition cloud_architect

prototype agent override

Override a built-in agent with a custom definition.

az prototype agent override --name <builtin-name> --file <path>
Parameter Type Default Description
--name String Required Name of the built-in agent to override.
--file String Required Path to YAML or Python agent definition file.

Examples:

# Override the cloud architect with a custom definition
az prototype agent override --name cloud-architect --file ./custom-architect.yaml

prototype agent show

Show details for a specific agent.

az prototype agent show --name <name> [--detailed]
Parameter Type Default Description
--name String Required Name of the agent to show details for.
--detailed, -d Flag false Show full system prompt instead of 200-character preview.

Examples:

# Show agent summary
az prototype agent show --name terraform-agent

# Show full system prompt
az prototype agent show --name terraform-agent --detailed

prototype agent remove

Remove a custom agent from the project registry.

az prototype agent remove --name <name>
Parameter Type Default Description
--name String Required Name of the custom agent to remove.

Examples:

az prototype agent remove --name my-agent

prototype agent update

Update properties of a custom agent.

az prototype agent update --name <name>
                          [--description <text>]
                          [--capabilities <list>]
                          [--system-prompt-file <path>]
Parameter Type Default Description
--name String Required Name of the custom agent to update.
--description String None New description for the agent.
--capabilities String None Comma-separated list of capabilities (e.g., architect,deploy).
--system-prompt-file String None Path to a text file containing the new system prompt.

Examples:

# Update description
az prototype agent update --name my-agent --description "Handles network security"

# Update capabilities and system prompt
az prototype agent update --name my-agent \
  --capabilities "architect,deploy,security" \
  --system-prompt-file ./new-prompt.txt

prototype agent test

Test an agent by sending it a prompt and displaying the response.

az prototype agent test --name <name> [--prompt <text>]
Parameter Type Default Description
--name String Required Name of the agent to test.
--prompt String None Test prompt to send to the agent.

Examples:

# Test with a custom prompt
az prototype agent test --name cloud-architect --prompt "Design a 3-tier web app on Azure"

# Test with default prompt
az prototype agent test --name terraform-agent

prototype agent export

Export an agent definition to a YAML file.

az prototype agent export --name <name> [--output-file <path>]
Parameter Type Default Description
--name String Required Name of the agent to export.
--output-file, -f String None Output file path for the exported YAML.

Examples:

# Export to stdout
az prototype agent export --name cloud-architect

# Export to a file
az prototype agent export --name cloud-architect --output-file ./architect.yaml

Home

Getting Started

Stages

Interfaces

Configuration

Agent System

Features

Quality

Help

Governance

Policies — Azure

AI Services

Compute

Data Services

Identity

Management

Messaging

Monitoring

Networking

Security

Storage

Web & App

Policies — Well-Architected

Reliability

Security

Cost Optimization

Operational Excellence

Performance Efficiency

Integration

Anti-Patterns
Standards

Application

IaC

Principles

Transforms

Clone this wiki locally