### Structured Database Setup Options Example

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/agent-workflows.mdx

Control database provisioning behavior in automation using `dbSetupOptions`. This example demonstrates setting up a PostgreSQL database with Drizzle ORM using Hono backend on Bun runtime, with manual database setup.

```bash
create-better-t-stack create-json --input '{
  "projectName": "db-app",
  "database": "postgres",
  "orm": "drizzle",
  "backend": "hono",
  "runtime": "bun",
  "api": "trpc",
  "frontend": ["tanstack-router"],
  "dbSetup": "neon",
  "dbSetupOptions": {
    "mode": "manual"
  }
}'
```

--------------------------------

### Install and Setup Project

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/contributing.mdx

Initializes the project environment by cloning the repository and installing dependencies using Bun.

```bash
git clone https://github.com/AmanVarshney01/create-better-t-stack.git
cd create-better-t-stack
bun install
```

--------------------------------

### Create Better-T-Stack Project (Default)

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/index.mdx

Creates a new Better-T-Stack project using the default stack configuration without interactive prompts. This is a shortcut for users who prefer the pre-defined setup.

```bash
npm create better-t-stack@latest --yes
```

--------------------------------

### Include Example Implementations

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

Bootstrap your project with pre-built example code, such as todo apps or AI chat interfaces, using the --examples flag.

```bash
create-better-t-stack --examples todo ai
```

--------------------------------

### Specify Database Setup Provider with --db-setup

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

The `--db-setup <setup>` option determines the database hosting or setup provider. Choices range from manual setup ('none') to cloud services like 'turso', 'd1', 'neon', 'supabase', 'planetscale', 'mongodb-atlas', and 'docker'.

```bash
create-better-t-stack --database postgres --db-setup neon
```

--------------------------------

### Create Better-T-Stack Project (Interactive)

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/index.mdx

Initiates the creation of a new Better-T-Stack project using npm. This command launches an interactive CLI to guide the user through selecting frontend, backend, database, ORM, API layer, and addons.

```bash
npm create better-t-stack@latest
```

--------------------------------

### Create Better-T-Stack Project (Convex + React + Clerk)

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/index.mdx

Creates a new Better-T-Stack project named 'my-api' configured with TanStack Router for the frontend, Convex for the backend, and Clerk for authentication. This setup is suitable for projects leveraging Convex's backend capabilities and Clerk for user management.

```bash
npm create better-t-stack@latest my-api \
  --frontend tanstack-router \
  --backend convex \
  --auth clerk
```

--------------------------------

### Clone and Develop Better-T-Stack (Bash)

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/README.md

Instructions for cloning the Better-T-Stack repository and setting up the development environment. This includes installing dependencies and starting the CLI and website development servers.

```bash
# Clone the repository
git clone https://github.com/AmanVarshney01/create-better-t-stack.git

# Install dependencies
bun install

# Start CLI development
bun dev:cli

# Start website development
bun dev:web
```

--------------------------------

### Examples

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

Include example implementations in your project, such as a Todo app or an AI chat interface.

```APIDOC
## `--examples <types...>`

### Description
Include example implementations in the project.

### Method
CLI Argument

### Endpoint
N/A

### Parameters
#### Query Parameters
- **--examples** (string array) - Optional - Comma-separated list of examples to include (`todo`, `ai`, `none`). Defaults to `none`.

### Request Example
```bash
create-better-t-stack --examples todo ai
```

### Response
#### Success Response (200)
Project includes the selected example implementations.

#### Response Example
N/A
```

--------------------------------

### Run create-better-t-stack as an MCP Server

Source: https://context7.com/amanvarshney01/create-better-t-stack/llms.txt

Provides instructions and examples for running `create-better-t-stack` as an MCP (Message Communication Protocol) server. This enables AI agents to interact with the tool programmatically. It includes commands for starting the server and examples of MCP tool calls for project planning and creation.

```bash
# Start MCP server over stdio
create-better-t-stack mcp

# Or via npx
npx create-better-t-stack@latest mcp

# Install into agent configs using add-mcp
npx -y add-mcp@latest "npx -y create-better-t-stack@latest mcp"

# For Bun projects
bunx add-mcp@latest "bunx create-better-t-stack@latest mcp"

```

