> 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 full documentation content, see https://docs.astropods.com/llms-full.txt.

# CLI overview

The Astro AI CLI (`ast`) is the primary tool for working with agents locally and publishing them to the Astro AI 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-reference#project-create)**: create a new agent harness
2. **[`ast project configure`](/cli-reference#project-configure)**: set required credentials and variables
3. **[`ast project start`](/cli-reference#project-start)**: run the agent locally with hot-reload
4. **[`ast spec validate`](/cli-reference#spec-validate)**: check `astropods.yml` for errors
5. **[`ast push`](/cli-reference#blueprint-push)**: build and push a blueprint to the registry
6. **[`ast blueprint deploy`](/cli-reference#blueprint-deploy)**: deploy the blueprint as a live hosted agent

Authentication is handled separately with [`ast login`](/authentication).

## Command groups

| Group           | Description                                                 |
| --------------- | ----------------------------------------------------------- |
| `ast project`   | Local development: create, configure, start, stop, logs     |
| `ast blueprint` | Registry: push, deploy, list, get                           |
| `ast agent`     | Running agents: list, pause, resume, logs, redeploy, delete |
| `ast secrets`   | Account vault: create, list, update, delete, import         |
| `ast account`   | Account management: list, switch                            |
| `ast spec`      | Spec tools: validate, explain                               |
| `ast settings`  | CLI settings: telemetry, shell completions                  |

## Next steps

* [CLI reference](/cli-reference): full command and flag documentation
* [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