CLI reference

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

build

Build agent and component containers from the spec.

$
ast build [flags]

Builds the agent container and any custom component images (models, knowledge bases, tools) defined in astroai.yml. Use ast push to build and push in one step.

create

Scaffold a new Astro AI agent project.

$
ast create <name> [flags]

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

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. Add API keys to .env (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 documentation in the terminal.

$
ast docs [category]

Alias: ast doc

explain

Print a human-readable explanation of the agent defined in astroai.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 an OAuth 2.0 Device Authorization Flow. After completing the browser flow, credentials are stored in the system keyring or ~/.astro/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 Astro 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 Astro AI platform.

$
ast push [flags]

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

schema

Print the JSON Schema for astroai.yml to stdout.

$
ast schema

Redirect to a file for use with editor YAML validation:

$
ast schema > .ast/schema.json

VS Code — add to .vscode/settings.json:

1
{ "yaml.schemas": { ".ast/schema.json": "astroai.yml" } }

Inline — add to the top of astroai.yml:

1
# yaml-language-server: $schema=https://<your-server>/schema/astroai.json

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 astroai.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. If the environment variable ASTRO_ACCESS_TOKEN is set, that is reported instead of the stored credential.