```typescript
// MCP workflow example (from an MCP client)
// 1. Get guidance for ambiguous requests
const guidance = await mcpClient.callTool("bts_get_stack_guidance", {});

// 2. Get schema for input validation
const schema = await mcpClient.callTool("bts_get_schema", { name: "createInput" });

// 3. Plan project (dry run validation)
const plan = await mcpClient.callTool("bts_plan_project", {
  projectName: "my-app",
  frontend: ["tanstack-router"],
  backend: "hono",
  runtime: "bun",
  database: "postgres",
  orm: "drizzle",
  api: "trpc",
  auth: "better-auth",
  payments: "none",
  addons: [],
  examples: [],
  git: true,
  packageManager: "bun",
  install: false, // Always false for MCP to avoid timeout
  dbSetup: "neon",
  webDeploy: "none",
  serverDeploy: "none",
});

// 4. Create project after plan validation
const result = await mcpClient.callTool("bts_create_project", {
  projectName: "my-app",
  frontend: ["tanstack-router"],
  backend: "hono",
  runtime: "bun",
  database: "postgres",
  orm: "drizzle",
  api: "trpc",
  auth: "better-auth",
  payments: "none",
  addons: [],
  examples: [],
  git: true,
  packageManager: "bun",
  install: false,
  dbSetup: "neon",
  webDeploy: "none",
  serverDeploy: "none",
});

```

--------------------------------

### Development Scripts without Monorepo Tools (Bun Example)

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/project-structure.mdx

Example development scripts for a project not using Turborepo or Nx, specifically demonstrating usage with the Bun package manager. It utilizes Bun's filtering capabilities to run scripts on individual packages.

```json
{
  "scripts": {
    "dev": "bun run --filter '*' dev",
    "build": "bun run --filter '*' build",
    "check-types": "bun run --filter '*' check-types",
    "dev:web": "bun run --filter web dev",
    "dev:server": "bun run --filter server dev"
  }
}
```

--------------------------------

### Manual Database Setup with --manual-db

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

Use the `--manual-db` flag to skip the automatic database setup prompts. This option is for users who prefer to configure their database manually after the project is created.

```bash
create-better-t-stack --manual-db
```

--------------------------------

### Fastify Backend Server Entry Point

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/project-structure.mdx

The main entry point for a Fastify backend server. It sets up the Fastify instance, registers plugins, defines routes, and starts the server.

```ts
import Fastify from 'fastify';

const fastify = Fastify({
  logger: true,
});

fastify.get('/', async (request, reply) => {
  return { hello: 'Fastify' };
});

const start = async () => {
  try {
    await fastify.listen({ port: 3000 });
  } catch (err) {
    fastify.log.error(err);
    process.exit(1);
  }
};

start();

```

--------------------------------

### Frontend Options

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

These options configure the frontend setup for the project.

```APIDOC
## Frontend Options

*(No specific frontend options detailed in the provided text. This section would typically list flags related to frontend frameworks, state management, etc.)*
```

--------------------------------

### Create Better-T-Stack Project (Empty Monorepo)

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/index.mdx

Initializes an empty Better-T-Stack monorepo project named 'my-workspace'. This configuration sets both the frontend and backend to 'none', providing a bare-bones structure for custom development within a monorepo.

```bash
npm create better-t-stack@latest my-workspace \
  --frontend none \
  --backend none
```

--------------------------------

### Create Better-T-Stack Project (Stack Builder)

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/index.mdx

Launches the Better-T-Stack UI builder for creating a project. Users can visit the '/new' route or use this CLI command to visually select their stack components and generate the corresponding project creation command.

```bash
npm create better-t-stack@latest builder
```

--------------------------------

### Install Better-T-Stack dependency

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/programmatic-api.mdx

Command to install the library via npm.

```bash
npm i create-better-t-stack
```

--------------------------------

### Hono Backend Server Entry Point

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/project-structure.mdx

The main entry point for a Hono backend server. It typically sets up the Hono application, defines routes, and starts the server.

```ts
import { Hono } from 'hono';

const app = new Hono();

app.get('/', (c) => {
  return c.text('Hello Hono!');
});

export default {
  fetch: app.fetch,
};

```

--------------------------------

### Control Dependency Installation with --install / --no-install

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

The `--install` and `--no-install` flags control whether dependencies are automatically installed after the project is scaffolded. By default, dependencies are installed.

```bash
create-better-t-stack --no-install
```

--------------------------------

### Configure Frontend Frameworks

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

Use the --frontend flag to specify one or more web or native frameworks for your project. You can combine multiple frameworks or choose 'none' for a backend-only setup.

```bash
# Single web frontend
create-better-t-stack --frontend tanstack-router

# Web + native frontend
create-better-t-stack --frontend next native-uniwind

# Backend-only
create-better-t-stack --frontend none
```

--------------------------------

### Addons

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

Include additional features and tools in your project, such as PWA support, desktop app capabilities, linting, monorepo setups, and more.

