create-augusta-app

An interactive CLI that scaffolds an org-standard app: pick a stack, pick the features you want, and it generates a ready-to-run project.

Repo layout

This is a monorepo:

| Path | What it is | | ---- | ---------- | | src/ | The scaffolder CLI (TypeScript, run with Bun) — published to npm | | nextjs/ | The golden template — a complete, CI-tested Next.js app with every feature enabled | | fastapi/ | The golden template for React + FastAPI — Vite React frontend plus Python backend | | react-hono/ | The golden template for React + Hono — Vite React frontend plus Bun backend | | provision/ | The provisioning broker (Hono + Better Auth) — holds the org tokens server-side and mints per-project keys. Not published to npm; deployed separately. |

Each template is the full app (all features on). Generation is subtractive: the CLI copies the selected stack template and removes whatever features you didn't select.

Usage

The published CLI runs with Bun — no install needed:

bunx create-augusta-app

Requires Bun. The CLI runs TypeScript directly and uses Bun APIs, so npx won't work. To run from a clone instead: bun run start.

You'll be prompted for:

1. Project directory — where to create the app.
2. Stack — Next.js, React + FastAPI, or React + Hono.
3. Features — stack-specific services (toggle with space).
4. Agent skills — optionally install recommended project-level skills for the selected stack.

The CLI then copies the template, prunes deselected features, installs deps, and git inits. Secrets land in a git-ignored .env:

• BETTER_AUTH_SECRET / SECRET_KEY — minted locally during generation; no account needed.
• Everything else — Postgres/Redis/Bucket, AI Gateway, Axiom, Resend, Meilisearch, Qdrant, Inngest — is provisioned by the broker. If you select any of those, the CLI asks for your Augusta email + password, sends them to the provisioning broker over HTTPS, and the broker mints per-project keys using the org's tokens (held server-side) and returns them to write into .env. The org credentials never touch your machine. Press Ctrl+C at the login prompt to skip and fill .env in yourself.

The broker URL defaults to the production deployment; override it with the AUGUSTA_BROKER_URL env var. Broker source and deploy docs live in provision/.

The CLI can also install recommended project-level agent skills for the selected stack and selected features. The mapping lives in src/skills.ts: prefer official or author-owned sources, and install full source repos when they provide a coherent pack of related skills instead of installing each skill one by one. Feature-level skills are only installed when that service is included in the generated project.

Agent harnesses

The TypeScript stacks ship with Mastra by default and can also scaffold optional OpenAI Agents SDK and Eve agent harnesses. Mastra gives generated apps a support agent at /api/agents/support, the legacy /api/mastra compatibility route, and bun run agent:eval. OpenAI Agents SDK adds /api/openai-agents/support and bun run openai-agent:eval. Eve adds a file-based agent/ scaffold and bun run eve:dev.

All TS agent harnesses depend on the Vercel AI Gateway feature. During normal scaffolding, the broker uses its VERCEL_TOKEN to mint a project-scoped AI_GATEWAY_API_KEY and writes that value into the generated app's .env. No direct OpenAI API key is required. AI_GATEWAY_MODEL is optional for the new TS harnesses; when omitted they use the gateway-routed starter model.

The React + FastAPI stack also offers an optional OpenAI Agents SDK harness. It keeps the existing Pydantic AI option available, adds /agents/openai/support, and includes uv run python -m app.openai_agents.evals for a live smoke check through the same Vercel AI Gateway credentials.

How features are defined

Each feature is a manifest in src/features.ts listing everything it owns in the template — files, dependencies, scripts, env keys, line edits, and knip.json entries where applicable. When a feature is deselected, src/generate.ts removes all of it. To add a feature, build it into the relevant golden template (so the template always runs with everything on), then add a manifest describing its footprint.

Adding to the template

Work in nextjs/ or fastapi/ like normal apps. Keeping each golden template real, runnable, and CI-green is what guarantees generated apps are valid. See nextjs/README.md and fastapi/README.md for template-specific docs.

CI

.github/workflows/ci.yml (on Blacksmith runners) checks the CLI and all golden templates.

Each golden template also includes its own scaffolded CI workflow under .github/workflows/ci.yml, so generated projects start with a stack-specific Blacksmith pipeline already in place.

Generated projects also include Husky pre-commit hooks. The hooks run staged formatting plus fast local checks, while CI remains the full source of truth for builds and tests. TypeScript checks use Oxlint's type-aware/type-check mode, and Python type checks use Pyrefly.