CLI automation parity with Dashboard/MCP

[davidfowl]

Summary

The CLI lacks several commands available in MCP/Dashboard that are essential for end-to-end automation, diagnostics, and scripting - including AI agent-led workflows.

Community POC

See #13727 for a community proof-of-concept implementing some of these features.

Current Commands (aspire 13.2)

Command	Description
aspire new	Create a new Aspire project.
aspire init	Initialize Aspire support in an existing solution or create a single-file AppHost.
aspire run	Run an Aspire apphost in development mode.
aspire stop	Stop a running Aspire apphost.
aspire ps	List running Aspire apphosts.
aspire resources	Display resource snapshots from a running Aspire apphost.
aspire logs	Display logs from resources in a running Aspire apphost.
aspire add	Add a hosting integration to the Aspire AppHost.
aspire publish	Generates deployment artifacts for an Aspire apphost. (Preview)
aspire config	Manage configuration settings.
aspire cache	Manage disk cache for CLI operations.
aspire doctor	Diagnose Aspire environment issues and verify setup
aspire deploy	Deploy the contents of an Aspire apphost to its defined deployment targets. (Preview)
aspire do	Execute a specific pipeline step and its dependencies. (Preview)
aspire update	Update integrations in the Aspire project. (Preview)
aspire agent	Manage AI agent integrations.
aspire telemetry	View telemetry data (logs, spans, traces) from a running Aspire application.
aspire sdk	Commands for generating SDKs for building Aspire integrations in other languages.

Telemetry Subcommands

Command	Description
aspire telemetry logs [resource]	View structured logs from the Dashboard telemetry API.
aspire telemetry spans [resource]	View spans from the Dashboard telemetry API.
aspire telemetry traces [resource]	View traces from the Dashboard telemetry API.

Telemetry Options:

• --format <json|table> - Output format
• -n, --limit <count> - Maximum number of items to return
• --trace-id <id> - Filter by trace ID
• -f, --follow - Stream telemetry in real-time (logs, spans only)
• --severity <level> - Filter logs by minimum severity (logs only)
• --has-error - Filter by error status (spans, traces only)

Proposed Commands (Remaining)

Command	Description	MCP Equivalent
aspire command <resource> <command>	Execute predefined resource commands (start/stop/restart/custom)	aspire-execute_resource_command
aspire docs list	List all available Aspire documentation pages from aspire.dev	aspire-list_docs
aspire docs search <query>	Search Aspire documentation using keyword-based lexical search	aspire-search_docs
aspire docs get <slug>	Retrieve full content of a specific documentation page by slug	aspire-get_doc
aspire wait	Wait for resource state (new)	-
aspire secret	Set/get/list parameter values for dev (like dotnet user-secrets)	-

Docs Subcommands (Proposed)

Command	Description
aspire docs list	List all available Aspire documentation pages with titles, slugs, and summaries.
aspire docs search <query>	Search documentation by keywords. Returns ranked results with matched snippets.
aspire docs get <slug>	Retrieve full content of a documentation page. Use --section <heading> to get a specific section.

Docs Options:

• --format <json|markdown> - Output format (default: markdown)
• -n, --limit <count> - Maximum number of search results (default: 5, max: 10)
• --section <heading> - Filter to a specific section (get only)

Example Usage:

# List all documentation pages
aspire docs list

# Search for Redis integration docs
aspire docs search "redis integration"

# Get full Redis integration page
aspire docs get redis-integration

# Get just the configuration section
aspire docs get redis-integration --section "Configuration"

# Output as JSON for scripting
aspire docs search "health checks" --format json

Proposed Global Flag

--format json for machine-readable output on:

• aspire ps ✅
• aspire resources ✅
• aspire logs ✅
• aspire telemetry logs ✅ (13.2)
• aspire telemetry spans ✅ (13.2)
• aspire telemetry traces ✅ (13.2)
• aspire doctor ✅
• aspire command (proposed)
• aspire docs (proposed)
• aspire wait (proposed)