```APIDOC
## `--addons <types...>`

### Description
Add extra features and tooling to the project.

### Method
CLI Argument

### Endpoint
N/A

### Parameters
#### Query Parameters
- **--addons** (string array) - Optional - Comma-separated list of addons to include (e.g., `pwa`, `biome`, `turborepo`). Defaults to `none`.

### Request Example
```bash
create-better-t-stack --addons pwa biome husky
```

### Response
#### Success Response (200)
Project includes the specified addons.

#### Response Example
N/A
```

--------------------------------

### Create Better-T-Stack Project (Default Stack)

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/index.mdx

Generates a new Better-T-Stack project named 'my-webapp' with a predefined default stack. This includes TanStack Router for frontend, Hono for backend, SQLite for database, Drizzle ORM, Better-Auth for authentication, and Turborepo for addons.

```bash
npm create better-t-stack@latest my-webapp \
  --frontend tanstack-router \
  --backend hono \
  --database sqlite \
  --orm drizzle \
  --auth better-auth \
  --addons turborepo
```

--------------------------------

### Database Options

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

These options configure the database type, ORM, and setup provider for the project.

```APIDOC
## Database Options

### `--database <type>`

**Description**: Database type to use. Options: `none`, `sqlite`, `postgres`, `mysql`, `mongodb`.

**Method**: CLI Flag

**Parameters**:
- `type` (string) - Required - The type of database to use.

**Example**:
```bash
create-better-t-stack --database postgres
```

### `--orm <type>`

**Description**: ORM to use with your database. Options: `none`, `drizzle`, `prisma`, `mongoose`.

**Method**: CLI Flag

**Parameters**:
- `type` (string) - Required - The type of ORM to use.

**Example**:
```bash
create-better-t-stack --database postgres --orm drizzle
```

### `--db-setup <setup>`

**Description**: Database hosting/setup provider. Options: `none` (Manual setup), `turso`, `d1`, `neon`, `supabase`, `prisma-postgres`, `planetscale`, `mongodb-atlas`, `docker`.

**Method**: CLI Flag

**Parameters**:
- `setup` (string) - Required - The database setup provider.

**Example**:
```bash
create-better-t-stack --database postgres --db-setup neon
```
```

--------------------------------

### Express Backend Server Entry Point

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/project-structure.mdx

The main entry point for an Express backend server. It initializes the Express app, sets up middleware, defines routes, and starts the server.

```ts
import express from 'express';

const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send('Hello Express!');
});

app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

```

--------------------------------

### Create Better-T-Stack Project (Mobile App)

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/index.mdx

Generates a new Better-T-Stack project named 'my-native' for mobile application development. It uses Native Uniwind for the frontend, Hono for the backend, SQLite for the database, Drizzle ORM, and Better-Auth for authentication.

```bash
npm create better-t-stack@latest my-native \
  --frontend native-uniwind \
  --backend hono \
  --database sqlite \
  --orm drizzle \
  --auth better-auth
```

--------------------------------

### Scaffold Projects via CLI

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/index.mdx

Examples of using the CLI to generate full-stack applications or backend-only servers with specific configurations like database, ORM, and frontend frameworks.

```bash
create-better-t-stack \
  --database postgres \
  --orm drizzle \
  --backend hono \
  --frontend tanstack-router \
  --auth better-auth \
  --addons pwa biome

create-better-t-stack api-server \
  --frontend none \
  --backend hono \
  --database postgres \
  --orm drizzle \
  --api trpc
```

--------------------------------

### Frontend Frameworks

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

Configure the frontend framework(s) for your project. You can select multiple web and native frameworks, or opt for a backend-only setup.

```APIDOC
## `--frontend <types...>`

### Description
Specify frontend frameworks for the project. Supports multiple selections for web and native, or a backend-only option.

### Method
CLI Argument

### Endpoint
N/A

### Parameters
#### Query Parameters
- **--frontend** (string array) - Required - Comma-separated list of frontend frameworks (e.g., `tanstack-router`, `next`, `native-uniwind`, `none`).

### Request Example
```bash
create-better-t-stack --frontend tanstack-router
create-better-t-stack --frontend next native-uniwind
create-better-t-stack --frontend none
```

### Response
#### Success Response (200)
Project scaffolding based on selected frontend(s).

#### Response Example
N/A
```

--------------------------------

### Elysia Backend Server Entry Point

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/project-structure.mdx

The main entry point for an Elysia backend server. It defines the Elysia app, sets up routes, and starts the server.

```ts
import { Elysia } from 'elysia';

const app = new Elysia()
  .get('/', () => 'Hello Elysia!')
  .listen(3000);

console.log(
  `Elysia is running at ${app.server?.hostname}:${app.server?.port}`
);

```

--------------------------------

### Development Scripts with Turborepo

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/project-structure.mdx

