CLI reference

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

account

Manage accounts. All platform resources are scoped to the active account.

$
ast account <subcommand>

account list

List all accounts you belong to. The active account is marked with a check.

$
ast account list

account switch

Set the active account. Omit the name for an interactive selector. Use - to switch back to the previously active account.

$
ast account switch [name]
$
ast account switch -

agent

Manage deployed agents in the active account.

$
ast agent <subcommand>

agent list

$
ast agent list [--json]

agent get

$
ast agent get <name> [--json]

agent pause / resume

$
ast agent pause <name> [--id <deployment-id>]
$
ast agent resume <name> [--id <deployment-id>]

agent redeploy

Re-deploy an existing agent in-place. Accepts the same --adapter, --var, --vars-file, --build, --dry-run, and --json flags as blueprint deploy. If --adapter is omitted, the adapter defaults to web; pass --adapter explicitly to preserve or change a non-web setup.

$
ast agent redeploy <name> [flags]

agent restart

$
ast agent restart <name> --component agent [--id <deployment-id>]

agent logs

$
ast agent logs <name> --container app|messaging [--tail] [--id <deployment-id>]

--tail streams logs continuously after fetching the last 15 minutes.

agent delete

$
ast agent delete <name> [--confirm <name>]

Prompts for confirmation. Pass --confirm <name> to skip the prompt.

agent history

$
ast agent history <name> [--json]

blueprint

Manage blueprints in the active account.

$
ast blueprint <subcommand>

blueprint list

$
ast blueprint list [--json]

blueprint get

$
ast blueprint get <name> [--json] [--card]

--card shows the agent description.

blueprint deploy

Deploy a blueprint as a new agent. Alias: ast deploy <name>.

$
ast blueprint deploy <name> [flags]
$
ast deploy <name> [flags]

blueprint build

Build the container image for a blueprint. Alias: ast build.

$
ast blueprint build [name] [flags]
$
ast build [name] [flags]

If [name] is omitted, the name is read from astropods.yml.

blueprint push

Build and push to the registry. Alias: ast push.

$
ast blueprint push [name] [flags]
$
ast push [name] [flags]

The [name] argument sets the blueprint name in the registry and overrides the name field in astropods.yml. If omitted, the name is read from astropods.yml.

blueprint archive

Archive a blueprint so it no longer appears in listings.

$
ast blueprint archive <name>

project

Manage the local agent project development environment. Alias: ast dev.

$
ast project <subcommand>
$
ast dev <subcommand>

project create

Create a new agent harness. Alias: ast create.

$
ast project create [name] [flags]
$
ast create [name] [flags]

project configure

Set credentials and variables for the current project. Alias: ast configure.

$
ast project configure [flags]
$
ast configure [flags]

Run without flags for an interactive form. Reads astropods.yml to determine required variables and stores values in ~/.ast/project-configs.json, which is loaded automatically by project start.

project start

Start local dev containers. Alias: ast dev start.

$
ast project start [flags]

project logs

Tail container logs. Alias: ast dev logs.

$
ast project logs [service]

Defaults to the agent container. Pass a service name (e.g. astro-messaging) to tail a specific container. Use --all to tail all services.

project stop

Stop and remove dev containers. Alias: ast dev stop.

$
ast project stop

secrets

Manage account secrets and plain variables. Alias: ast secret.

$
ast secrets <subcommand>

secrets list

$
ast secrets list [--values] [--json]

--values shows values for plain (non-secret) variables.

secrets create

$
ast secrets create <name> [--value <val>] [--plain] [--description <text>] [--overwrite]

Prompts for value when --value is omitted. Use --plain to store as a readable variable instead of an encrypted secret.

secrets update

$
ast secrets update <name> [--value <val>] [--plain] [--description <text>]

secrets get

$
ast secrets get <name> [--json]

secrets delete

$
ast secrets delete <name>

secrets import

Import variables from a file (e.g., .env). Blank values are skipped. Existing variables are skipped unless --overwrite is set.

$
ast secrets import --file <path> [--plain] [--plain-keys KEY1,KEY2] [--overwrite]

settings

Control CLI settings.

$
ast settings <subcommand>

settings update

Enable or disable anonymous telemetry.

$
ast settings update --telemetry on|off

settings bash / zsh / fish / powershell

Write a shell completion script to ~/.ast/<binary>-completion.<shell> and print sourcing instructions.

$
ast settings bash
$
ast settings zsh
$
ast settings fish
$
ast settings powershell

spec

Validate and explain astropods.yml spec files. The --file/-f flag is available on all spec subcommands.

$
ast spec <subcommand> [-f path/to/astropods.yml]

spec validate

Validate astropods.yml against the spec schema.

$
ast spec validate [-f <file>]

Checks YAML syntax, JSON schema conformance, and semantic rules. Exit code 0 on success, making it suitable for CI.

spec explain

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

$
ast spec explain [-f <file>]

docs

Display Astro AI documentation in the terminal.

$
ast docs [category]

Alias: ast doc

login

Authenticate with the Astro AI platform.

$
ast login [--no-browser]

--no-browser prints the verification URL instead of opening it. Credentials are stored in the system keyring or ~/.ast/credentials.json. See Authentication.

logout

Clear stored credentials.

$
ast logout [--all]

--all clears credentials for all profiles.

upgrade

Upgrade the CLI to the latest version.

$
ast upgrade [--force]

--force skips the version check and always downloads.

whoami

Display the currently authenticated user and active account.

$
ast whoami