---

Automation Scenarios

Lifecycle & Discovery

Scenario	Command
Find where the apphost is running	aspire ps --format json
Start the apphost in background	aspire run --detach
Stop the apphost	aspire stop
Restart a specific resource	aspire command api restart
Stop a specific resource	aspire command redis resource-stop

Waiting & Health

Scenario	Command
Wait for all resources to be running	aspire wait --all --state Running --timeout 120
Wait for specific resource to be healthy	aspire wait api --state Healthy --timeout 60
Check if any resources failed	aspire resources --format json | jq ".[] | select(.state == \"Failed\")"

Documentation & Learning

Scenario	Command
Find docs about a topic	aspire docs search "connection strings"
Get full integration guide	aspire docs get postgres-integration
List all available docs	aspire docs list --format json

Debugging & Tracing

Scenario	Command
View distributed traces	aspire telemetry traces --format json
Find traces with errors	aspire telemetry traces --has-error --format json
Get structured logs for a trace	aspire telemetry logs --trace-id <id> --format json
View structured logs for a resource	aspire telemetry logs api --format json
Filter structured logs by level	aspire telemetry logs api --severity Error
Stream logs in real-time	aspire telemetry logs --follow
Stream spans in real-time	aspire telemetry spans --follow
View raw console logs	aspire logs api

Parameters & Secrets

Scenario	Command
Set a parameter value	aspire secret set postgres-password "mysecret"
List configured parameters	aspire secret list
Get a parameter value	aspire secret get postgres-password

Endpoint Discovery

Scenario	Command
Get endpoint URL for a resource	aspire resources --format json | jq -r ".[] | select(.name == \"api\") | .endpoints[0].url"
List all running resources	aspire resources --format json

Environment Validation

Scenario	Command
Validate environment before deploy	aspire doctor --format json
Check for doctor failures	aspire doctor --format json | jq ".[] | select(.status == \"fail\")"

---

AI Agent-Led Automation Scenarios

These scenarios enable AI coding agents (Copilot, Claude, etc.) to autonomously diagnose, debug, and fix issues.

Agent: Diagnose Why a Resource Failed

# Agent checks resource state
aspire resources --format json

# Agent sees "api" is in Failed state, gets structured logs
aspire telemetry logs api --severity Error --format json

# Agent analyzes error, identifies missing connection string
# Agent fixes appsettings.json and restarts
aspire command api restart
aspire wait api --state Running --timeout 30

Agent: Learn About Aspire Features

# Agent needs to understand health checks
aspire docs search "health checks"

# Agent reads the full documentation
aspire docs get health-checks

# Agent implements health checks based on documentation

Agent: Investigate Slow Endpoint

# Agent finds slow traces
aspire telemetry traces --format json | jq ".[] | select(.durationMs > 1000)"

# Agent gets structured logs correlated to slow trace
aspire telemetry logs --trace-id <id> --format json

# Agent identifies slow database query in logs
# Agent optimizes query and restarts service
aspire command api restart

Agent: Validate Fix After Code Change

# Agent made a code change, rebuilds and waits
aspire wait api --state Running --timeout 60

# Agent verifies no errors in structured logs since restart
aspire telemetry logs api --severity Error --format json

# Agent checks endpoint works
curl $(aspire resources --format json | jq -r ".[] | select(.name == \"api\") | .endpoints[0].url")/health

Agent: Root Cause Analysis Across Services

# User reports: "checkout is broken"
# Agent finds traces with errors in checkout flow
aspire telemetry traces --has-error --format json | jq ".[] | select(.resources | contains([\"checkout\"]))"

# Agent gets structured logs for the trace
aspire telemetry logs --trace-id <id> --format json

# Agent sees: checkout -> inventory -> postgres (connection refused)
# Agent checks postgres status
aspire resources --format json | jq ".[] | select(.name == \"postgres\")"

# Agent restarts postgres
aspire command postgres restart
aspire wait postgres --state Healthy --timeout 30