Example development scripts for a project using Turborepo. These scripts leverage `turbo` commands to run tasks across multiple packages in the monorepo, facilitating efficient development workflows.

```json
{
  "scripts": {
    "dev": "turbo dev",
    "build": "turbo build",
    "check-types": "turbo check-types",
    "dev:web": "turbo -F web dev",
    "dev:server": "turbo -F server dev",
    "db:push": "turbo -F server db:push",
    "db:studio": "turbo -F server db:studio"
  }
}
```

--------------------------------

### Choose Package Manager with --package-manager

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

Specify the package manager to be used for installing dependencies with the `--package-manager <pm>` option. Supported options are 'npm', 'pnpm', and 'bun'.

```bash
create-better-t-stack --package-manager bun
```

--------------------------------

### Development Scripts with Nx

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/project-structure.mdx

Example development scripts for a project using Nx. These scripts use `nx run-many` to execute tasks across specified projects within the monorepo, enabling parallel execution and task management.

```json
{
  "scripts": {
    "dev": "nx run-many -t dev",
    "build": "nx run-many -t build",
    "check-types": "nx run-many -t check-types",
    "dev:web": "nx run-many -t dev --projects=web",
    "dev:server": "nx run-many -t dev --projects=server"
  }
}
```

--------------------------------

### Better-T-Stack Configuration (bts.jsonc)

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/project-structure.mdx

The main configuration file for Better-T-Stack, defining project settings such as database, ORM, backend, frontend, addons, and API choices. This JSONC file guides the generation of the project structure and dependencies.

```json
{
  "$schema": "https://r2.better-t-stack.dev/schema.json",
  "version": "<cli-version>",
  "createdAt": "<timestamp>",
  "database": "<none|sqlite|postgres|mysql|mongodb>",
  "orm": "<none|drizzle|prisma|mongoose>",
  "backend": "<none|hono|express|fastify|elysia|convex|self>",
  "runtime": "<bun|node|workers|none>",
  "frontend": ["<tanstack-router|react-router|tanstack-start|next|nuxt|svelte|solid|astro|native-bare|native-uniwind|native-unistyles|none>"] ,
  "addons": ["<pwa|tauri|electrobun|starlight|fumadocs|biome|lefthook|husky|mcp|turborepo|nx|ultracite|oxlint|opentui|wxt|skills|none>"] ,
  "examples": ["<ai|todo|none>"] ,
  "auth": <"better-auth"|"clerk"|"none">
  "packageManager": "<bun|pnpm|npm>",
  "dbSetup": "<turso|neon|prisma-postgres|planetscale|mongodb-atlas|supabase|d1|docker|none>",
  "api": "<none|trpc|orpc>",
  "webDeploy": "<cloudflare|none>",
  "serverDeploy": "<cloudflare|none>"
}
```

--------------------------------

### Create Better T Stack CLI Usage

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/cli/README.md

The main command-line interface for create-better-t-stack. It accepts a project directory and various options to configure the project setup, including template, database, ORM, authentication, frontend, backend, and more. The `--help` flag displays all available options.

```bash
Usage: create-better-t-stack [project-directory] [options]

Options:
  -V, --version                   Output the version number
  -y, --yes                       Use default configuration
  --template <type>               Use a template (mern, pern, t3, uniwind, none)
  --database <type>               Database type (none, sqlite, postgres, mysql, mongodb)
  --orm <type>                    ORM type (none, drizzle, prisma, mongoose)
  --dry-run                       Validate configuration without writing files
  --auth <provider>               Authentication (better-auth, clerk, none)
  --payments <provider>           Payments provider (polar, none)
  --frontend <types...>           Frontend types (tanstack-router, react-router, tanstack-start, next, nuxt, svelte, solid, astro, native-bare, native-uniwind, native-unistyles, none)
  --addons <types...>             Additional addons (pwa, tauri, electrobun, starlight, biome, lefthook, husky, mcp, turborepo, nx, fumadocs, ultracite, oxlint, opentui, wxt, skills, none)
  --examples <types...>           Examples to include (todo, ai, none)
  --git                           Initialize git repository
  --no-git                        Skip git initialization
  --package-manager <pm>          Package manager (npm, pnpm, bun)
  --install                       Install dependencies
  --no-install                    Skip installing dependencies
  --db-setup <setup>              Database setup (turso, d1, neon, supabase, prisma-postgres, planetscale, mongodb-atlas, docker, none)
  --web-deploy <setup>            Web deployment (cloudflare, none)
  --server-deploy <setup>         Server deployment (cloudflare, none)
  --backend <framework>           Backend framework (hono, express, fastify, elysia, convex, self, none)
  --runtime <runtime>             Runtime (bun, node, workers, none)
  --api <type>                    API type (trpc, orpc, none)
  --directory-conflict <strategy> Directory strategy (merge, overwrite, increment, error)
  -h, --help                      Display help
```

