Create a clearer get started pathway
- Dominant language
- Go
- Stars
- 569
- Forks
- 364
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 136
Description
## Current experience
When an AI agent (e.g., Copilot, Amp) is asked to **create a new azd project from scratch** — such as *"Create an azd project that deploys a container app"* — it fails because azd does not provide a clear, agent-friendly pathway for greenfield project creation.
### What the agent experiences
1. **No way to discover or select starter templates programmatically.** `azd init --template` requires the user (or agent) to already know the template name/URL. There is no non-interactive CLI command that returns a curated list of **starter** templates with metadata (e.g., tags like `container-app`, `function-app`, `web-app`) that an agent can filter and select from.
2. **`azd add` is interactive-only.** The compose workflow (`azd add`) prompts the user to select components via an interactive console UI. There is no `--non-interactive` JSON/flag-based equivalent that an agent could call to add a service or resource to a project.
### Root issues
- **No template discovery for agents.** `azd template list` exists as a CLI command but the output isn't structured for programmatic consumption with filtering by use-case (e.g., "container apps", "functions", "static web apps"). Agents have no way to discover which templates are available or which ones are recommended starters.
- **No non-interactive `azd add`.** The compose workflow can't be driven programmatically.
## Proposed solutions
### Option A: Bake starter templates directly into `azd init`
Support well-known starter template names as a positional argument to `azd init`:
```bash
azd init containerapp
azd init functionapp
azd init webapp
azd init staticwebapp
```
Each name maps to a curated starter template. This is simple, discoverable (agents and users can see the list via `azd init --list-starters` or help text), and requires no prior knowledge of template URLs.
This would let an agent handle: *"Create an azd project that deploys a container app"* → `azd init containerapp --environment myenv` — a single, non-interactive command.
### Option B: Non-interactive `azd add`
Generalize `azd add` as the single command for adding anything to an azd project — not just resources, but services, hooks, extensions, etc. The root namespace maps directly to the top-level keys in `azure.yaml` (`resources`, `services`, `hooks`, `extensions`, `pipeline`), and the dotted path drills into the type.
#### Example syntax
```bash
# Resources
azd add resource --type host.containerapp --input '{"name":"myapi","language":"python","port":8080}'
azd add resource --type db.postgres --input '{"name":"mydb"}'
azd add resource --type ai.openai.model --input '{"name":"gpt4","model":"gpt-4o","version":"2024-08-06"}'
# Services (linked to a host resource)
azd add service --type containerapp --input '{"name":"web","host":"containerapp","language":"python","project":"./src/web"}'
# Extensions
azd add extension --input '{"name":"ai","source":"github.com/Azure/azd-extensions/ai"}'
# Hooks
azd add hook --type preprovision --input '{"run":"./scripts/setup.sh"}'
```
## Impact
- **Who is affected:** Any AI agent or automation trying to use azd for new project creation.
- **Severity:** High — this is one of the most common first interactions ("help me get started on Azure"), and it fails completely for agents.
- **Workaround:** The agent must have pre-baked knowledge of template URLs, which is less ideal and doesn't scale well.
## Environment
- `azd` version: latest (main branch)
- Agent: Any AI coding agent (Copilot, etc.)
Contributor guide
Assessment
This issue has not been assessed yet.