---

Development Scenarios

Debug Why Endpoint Returns 500

# Dev: "GET /orders returns 500, no idea why"

# Agent hits endpoint
curl http://localhost:5000/orders

# Agent finds the trace
aspire telemetry traces --has-error --format json | jq ".[-1]"

# Agent gets correlated logs
aspire telemetry logs --trace-id abc123 --format json
# → NullReferenceException at OrderService.cs:42 - _repository was null

# Agent sees: missing DI registration
# Agent adds services.AddScoped<IOrderRepository>() to Program.cs
aspire command api restart

# Agent verifies
curl http://localhost:5000/orders
# → 200 OK

Auto-Fix Database Migration Error

# Agent sees migration failure
aspire telemetry logs api --severity Error --format json
# → "Invalid column name CustomerId"

# Agent checks the model, sees missing migration
# Agent generates migration
dotnet ef migrations add AddCustomerId --project src/Api

# Agent restarts to apply
aspire command api restart
aspire wait api --state Healthy

# Agent verifies
aspire telemetry logs api --severity Error --format json  # empty
git add . && git commit -m "Add missing CustomerId migration"

---

CI Scenarios

Integration Test Gate

# GitHub Actions / Azure Pipelines
- name: Run Aspire App
  run: |
    aspire run --detach --project ./AppHost
    aspire wait --all --state Running --timeout 180

- name: Run Integration Tests
  run: dotnet test ./tests/IntegrationTests

- name: Collect Failure Logs
  if: failure()
  run: |
    aspire telemetry logs --severity Error --format json > error-logs.json
    aspire telemetry traces --has-error --format json > failed-traces.json

- name: Cleanup
  if: always()
  run: aspire stop

Smoke Test on PR

- name: Start App
  run: |
    aspire run --detach
    aspire wait --all --state Running --timeout 120

- name: Smoke Test All Endpoints
  run: |
    aspire resources --format json | jq -r ".[].endpoints[]?.url" | while read url; do
      echo "Testing $url/health"
      curl -sf "$url/health" || exit 1
    done

- name: Check No Startup Errors
  run: |
    ERRORS=$(aspire telemetry logs --severity Error --format json | jq length)
    if [ "$ERRORS" -gt 0 ]; then
      echo "❌ Found $ERRORS startup errors"
      aspire telemetry logs --severity Error --format json
      exit 1
    fi

- name: Cleanup
  if: always()
  run: aspire stop

---

Impact

These additions enable:

1. CI/CD automation - Script resource lifecycle, wait for health, gate on failures
2. CLI-based debugging - Trace requests across services without Dashboard
3. Headless operation - Full control in SSH/container/remote environments
4. AI agent workflows - Agents can diagnose, debug, and fix issues autonomously
5. Integration with tools - Pipe JSON to jq, forward to logging systems, build custom dashboards
6. Development inner loop - Stay in terminal/editor, no context switching to Dashboard
7. Documentation access - Query Aspire docs directly from CLI for learning and reference

[JamesNK]

Missing structured logs. AI is confusing console logs = structured logs and thinking they're already done.

I don't think we need aspire trace-logs. The trace ID can be an argument on aspire structured-logs to filter results.

[Hona]

Unsure if it is in the spec already, but a few things missing from MCP that I hope are part of the new CLI:

• standalone dashboard support (no apphost) - old PoC for MCP
• getting attributes from OTEL on structured logging and spans (e.g. key info like IDs not in the message may be here)

[davidfowl]

standalone dashboard support (no apphost) - old PoC for MCP

Not yet, we don't have a good story here yet, but will take it as feedback and think about how to land it.

[Hona]

Perhaps a good story is as an Azure developer accessing Aspire dashboard instances from the cloud?
Pointing an agent to a cloud standalone(?) dashboard for an App Service could be nice.
Solves the local+Azure story together

[davidfowl]

There's nothing baked into our CLI that has anything to do with azure. We'd need to build an extensibility model for that.