--------------------------------

### Automate CLI via JSON input

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/index.mdx

Executes project creation or addon installation using machine-readable JSON payloads instead of CLI flags. Useful for agentic workflows and automated scripts.

```bash
# Create project from JSON
create-better-t-stack create-json --input '{"projectName":"my-app","yes":true,"dryRun":true}'

# Add addons from JSON
create-better-t-stack add-json --input '{"projectDir":"./my-app","addons":["wxt"],"addonOptions":{"wxt":{"template":"react"}}}'
```

--------------------------------

### Generate Virtual Projects In-Memory with createVirtual()

Source: https://context7.com/amanvarshney01/create-better-t-stack/llms.txt

Illustrates the use of the `createVirtual` function from `create-better-t-stack` to generate project structures in memory without writing to disk. This is useful for previews and testing. The example shows how to configure various project aspects and handle the resulting virtual file tree.

```typescript
import { createVirtual, type VirtualFileTree, EMBEDDED_TEMPLATES, TEMPLATE_COUNT } from "create-better-t-stack";

// Generate virtual project
const result = await createVirtual({
  projectName: "preview-app",
  frontend: ["tanstack-router"],
  backend: "hono",
  runtime: "bun",
  database: "sqlite",
  orm: "drizzle",
  api: "trpc",
  auth: "better-auth",
  payments: "none",
  addons: ["biome"],
  examples: ["todo"],
  packageManager: "bun",
  dbSetup: "none",
  webDeploy: "none",
  serverDeploy: "none",
});

result.match({
  ok: (tree: VirtualFileTree) => {
    console.log(`Generated ${tree.fileCount} files`);
    console.log(`Generated ${tree.directoryCount} directories`);
    console.log(`Project config:`, tree.config);

    // Access the virtual file tree
    const root = tree.root;
    // Navigate the tree structure...
  },
  err: (error) => {
    console.error(`Generation failed: ${error.message}`);
  },
});

// Check available embedded templates
console.log(`Embedded templates available: ${TEMPLATE_COUNT}`);

```

--------------------------------

### Automate project creation via JSON payload

Source: https://context7.com/amanvarshney01/create-better-t-stack/llms.txt

Use the create-json command to pass a structured JSON object for automated scaffolding, ideal for AI agents or CI/CD pipelines. Supports nested configurations for complex addons and database setups.

```bash
create-better-t-stack create-json --input '{
  "projectName": "my-app",
  "frontend": ["tanstack-router"],
  "backend": "hono",
  "runtime": "bun",
  "database": "postgres",
  "orm": "drizzle",
  "api": "trpc",
  "auth": "better-auth",
  "addons": ["biome", "turborepo"],
  "git": true
}'

create-better-t-stack create-json --input '{
  "projectName": "extension-app",
  "addons": ["wxt", "mcp"],
  "addonOptions": {
    "wxt": { "template": "react", "devPort": 5555 },
    "mcp": { "servers": ["context7"] }
  }
}'
```

--------------------------------

### Add Addons Programmatically with create-better-t-stack

Source: https://context7.com/amanvarshney01/create-better-t-stack/llms.txt

Demonstrates how to use the `add` function from `create-better-t-stack` to programmatically add addons to an existing project. It covers basic addon addition with installation and package manager specification, as well as advanced usage with structured addon options and dry runs for validation.

```typescript
import { add, type AddResult } from "create-better-t-stack";

// Basic addon addition
const result = await add({
  projectDir: "./my-app",
  addons: ["biome", "husky", "pwa"],
  install: true,
  packageManager: "bun",
});

if (result?.success) {
  console.log(`Added addons: ${result.addedAddons.join(", ")}`);
  console.log(`Project directory: ${result.projectDir}`);
  console.log(`Files written: ${result.plannedFileCount}`);
} else {
  console.error(`Failed: ${result?.error ?? "Unknown error"}`);
}

// With structured addon options
const resultWithOptions = await add({
  projectDir: "./my-app",
  addons: ["mcp", "skills", "ultracite"],
  addonOptions: {
    mcp: {
      scope: "project",
      servers: ["context7", "better-t-stack", "supabase"],
      agents: ["cursor", "claude-code", "vscode"],
    },
    skills: {
      scope: "project",
      agents: ["cursor", "claude-code"],
      selections: [
        { source: "vercel-labs/agent-skills", skills: ["web-design-guidelines"] },
        { source: "supabase/agent-skills", skills: ["database-setup"] },
      ],
    },
    ultracite: {
      linter: "biome",
      editors: ["vscode", "cursor", "windsurf"],
      agents: ["claude", "codex", "copilot"],
      hooks: ["cursor", "claude"],
    },
  },
  install: true,
  packageManager: "bun",
});

// Dry run for validation
const dryResult = await add({
  projectDir: "./my-app",
  addons: ["wxt"],
  addonOptions: {
    wxt: { template: "solid" },
  },
  dryRun: true,
});

if (dryResult?.success && dryResult.dryRun) {
  console.log(`Would write ${dryResult.plannedFileCount} files`);
}

```

