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

# CLI

## Docs

- [ast project](https://docs.astropods.com/cli/project.md): Create an agent harness and run it locally
- [ast blueprint](https://docs.astropods.com/cli/blueprint.md): Build, push, deploy, and manage blueprints in the registry
- [ast agent](https://docs.astropods.com/cli/agent.md): Inspect, control, and remove deployed agents
- [ast eval](https://docs.astropods.com/cli/eval.md): Activate evaluators, evaluate traces, and save human reviews
- [ast dataset](https://docs.astropods.com/cli/dataset.md): Inspect and curate an agent's evaluation dataset
- [ast env](https://docs.astropods.com/cli/env.md): Manage where a blueprint's agents run and the values each one uses
- [ast secrets](https://docs.astropods.com/cli/secrets.md): Store and manage account and environment variables and secrets
- [ast knowledge](https://docs.astropods.com/cli/knowledge.md): Connect and manage the account's knowledge stores
- [ast account](https://docs.astropods.com/cli/account.md): List the accounts you belong to and switch the active one
- [ast spec](https://docs.astropods.com/cli/spec.md): Validate astropods.yml against the spec schema
- [ast settings](https://docs.astropods.com/cli/settings.md): Control telemetry and install shell completions
- [Top-level commands](https://docs.astropods.com/cli/top-level.md): Session, upgrade, and documentation commands that take no subcommand


> **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page.

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

# CLI overview

The Astropods CLI (`ast`) is the primary tool for working with agents locally and publishing them to the Astropods platform. It handles creating agent harnesses, local development, building containers, deploying to the registry, and managing running agents.

## Installation

See [Install the CLI](/install-cli) for platform-specific installation instructions.

Verify your installation:

```bash
ast --version
```

## Configuration file

Most commands read `astropods.yml` in the current directory. This file defines your agent's spec: its name, interface, models, tools, knowledge bases, and other configuration.

## Global flags

These flags are available on all commands:

| Flag        | Short | Description                  |
| ----------- | ----- | ---------------------------- |
| `--verbose` | `-v`  | Verbose output               |
| `--quiet`   | `-q`  | Minimal output               |
| `--version` |       | Print the CLI version        |
| `--help`    | `-h`  | Help for the current command |

## Workflow overview

A typical workflow from zero to a deployed agent:

1. **[`ast project create`](/cli/project#project-create)**: create a new agent harness
2. **[`ast project configure`](/cli/project#project-configure)**: set required credentials and variables
3. **[`ast project start`](/cli/project#project-start)**: run the agent locally with hot-reload
4. **[`ast spec validate`](/cli/spec#spec-validate)**: check `astropods.yml` for errors
5. **[`ast push`](/cli/blueprint#blueprint-push)**: build and push a blueprint to the registry
6. **[`ast blueprint deploy`](/cli/blueprint#blueprint-deploy)**: deploy the blueprint as a live hosted agent

Authentication is handled separately with [`ast login`](/cli/top-level#login).

## Command groups

| Group                                | Description                                                         |
| ------------------------------------ | ------------------------------------------------------------------- |
| [`ast project`](/cli/project)        | Local development: create, configure, start, stop, logs             |
| [`ast blueprint`](/cli/blueprint)    | Registry: build, push, deploy, list, get                            |
| [`ast agent`](/cli/agent)            | Running agents: list, pause, resume, logs, redeploy, delete         |
| [`ast env`](/cli/env)                | Environments: list, create, rename, delete                          |
| [`ast secrets`](/cli/secrets)        | Account and environment vault: create, list, update, delete, import |
| [`ast knowledge`](/cli/knowledge)    | Knowledge stores: connect, list, status, credentials, delete        |
| [`ast account`](/cli/account)        | Account management: list, switch                                    |
| [`ast spec`](/cli/spec)              | Spec tools: validate                                                |
| [`ast settings`](/cli/settings)      | CLI settings: telemetry, shell completions                          |
| [Top-level commands](/cli/top-level) | `login`, `logout`, `whoami`, `upgrade`, `docs`                      |

## All commands

| Command                                                             | Description                                                         |
| ------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [`ast project create`](/cli/project#project-create)                 | Create a new agent project                                          |
| [`ast project configure`](/cli/project#project-configure)           | Configure project credentials and inputs                            |
| [`ast project start`](/cli/project#project-start)                   | Start the project's containers                                      |
| [`ast project stop`](/cli/project#project-stop)                     | Stop the project's containers                                       |
| [`ast project logs`](/cli/project#project-logs)                     | Tail container logs                                                 |
| [`ast project trigger`](/cli/project#project-trigger)               | Run a job now                                                       |
| [`ast blueprint list`](/cli/blueprint#blueprint-list)               | List blueprints in the active account                               |
| [`ast blueprint get`](/cli/blueprint#blueprint-get)                 | Get a blueprint's metadata and config                               |
| [`ast blueprint build`](/cli/blueprint#blueprint-build)             | Build the blueprint image                                           |
| [`ast blueprint push`](/cli/blueprint#blueprint-push)               | Push the blueprint image to the registry                            |
| [`ast blueprint deploy`](/cli/blueprint#blueprint-deploy)           | Deploy a blueprint as a new agent                                   |
| [`ast blueprint set`](/cli/blueprint#blueprint-set)                 | Update blueprint settings                                           |
| [`ast blueprint archive`](/cli/blueprint#blueprint-archive)         | Archive a blueprint                                                 |
| [`ast env list`](/cli/env#env-list)                                 | List a blueprint's environments                                     |
| [`ast env create`](/cli/env#env-create)                             | Create an empty environment                                         |
| [`ast env rename`](/cli/env#env-rename)                             | Rename an environment                                               |
| [`ast env delete`](/cli/env#env-delete)                             | Delete an environment with no agent, and its variables and secrets  |
| [`ast agent list`](/cli/agent#agent-list)                           | List deployed agents in the active account                          |
| [`ast agent get`](/cli/agent#agent-get)                             | Get details for a deployed agent                                    |
| [`ast agent pause`](/cli/agent)                                     | Pause a running agent                                               |
| [`ast agent resume`](/cli/agent)                                    | Resume a paused agent                                               |
| [`ast agent redeploy`](/cli/agent#agent-redeploy)                   | Redeploy an existing agent                                          |
| [`ast agent restart`](/cli/agent#agent-restart)                     | Restart a running agent                                             |
| [`ast agent trigger`](/cli/agent#agent-trigger)                     | Run a job now                                                       |
| [`ast agent logs`](/cli/agent#agent-logs)                           | Fetch logs for a deployed agent                                     |
| [`ast agent history`](/cli/agent#agent-history)                     | List an agent's deployment history                                  |
| [`ast agent trace`](/cli/agent#agent-trace)                         | List traces or show a single trace                                  |
| `ast agent network`                                                 | Show an agent's inbound, outbound, and database network traffic     |
| `ast agent usage`                                                   | Show an agent's traces, model spend, and compute                    |
| [`ast agent delete`](/cli/agent#agent-delete)                       | Delete a deployed agent                                             |
| [`ast secrets list`](/cli/secrets#secrets-list)                     | List variables and secrets                                          |
| [`ast secrets get`](/cli/secrets#secrets-get)                       | Get details for a variable or secret                                |
| [`ast secrets create`](/cli/secrets#secrets-create)                 | Create a variable or secret                                         |
| [`ast secrets update`](/cli/secrets#secrets-update)                 | Update a variable's or secret's value                               |
| [`ast secrets delete`](/cli/secrets#secrets-delete)                 | Delete a variable or secret                                         |
| [`ast secrets import`](/cli/secrets#secrets-import)                 | Import variables from a file such as `.env`                         |
| [`ast knowledge connect`](/cli/knowledge#knowledge-connect)         | Connect a database as a knowledge store                             |
| [`ast knowledge list`](/cli/knowledge#knowledge-list)               | List knowledge stores                                               |
| [`ast knowledge status`](/cli/knowledge#knowledge-status)           | Get a knowledge store's status                                      |
| [`ast knowledge credentials`](/cli/knowledge#knowledge-credentials) | Print a knowledge store's credentials                               |
| [`ast knowledge delete`](/cli/knowledge#knowledge-delete)           | Delete a knowledge store                                            |
| [`ast account list`](/cli/account#account-list)                     | List accounts you belong to                                         |
| [`ast account switch`](/cli/account#account-switch)                 | Set the active account                                              |
| `ast billing get`                                                   | Get plan, spend, remaining credit, and spend controls               |
| `ast billing status`                                                | Get the active account's billing gating status                      |
| `ast billing invoices`                                              | List the active account's invoices                                  |
| `ast billing set`                                                   | Set the account's spend warning and limit                           |
| `ast billing agents`                                                | Break down compute spend by agent                                   |
| `ast billing models`                                                | Break down AI Gateway spend by model, or one model's spend by agent |
| [`ast eval push`](/cli/eval#eval-push)                              | Activate the agent's `EVALUATION.yaml` as its evaluation set        |
| [`ast eval validate`](/cli/eval#eval-validate)                      | Validate `EVALUATION.yaml` without activating it                    |
| [`ast eval get`](/cli/eval#eval-get)                                | Show a blueprint's active evaluators                                |
| [`ast eval status`](/cli/eval#eval-status)                          | Show evaluation progress for a deployment                           |
| [`ast eval run`](/cli/eval#eval-run)                                | Queue evaluations for a deployment's traces                         |
| [`ast eval review`](/cli/eval#eval-review)                          | Save a human review for one trace                                   |
| [`ast dataset list`](/cli/dataset#dataset-list)                     | List the account's datasets                                         |
| [`ast dataset get`](/cli/dataset#dataset-get)                       | Show a dataset's item count and evaluator values                    |
| [`ast dataset items`](/cli/dataset#dataset-items)                   | List a dataset's items                                              |
| [`ast dataset add`](/cli/dataset#dataset-add)                       | Add a trace to a dataset                                            |
| [`ast dataset edit`](/cli/dataset#dataset-edit)                     | Replace a dataset item's evaluator values                           |
| [`ast dataset remove`](/cli/dataset#dataset-remove)                 | Remove a trace from a dataset                                       |
| [`ast dataset download`](/cli/dataset#dataset-download)             | Save a dataset as a zip of JSONL                                    |
| [`ast spec validate`](/cli/spec#spec-validate)                      | Validate `astropods.yml` against the spec schema                    |
| [`ast settings update`](/cli/settings#settings-update)              | Update CLI settings                                                 |
| [`ast settings bash`, `zsh`, `fish`, `powershell`](/cli/settings)   | Generate a shell completion script                                  |
| [`ast login`](/cli/top-level#login)                                 | Authenticate with Astropods                                         |
| [`ast logout`](/cli/top-level#logout)                               | Log out from Astropods                                              |
| [`ast whoami`](/cli/top-level#whoami)                               | Display the authenticated user                                      |
| [`ast upgrade`](/cli/top-level#upgrade)                             | Upgrade the CLI to the latest version                               |
| [`ast docs`](/cli/top-level#docs)                                   | Display Astropods documentation                                     |

## Next steps

* [Your first project](/get-started): step-by-step local development guide
* [Your first blueprint](/blueprints): build and push to the registry
* [Deploy your first agent](/deploy-agent): run a blueprint as a live agent