Skip to navigation
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 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 <file>Environment file for credentials (default: .env). Accepts an absolute path or one relative to the project directory. When you pass --env-file, the file must exist, or the command stops with an error. Replaces --env, which still works but is deprecated.
--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 job. Starts the job in a container and exits when the job completes. Requires a running dev environment.

ast project trigger <name> [flags]

Run without a name to list the jobs declared in astropods.yml.

FlagDescription
--env-file <file>Environment file for credentials and input values (default: .env). Accepts an absolute path or one relative to the project directory. When you pass --env-file, the file must exist, or the command stops with an error. Replaces --env, which still works but is deprecated.
-f, --file <file>Path to the agent spec (default: astropods.yml in the current directory)

The environment file also supplies values for the inputs declared on the job entry in astropods.yml, so you can vary a run without editing the spec:

ast project trigger backfill --env-file env/full-sync.env

Values stored by project configure take precedence over the environment file.

project trigger runs whichever images already exist and does not rebuild them. After changing code that a job runs, rebuild first with ast project start --rebuild.

Next steps