--------------------------------

### Select Backend Framework with --backend

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

Choose a backend framework using the `--backend <framework>` option. Available frameworks include 'none', 'hono', 'express', 'fastify', 'elysia', 'convex', and 'self'.

```bash
create-better-t-stack --backend hono
```

--------------------------------

### Scaffold a new project via CLI

Source: https://context7.com/amanvarshney01/create-better-t-stack/llms.txt

Initialize a new project using interactive prompts, default settings, or specific configuration flags. This supports various package managers like bun, pnpm, and npm.

```bash
# Interactive mode
bun create better-t-stack@latest

# Quick setup with defaults
create-better-t-stack my-app --yes

# Full configuration via flags
create-better-t-stack my-app \
  --database postgres \
  --orm drizzle \
  --backend hono \
  --runtime bun \
  --frontend tanstack-router \
  --api trpc \
  --auth better-auth \
  --addons pwa biome \
  --examples todo \
  --package-manager bun \
  --install
```

--------------------------------

### Install MCP Server into Agent Configs

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/agent-workflows.mdx

Integrate the Better-T-Stack MCP server into supported agent configurations using the `add-mcp` command. This ensures the generated project can communicate with the MCP server without global installations.

```bash
npx -y add-mcp@latest "npx -y create-better-t-stack@latest mcp"
```

--------------------------------

### Initialize Project with create-bts

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/packages/create-bts/README.md

Commands to scaffold a new project using the create-bts alias. Supports both npx for npm users and the bun runtime for faster execution.

```bash
npx create-bts@latest
```

```bash
bun create bts
```

--------------------------------

### Query Function Example

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/packages/template-generator/templates/backend/convex/packages/backend/convex/README.md

Demonstrates how to define and use a Convex query function with argument validation and database reads.

```APIDOC
## POST /convex/myFunctions.myQueryFunction

### Description
A query function that takes two arguments (a number and a string) and returns documents from a table.

### Method
POST

### Endpoint
/convex/myFunctions.myQueryFunction

### Parameters
#### Query Parameters
- **first** (number) - Required - The first argument for the query.
- **second** (string) - Required - The second argument for the query.

### Request Body
```json
{
  "first": 10,
  "second": "hello"
}
```

### Response
#### Success Response (200)
- **documents** (Array) - An array of documents retrieved from the specified table.

#### Response Example
```json
{
  "documents": [
    {
      "_id": "someId1",
      "field1": "value1"
    },
    {
      "_id": "someId2",
      "field1": "value2"
    }
  ]
}
```
```

--------------------------------

### Develop Documentation Web App

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/contributing.mdx

Configures the backend and frontend for the documentation site, including setting up environment variables and Convex secrets.

```bash
cd packages/backend
bun dev:setup
# Set environment variables in apps/web/.env
# NEXT_PUBLIC_CONVEX_URL=http://127.0.0.1:3210/
npx convex env set GITHUB_ACCESS_TOKEN=xxxxx
npx convex env set GITHUB_WEBHOOK_SECRET=xxxxx
bun dev
```

--------------------------------

### Mutation Function Example

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/packages/template-generator/templates/backend/convex/packages/backend/convex/README.md

Illustrates how to define and use a Convex mutation function for database writes and optional return values.

```APIDOC
## POST /convex/myFunctions.myMutationFunction

### Description
A mutation function that inserts a new message into the 'messages' table and returns the inserted message.

### Method
POST

### Endpoint
/convex/myFunctions.myMutationFunction

### Parameters
#### Query Parameters
- **first** (string) - Required - The body of the message to be inserted.
- **second** (string) - Required - The author of the message.

### Request Body
```json
{
  "first": "Hello!",
  "second": "me"
}
```

### Response
#### Success Response (200)
- **message** (Object) - The newly inserted message object, including its ID.
  - **_id** (string) - The unique identifier for the message.
  - **body** (string) - The content of the message.
  - **author** (string) - The author of the message.

#### Response Example
```json
{
  "_id": "messageId123",
  "body": "Hello!",
  "author": "me"
}
```
```

