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>

Commands that target a deployment require exactly one of --name (display name or blueprint name from agent list) or --id (deployment ID). Quote --name values that contain spaces or shell metacharacters, e.g. ast agent get --name 'Pirate Parrot EU!'.

agent list

$
ast agent list [--json]

agent get

$
ast agent get --name <display-or-blueprint-name> [--json]
$
ast agent get --id <deployment-id> [--json]

agent pause / resume

$
ast agent pause --name <display-or-blueprint-name>
$
ast agent pause --id <deployment-id>
$
ast agent resume --name <display-or-blueprint-name>
$
ast agent resume --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 <display-or-blueprint-name> [flags]
$
ast agent redeploy --id <deployment-id> [flags]

agent restart

$
ast agent restart --name <display-or-blueprint-name> --component agent
$
ast agent restart --id <deployment-id> --component agent

agent logs

$
ast agent logs --name <display-or-blueprint-name> [--workload <workload>[/<container>]] [--tail]
$
ast agent logs --id <deployment-id> [--workload <workload>[/<container>]] [--tail]

By default this reads logs from all containers in the agent workload. Use --workload to target a different workload (knowledge entry, ingestion sidecar, collector, etc.) or a specific container.

--workload accepts any of:

• A full workload name: my-agent-knowledge-vectors
• An entry-name suffix: vectors (matches my-agent-knowledge-vectors)
• A component label: agent, messaging, knowledge, collector
• A workload/container pair to pick a specific container: agent/messaging

Ambiguous identifiers (e.g. knowledge when several knowledge entries exist) return an error listing the candidates. Use ast agent get --name <display-or-blueprint-name> to see each workload’s K8s name.

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

agent delete

$
ast agent delete --name <display-or-blueprint-name> [--confirm <name-or-id>]
$
ast agent delete --id <deployment-id> [--confirm <name-or-id>]

Prompts for confirmation. Pass --confirm with the display name or deployment ID to skip the prompt.

agent history

$
ast agent history --name <display-or-blueprint-name> [--json]
$
ast agent history --id <deployment-id> [--json]

agent trace

List recent traces for a deployed agent (live Langfuse query; same data as the Monitor tab in the web UI; default --limit is 50):

$
ast agent trace --name <display-or-blueprint-name> [--limit <n>] [--offset <n>] [--start <RFC3339>] [--end <RFC3339>] [--json]
$
ast agent trace --id <deployment-id> [--limit <n>] [--offset <n>] [--start <RFC3339>] [--end <RFC3339>] [--json]

Show a single trace Overview (input, output, metadata, observations, scores):

$
ast agent trace --name <display-or-blueprint-name> --trace-id <trace-id> [--json]
$
ast agent trace --name <display-or-blueprint-name> -t <trace-id> [--json]
$
ast agent trace --id <deployment-id> --trace-id <trace-id> [--json]

Print the agents-page activity summary (30-day request/token sparkline, total traces, last active). Matches the /agents dashboard; updates about every 10 minutes — not live Langfuse. Does not use --limit, --offset, --start, or --end. Cannot be combined with --trace-id.

$
ast agent trace --name <display-or-blueprint-name> --summary [--json]
$
ast agent trace --id <deployment-id> --summary [--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.

$
ast project <subcommand>

project create

Create a new agent harness. Name is required. Non-interactive. Alias: ast create.

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

After generating the agent harness, the CLI asks what you want the agent to do and prints a prompt to paste into Claude or another coding agent. Pass -y to skip the question and output the prompt immediately.

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 and tail all logs in the foreground. Press Ctrl+C to stop everything.

$
ast project start [flags]

project logs

Tail container 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.

$
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.

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] [--account <name>]

--no-browser prints the verification URL instead of opening it. --account switches to the named account after login. Re-login restores your last active account unless you pass --account. 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