> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# ast env

An environment is where one agent of a blueprint runs in the active account. Each environment has its own variables and secrets, which override the account's values with the same name. Deleting the agent keeps the environment and its values, ready for the next deploy. Aliases: `ast envs`, `ast environment`, `ast environments`.

```bash
ast env <subcommand> [--blueprint <name>]
```

Every subcommand works on one blueprint. Pass `--blueprint` (`-b`), or run the command in the blueprint's project directory, where the CLI reads the name from `astropods.yml`.

Environments are available for private blueprints only.

## env list

```bash
ast env list [--json]
```

Lists the blueprint's environments with each one's agent, status, and variable and secret counts. An environment with no agent shows as `empty`.

## env create

```bash
ast env create <name>
```

Creates an empty environment. Deploy into it with `ast deploy --env <name>`.

## env rename

```bash
ast env rename <name> <new-name>
```

A name is unique per blueprint in an account.

## env delete

```bash
ast env delete <name> [--confirm <name>]
```

Deletes an environment and its variables and secrets. An environment that has an agent can't be deleted: delete the agent first with `ast agent delete --env <name>`. Prompts for confirmation. Pass `--confirm` with the environment name to skip the prompt.

## Deploy into an environment

```bash
ast deploy --env staging
```

`--env` names an environment with no agent. Without it, a deploy uses the blueprint's oldest environment that has no agent, or creates a new one named `main`, `main-2`, and so on. Either way, the deploy prints the environment it used. A redeploy stays in its environment.

## Environment variables and secrets

Pass `--env` to any [`ast secrets`](/cli/secrets) subcommand to work on an environment's values instead of the account's:

```bash
ast secrets create API_KEY --env staging
ast secrets list --env staging
```

At deploy time, a `--var KEY=@NAME` reference resolves from the environment first, then from the account.

## Target an agent by environment

An environment holds at most one agent, so `--env` picks exactly one. The blueprint comes from `--blueprint` or `astropods.yml`, as above. Every [`ast agent`](/cli/agent) command that acts on one agent accepts it in place of `--name` or `--id`:

```bash
ast agent logs --env main
ast agent redeploy --env staging --latest
```

## Next steps

* [ast secrets](/cli/secrets): manage account and environment values
* [ast agent](/cli/agent): manage the agent in an environment
* [ast blueprint](/cli/blueprint): deploy a blueprint