--------------------------------

### Prisma ORM Auth Schema Extension

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/project-structure.mdx

An example of extending the Prisma schema to include authentication-related fields. This file would be added to the Prisma schema definition.

```prisma
model Account {
  id                String  @id @default(cuid())
  userId            String
  type              String
  provider          String
  providerAccountId String
  refresh_token     String? @db.Text
  access_token      String? @db.Text
  expires_at        Int? 
  token_type        String?
  scope             String?
  id_token          String? @db.Text
  session_state     String?

  user User @relation(fields: [userId], references: [id])

  @@unique([provider, providerAccountId])
}

```

--------------------------------

### Develop CLI Application

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/contributing.mdx

Instructions for building and testing the CLI tool locally using Bun's development and linking features.

```bash
cd apps/cli
bun link
bun dev
# To run globally:
create-better-t-stack
```

--------------------------------

### Drizzle ORM Auth Schema Extension

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/project-structure.mdx

An example of extending the Drizzle ORM schema to include authentication-related fields. This file would typically be part of the Drizzle schema definitions.

```ts
import { pgTable, text, timestamp } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  id: text('id').primaryKey(),
  email: text('email').notNull().unique(),
  name: text('name'),
  createdAt: timestamp('created_at').defaultNow(),
});

```

--------------------------------

### Configure Payments

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

Integrate payment providers like Polar using the --payments flag. This requires specific authentication setups.

```bash
create-better-t-stack --payments polar --auth better-auth
```

--------------------------------

### Configure Deployment

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

Set up infrastructure-as-code deployment targets for web or server environments using the --web-deploy and --server-deploy flags.

```bash
create-better-t-stack --web-deploy cloudflare
create-better-t-stack --server-deploy cloudflare
```

--------------------------------

### Initialize Projects via CLI

Source: https://context7.com/amanvarshney01/create-better-t-stack/llms.txt

Scaffold a new project using the CLI with JSON input for precise configuration. The dryRun flag allows for validation of the configuration without modifying the file system.

```bash
create-better-t-stack create-json --input '{
  "projectName": "test-app",
  "frontend": ["next"],
  "backend": "self",
  "runtime": "node",
  "database": "postgres",
  "orm": "prisma",
  "api": "trpc",
  "auth": "better-auth",
  "payments": "polar",
  "addons": [],
  "examples": [],
  "git": true,
  "packageManager": "pnpm",
  "install": false,
  "dbSetup": "none",
  "webDeploy": "cloudflare",
  "serverDeploy": "none",
  "dryRun": true
}'
```

--------------------------------

### Multi-Stage Deployment CLI Arguments

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/guides/cloudflare-alchemy.mdx

Demonstrates how to deploy to different stages (development, staging, production) using CLI arguments with the `bun run deploy` command. The `--stage` flag specifies the target environment.

```bash
# Development (default)
bun run deploy

# Staging
bun run deploy --stage staging

# Production
bun run deploy --stage prod
```

--------------------------------

### Create project programmatically

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/programmatic-api.mdx

Demonstrates how to initialize a new project using the create function with specific stack configurations. It shows handling the result using pattern matching.

```typescript
import { create } from "create-better-t-stack";

const result = await create("my-app", {
  frontend: ["tanstack-router"],
  backend: "hono",
  database: "sqlite",
  orm: "drizzle",
  auth: "better-auth",
  packageManager: "bun",
  install: false,
  dryRun: true,
});

result.match({
  ok: (data) => {
    console.log(`Project created at: ${data.projectDirectory}`);
    console.log(`Reproducible command: ${data.reproducibleCommand}`);
  },
  err: (error) => {
    console.error(`Failed: ${error.message}`);
  },
});
```

--------------------------------

### Access Bindings in Request Handlers

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/guides/cloudflare-alchemy.mdx

Provides examples of accessing type-safe environment bindings within Hono applications and standard Cloudflare Worker fetch handlers.

```typescript
import { Hono } from "hono";
import { env } from "cloudflare:workers";

const app = new Hono()
  .get("/users", async (c) => {
    const db = drizzle(env.DB);
    const users = await db.select().from(usersTable);
    return c.json(users);
  });

export default {
  async fetch(request: Request, env: typeof server.Env) {
    const value = await env.KV.get("key");
    return new Response(`Value: ${value}`);
  },
};
```

--------------------------------

### Multi-Stage Deployment with Environment Files

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/guides/cloudflare-alchemy.mdx

Shows how to specify deployment stages using environment files, such as `.env.prod`, and pass them to the deploy command. This method allows for environment-specific configurations to be loaded.

