CLI reference

Full reference for the ast CLI. See CLI overview for global flags and workflow concepts.

create

Scaffold a new Astropods agent project.

$
ast create <name> [flags]

Creates a new directory named <name> with a scaffolded agent project including astropods.yml, Dockerfile, and starter source code.

configure

Set API keys and credentials for the current project.

$
ast configure [flags]

Interactive wizard to add or update credentials (LLM keys, Slack tokens, etc.) required by astropods.yml. Use this instead of editing .env directly.

dev

Manage the local development environment.

$
ast dev [subcommand] [flags]

Running ast dev with no subcommand starts the dev environment.

Subcommands

start

Start local dev containers with hot-reload.

$
ast dev start [flags]

Edit your agent source and it restarts automatically. Run ast configure to set API keys (e.g. ANTHROPIC_API_KEY).

logs

Tail container logs.

$
ast dev logs [service]

service defaults to agent. Pass a service name (e.g. astro-messaging) to tail a specific container.

stop

Stop and remove dev containers.

$
ast dev stop

docs

Display Astro AI documentation in the terminal.

$
ast docs [category]

Alias: ast doc

explain

Print a human-readable explanation of the agent defined in astropods.yml.

$
ast explain [flags]

Uses the global --file flag to locate the spec. Useful for quickly understanding what an agent does and how it is configured.

login

Authenticate with the Astro AI platform.

$
ast login [flags]

Initiates Authorization Flow. After completing the browser flow, credentials are stored in the system keyring or ~/.ast/credentials.json. See Authentication for details.

logout

Clear stored credentials.

$
ast logout [flags]

Without --all, clears credentials for the current profile only.

playground

Open the Astropods playground UI connected to a running agent.

$
ast playground <url> [flags]

<url> is the base URL of the agent’s messaging HTTP API (e.g. http://localhost:3100).

Starts a local playground container and opens it in the browser, connected to the agent at <url>.

push

Build and push the agent to the Astropods registry.

$
ast push [flags]

By default, push builds containers, pushes images to the Astropods registry, and registers the agent spec with the server. Requires an account and ast login first.

upgrade

Upgrade the CLI to the latest version.

$
ast upgrade [flags]

Downloads the latest binary from the Astro AI server and replaces the current installation.

validate

Validate astropods.yml against the spec schema.

$
ast validate [flags]

Checks YAML syntax, JSON schema conformance, and semantic rules (required fields, mutual exclusions, etc.). Uses the global --file flag to locate the spec.

Exit code 0 on success, non-zero on validation failure — suitable for use in CI.

whoami

Display the currently authenticated user.

$
ast whoami

Prints the user name, email, account, user ID, and token expiration.