> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# ast project

Manage the local agent project development environment.

```bash
ast project <subcommand>
```

## project create

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

```bash
ast project create <name> [flags]
ast create <name> [flags]
```

| Flag                     | Description                                                                                                                                                            |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-y, --yes`              | Skip 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](/ai-gateway) for managed model access with no provider API key. |
| `--force`                | Overwrite 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`.

```bash
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`.

| Flag                     | Description                                 |
| ------------------------ | ------------------------------------------- |
| `--var KEY=VALUE`        | Set a variable (repeatable)                 |
| `--rm-var KEY`           | Remove a stored variable (repeatable)       |
| `--vars-file <file>`     | Import variables from a `.env` file         |
| `-o, --output env\|json` | Print 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.

```bash
ast project start [flags]
```

| Flag               | Description                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| `-b, --background` | Start containers and exit immediately; use `ast project logs` and `ast project stop` to manage |
| `--env <file>`     | Environment file for credentials (default: `.env`)                                             |
| `--rebuild`        | Force rebuild all containers without cache                                                     |
| `--no-pull`        | Use only local images; skip pulling                                                            |
| `--all-logs`       | Tail logs from every service instead of just the agent                                         |

## project logs

Tail container logs.

```bash
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.

```bash
ast project stop
```

## project trigger

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

```bash
ast project trigger <name>
```

## Next steps

* [Your first project](/get-started): create and run an agent locally, step by step
* [ast spec](/cli/spec): validate `astropods.yml` before you push
* [ast blueprint](/cli/blueprint): publish the project to the registry