```bash
# packages/infra/.env.prod
ALCHEMY_STAGE=prod

bun run deploy --env-file .env.prod
```

--------------------------------

### Set Alchemy Password for CI/CD

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/guides/cloudflare-alchemy.mdx

Provides an example of how to set the `ALCHEMY_PASSWORD` environment variable in GitHub Actions for CI/CD pipelines. This password is required for encrypting and decrypting secrets.

```yaml
env:
  ALCHEMY_PASSWORD: ${{ secrets.ALCHEMY_PASSWORD }}
```

--------------------------------

### Configure Authentication

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

Select an authentication provider using the --auth flag. Note that some providers like 'clerk' have specific backend requirements.

```bash
create-better-t-stack --auth better-auth
create-better-t-stack --auth clerk
create-better-t-stack --auth none
```

--------------------------------

### Add Shared UI Components with shadcn/ui CLI

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/project-structure.mdx

This command adds new shadcn/ui primitives to the shared UI package. It requires the shadcn-ui CLI to be installed. The command specifies the components to add and the target package.

```bash
npx shadcn@latest add accordion dialog popover sheet table -c packages/ui
```

--------------------------------

### Docker Compose for Database

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/project-structure.mdx

A sample docker-compose.yml file for setting up a database service. This file defines the database image, ports, volumes, and environment variables required to run the database in a Docker container.

```yaml
version: '3.8'

services:
  db:
    image: postgres:15
    ports:
      - '5432:5432'
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: mydatabase

volumes:
  db_data:

```

--------------------------------

### Add Features and Plugins

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

Extend your project with additional tools such as PWA support, linting, git hooks, or monorepo configurations using the --addons flag.

```bash
create-better-t-stack --addons pwa biome husky
```

--------------------------------

### Configure project components via CLI flags

Source: https://context7.com/amanvarshney01/create-better-t-stack/llms.txt

Granularly define project architecture including frontend frameworks, backend runtimes, database providers, and specific addons using command-line arguments.

```bash
create-better-t-stack --frontend tanstack-router native-uniwind
create-better-t-stack --backend hono
create-better-t-stack --database postgres
create-better-t-stack --addons pwa biome turborepo mcp
create-better-t-stack my-app --directory-conflict overwrite
```

--------------------------------

### Automation Surfaces

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/options.mdx

These are CLI contract points for agents and scripts, including commands like `create-json`, `add-json`, `schema`, `mcp`, `addonOptions`, and `dbSetupOptions`.

```APIDOC
## Automation Surfaces

### Description
Specialized commands and JSON fields designed for agent and script interaction.

### Method
CLI Commands / JSON Fields

### Endpoint
N/A

### Available Surfaces
- `create-json`
- `add-json`
- `schema --name <schema>`
- `mcp`
- `addonOptions`
- `dbSetupOptions`

### Request Example
```bash
create-better-t-stack schema --name my-schema
```

### Response
#### Success Response (200)
Execution of the automation surface command.

#### Response Example
N/A

### Notes
Refer to the [Agent Workflows](/docs/cli/agent-workflows) documentation for examples.
```

--------------------------------

### Create a new Better-T-Stack project

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/apps/web/content/docs/cli/index.mdx

Initializes a new project using the CLI. Supports various flags for backend, frontend, database, and authentication configurations, or can be run with default settings.

```bash
# Default setup with prompts
create-better-t-stack

# Quick setup with defaults
create-better-t-stack --yes

# Specific configuration
create-better-t-stack --database postgres --backend hono --frontend tanstack-router

# Validate without writing files
create-better-t-stack my-app --yes --dry-run
```

--------------------------------

### Get create-better-t-stack Schemas (CLI)

Source: https://context7.com/amanvarshney01/create-better-t-stack/llms.txt

Retrieve schema definitions for various parts of the create-better-t-stack CLI. This includes the main CLI command schema, input schemas for actions like 'create' and 'add', and configuration schemas.

```bash
create-better-t-stack schema --name all
create-better-t-stack schema --name cli
create-better-t-stack schema --name createInput
create-better-t-stack schema --name addInput
create-better-t-stack schema --name addonOptions
create-better-t-stack schema --name dbSetupOptions
create-better-t-stack schema --name projectConfig
```

--------------------------------

### Create Better-T-Stack Project (CLI)

Source: https://github.com/amanvarshney01/create-better-t-stack/blob/main/README.md

Commands to create a new project using the Better-T-Stack CLI. It supports multiple package managers, with Bun being the recommended option for optimal performance.

```bash
# Using bun (recommended)
bun create better-t-stack@latest

# Using pnpm
pnpm create better-t-stack@latest

# Using npm
npx create-better-t-stack@latest
```