Skip to navigation

CLI overview

Create, develop, and deploy agents from your terminal with the ast CLI
View as Markdown

The Astropods CLI (ast) is the primary tool for working with agents locally and publishing them to the Astropods platform. It handles creating agent harnesses, local development, building containers, deploying to the registry, and managing running agents.

Installation

See Install the CLI for platform-specific installation instructions.

Verify your installation:

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:

FlagShortDescription
--verbose-vVerbose output
--quiet-qMinimal output
--versionPrint the CLI version
--help-hHelp for the current command

Workflow overview

A typical workflow from zero to a deployed agent:

  1. ast project create: create a new agent harness
  2. ast project configure: set required credentials and variables
  3. ast project start: run the agent locally with hot-reload
  4. ast spec validate: check astropods.yml for errors
  5. ast push: build and push a blueprint to the registry
  6. ast blueprint deploy: deploy the blueprint as a live hosted agent

Authentication is handled separately with ast login.

Command groups

GroupDescription
ast projectLocal development: create, configure, start, stop, logs
ast blueprintRegistry: build, push, deploy, list, get
ast agentRunning agents: list, pause, resume, logs, redeploy, delete
ast envEnvironments: list, create, rename, delete
ast secretsAccount and environment vault: create, list, update, delete, import
ast knowledgeKnowledge stores: connect, list, status, credentials, delete
ast accountAccount management: list, switch
ast specSpec tools: validate
ast settingsCLI settings: telemetry, shell completions
Top-level commandslogin, logout, whoami, upgrade, docs

All commands

CommandDescription
ast project createCreate a new agent project
ast project configureConfigure project credentials and inputs
ast project startStart the project’s containers
ast project stopStop the project’s containers
ast project logsTail container logs
ast project triggerRun a job now
ast blueprint listList blueprints in the active account
ast blueprint getGet a blueprint’s metadata and config
ast blueprint buildBuild the blueprint image
ast blueprint pushPush the blueprint image to the registry
ast blueprint deployDeploy a blueprint as a new agent
ast blueprint setUpdate blueprint settings
ast blueprint archiveArchive a blueprint
ast env listList a blueprint’s environments
ast env createCreate an empty environment
ast env renameRename an environment
ast env deleteDelete an environment with no agent, and its variables and secrets
ast agent listList deployed agents in the active account
ast agent getGet details for a deployed agent
ast agent pausePause a running agent
ast agent resumeResume a paused agent
ast agent redeployRedeploy an existing agent
ast agent restartRestart a running agent
ast agent triggerRun a job now
ast agent logsFetch logs for a deployed agent
ast agent historyList an agent’s deployment history
ast agent traceList traces or show a single trace
ast agent networkShow an agent’s inbound, outbound, and database network traffic
ast agent usageShow an agent’s traces, model spend, and compute
ast agent deleteDelete a deployed agent
ast secrets listList variables and secrets
ast secrets getGet details for a variable or secret
ast secrets createCreate a variable or secret
ast secrets updateUpdate a variable’s or secret’s value
ast secrets deleteDelete a variable or secret
ast secrets importImport variables from a file such as .env
ast knowledge connectConnect a database as a knowledge store
ast knowledge listList knowledge stores
ast knowledge statusGet a knowledge store’s status
ast knowledge credentialsPrint a knowledge store’s credentials
ast knowledge deleteDelete a knowledge store
ast account listList accounts you belong to
ast account switchSet the active account
ast billing getGet plan, spend, remaining credit, and spend controls
ast billing statusGet the active account’s billing gating status
ast billing invoicesList the active account’s invoices
ast billing setSet the account’s spend warning and limit
ast billing agentsBreak down compute spend by agent
ast billing modelsBreak down AI Gateway spend by model, or one model’s spend by agent
ast eval pushActivate the agent’s EVALUATION.yaml as its evaluation set
ast eval validateValidate EVALUATION.yaml without activating it
ast spec validateValidate astropods.yml against the spec schema
ast settings updateUpdate CLI settings
ast settings bash, zsh, fish, powershellGenerate a shell completion script
ast loginAuthenticate with Astropods
ast logoutLog out from Astropods
ast whoamiDisplay the authenticated user
ast upgradeUpgrade the CLI to the latest version
ast docsDisplay Astropods documentation

Next steps