Commands

ast project

Create an agent harness and run it locally
View as Markdown

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]
FlagDescription
-y, --yesSkip the goal prompt and output the coding-agent prompt immediately
-p, --path <dir>Parent directory for the project
-t, --template <name>Agent template: mastra (default) or langchain
-m, --model <provider>LLM provider: gateway, anthropic, or openai. gateway wires the agent to the Astro AI Gateway for managed model access with no provider API key.
--forceOverwrite existing directory

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.

FlagDescription
--var KEY=VALUESet a variable (repeatable)
--rm-var KEYRemove a stored variable (repeatable)
--vars-file <file>Import variables from a .env file
-o, --output env|jsonPrint stored variables instead of prompting

project start

Start local dev containers and tail the agent log in the foreground; sidecar logs are suppressed. Press Ctrl+C to stop everything.

ast project start [flags]
FlagDescription
-b, --backgroundStart containers and exit immediately; use ast project logs and ast project stop to manage
--env <file>Environment file for credentials (default: .env)
--rebuildForce rebuild all containers without cache
--no-pullUse only local images; skip pulling
--all-logsTail logs from every service instead of just the agent

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

project trigger

Manually run a named ingestion job. Starts the ingestion container and exits when the job completes.

ast project trigger <name>

Next steps