Add environment management commands (`aspire env new/list/select/set`)
- Dominant language
- C#
- Stars
- 6.3k
- Forks
- 991
- Avg merge
- 2d 15h
- Merged PRs (30d)
- 196
Description
## Problem
When deploying the same application to multiple environments (dev, staging, production), teams need isolated configuration and deployment state per environment. Today, `aspire deploy --environment staging` passes the environment name as a string to the AppHost, but there is no CLI-managed state separation — no way to store per-environment parameters, track what was deployed to each environment, or switch between environments.
Developers deploying to multiple targets must manually manage configuration differences, re-enter parameters each time, and have no visibility into what state each environment is in.
## Current State
- `--environment` on deploy/publish is a pass-through flag with no managed lifecycle
- `IDeploymentStateManager` stores per-environment state files internally, but this is not exposed through CLI commands
- Parameters must be re-entered on every deployment (no per-environment persistence beyond the state manager)
- No way to list, compare, or switch between environments
## Proposed Experience
```bash
# Create a new named environment
aspire env new staging
# List all environments (* marks active)
aspire env list
# dev
# staging *
# production
# Switch active environment
aspire env select production
# Set a parameter value for the current environment
aspire env set DB_SKU P1
aspire env set AZURE_LOCATION westus2
# View all resolved values for the current environment
aspire env get-values
# AZURE_LOCATION=westus2
# DB_SKU=P1
# Azure__SubscriptionId=12345...
# Deploy uses active environment's config + state
aspire deploy
# Override environment for a single command without switching
aspire deploy --environment staging
```
## Why This Matters
- **Team workflows** — Multiple developers deploying to shared staging/prod environments need consistent, isolated configuration per target
- **CI/CD pipelines** — Different pipeline stages target different environments with different parameters (regions, SKUs, secrets)
- **Parameter persistence** — Users should not re-enter subscription ID, location, and resource group on every deploy. Once set for an environment, they should persist.
- **Deployment state isolation** — Knowing what was deployed to staging vs production prevents accidental cross-environment operations
- **Complements #16090** — First-class parameters become much more useful when they persist per-environment rather than being entered every time
## Implementation Notes
The internal infrastructure largely exists:
- **`IDeploymentStateManager`** already stores per-environment JSON state files with optimistic concurrency control and section-based storage
- **`aspire.config.json`** has a profiles system that could be extended or paralleled for environment configuration
- **Pipeline steps** already receive environment context — the state manager namespaces by environment
The main work is:
1. **CLI commands** — `aspire env new`, `list`, `select`, `set`, `get-values` (thin wrappers over existing state infrastructure)
2. **Active environment tracking** — Store the currently selected environment in local config (similar to how profiles work)
3. **Parameter flow** — Parameters set via `aspire env set` should be automatically provided to the pipeline, reducing interactive prompts
4. **State directory convention** — Define where per-environment state lives (e.g., `.aspire/environments//`)
## Design Questions
- Should environment state live in the project directory (`.aspire/environments/`) or in the user config directory?
- How does `aspire env set` interact with the parameter system in #16090? Should `--set` values on the CLI override persisted environment values?
- Should `aspire env get-values` show both user-set parameters AND computed deployment outputs (resource IDs, endpoints)?
- Can environments be shared across team members (e.g., committed to source control or stored remotely)?
## Related Issues
- #16090 — Improve parameter experience during deployment (persisted env values reduce prompting friction)
- #14830 — Multi-pipeline deployment state (per-environment state enables pipeline-to-pipeline state transfer)
- #16063 — Unified resource introspection (environment context determines which deployed instance to introspect)
Contributor guide
Assessment
This issue has not been assessed yet.