create-better-t-stack/apps/web/content/docs/cli-commands.mdx

---
title: CLI Commands
description: Complete reference for all Better-T-Stack CLI commands and options
---

## Quick Usage

<Tabs items={['bun', 'pnpm', 'npm']}>
  <Tab value="bun">
    ```bash
    # Interactive setup
    bun create better-t-stack@latest

    # With project name
    bun create better-t-stack@latest my-project
    ```
  </Tab>
  <Tab value="pnpm">
    ```bash
    pnpm create better-t-stack@latest
    pnpm create better-t-stack@latest my-project
    ```
  </Tab>
  <Tab value="npm">
    ```bash
    npx create-better-t-stack@latest
    npx create-better-t-stack@latest my-project
    ```
  </Tab>
</Tabs>

## Commands Overview

| Command | Description |
|---------|-------------|
| `init` (default) | Create a new Better-T-Stack project |
| `add` | Add addons or deployment configurations to existing projects |
| `sponsors` | Display project sponsors |
| `docs` | Open documentation in browser |
| `builder` | Open web-based stack builder |

---

## `init` - Create Project (Default)

The primary command for creating new Better-T-Stack projects.

### Basic Usage

<Tabs items={['bun', 'pnpm', 'npm']}>
  <Tab value="bun">
    ```bash
    # Interactive setup
    bun create better-t-stack@latest

    # With project name
    bun create better-t-stack@latest my-project

    # With specific directory
    bun create better-t-stack@latest ./path/to/project

    # Use current directory
    bun create better-t-stack@latest .
    ```
  </Tab>
  <Tab value="pnpm">
    ```bash
    pnpm create better-t-stack@latest
    pnpm create better-t-stack@latest my-project
    pnpm create better-t-stack@latest ./path/to/project
    pnpm create better-t-stack@latest .
    ```
  </Tab>
  <Tab value="npm">
    ```bash
    npx create-better-t-stack@latest
    npx create-better-t-stack@latest my-project
    npx create-better-t-stack@latest ./path/to/project
    npx create-better-t-stack@latest .
    ```
  </Tab>
</Tabs>

### Flags Reference

#### General Options

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--yes, -y` | boolean | `false` | Skip prompts, use defaults |
| `--help, -h` | boolean | - | Show help information |
| `--version, -V` | boolean | - | Show CLI version |

#### Frontend Options

| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--frontend` | Multiple values | `tanstack-router` | Frontend frameworks to include |

**Available Frontend Values:**
- `tanstack-router` - React with TanStack Router
- `react-router` - React with React Router
- `tanstack-start` - React with TanStack Start (SSR)
- `next` - Next.js framework
- `nuxt` - Vue.js with Nuxt
- `svelte` - SvelteKit
- `solid` - SolidJS
- `native-nativewind` - React Native with NativeWind
- `native-unistyles` - React Native with Unistyles
- `none` - No frontend

**Examples:**
```bash
# Single web frontend
--frontend tanstack-router

# Web + Mobile
--frontend tanstack-router native-nativewind

# No frontend (API-only)
--frontend none
```

Note: Select at most one web frontend (one of: tanstack-router, react-router, tanstack-start, next, nuxt, svelte, solid) and at most one native frontend (one of: native-nativewind, native-unistyles).
Do not combine `none` with other frontend values.

#### Backend Options

| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--backend` | Single value | `hono` | Backend framework |

**Available Backend Values:**
- `hono` - Hono web framework
- `express` - Express.js
- `fastify` - Fastify framework
- `elysia` - Elysia framework
- `next` - Next.js API routes
- `convex` - Convex backend-as-a-service
- `none` - No backend

**Examples:**
```bash
--backend hono
--backend convex
--backend none
```

#### Runtime Options

| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--runtime` | Single value | `bun` | Runtime environment |

**Available Runtime Values:**
- `bun` - Bun runtime
- `node` - Node.js runtime
- `workers` - Cloudflare Workers (Hono only)
- `none` - No runtime (Convex/none backend)

**Examples:**
```bash
--runtime bun
--runtime workers  # Only with --backend hono
```

#### Database Options

| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--database` | Single value | `sqlite` | Database type |

**Available Database Values:**
- `sqlite` - SQLite database
- `postgres` - PostgreSQL
- `mysql` - MySQL
- `mongodb` - MongoDB
- `none` - No database

**Examples:**
```bash
--database postgres
--database none
```

#### ORM Options

| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--orm` | Single value | `drizzle` | ORM/Database toolkit |

**Available ORM Values:**
- `drizzle` - Drizzle ORM (TypeScript-first)
- `prisma` - Prisma ORM (feature-rich)
- `mongoose` - Mongoose (MongoDB only)
- `none` - No ORM

**Examples:**
```bash
--orm drizzle
--orm prisma
--orm none
```

#### API Layer Options

| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--api` | Single value | `trpc` | API layer type |

**Available API Values:**
- `trpc` - tRPC (end-to-end type safety)
- `orpc` - oRPC (OpenAPI compatible)
- `none` - No API layer

**Examples:**
```bash
--api trpc
--api orpc
--api none
```

#### Authentication Options

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--auth` | boolean | `true` | Enable authentication |
| `--no-auth` | boolean | - | Disable authentication |

**Examples:**
```bash
--auth        # Enable auth
--no-auth     # Disable auth
```

#### Addons Options

| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--addons` | Multiple values | `turborepo` | Additional features |

**Available Addon Values:**
- `turborepo` - Turborepo build system
- `pwa` - Progressive Web App support
- `tauri` - Desktop app with Tauri
- `biome` - Biome linter/formatter
- `husky` - Git hooks with Husky
- `starlight` - Documentation site
 - `fumadocs` - Fumadocs docs site
 - `ultracite` - Markdown/MDX processing
 - `oxlint` - Fast linter
- `none` - No addons

Note: Do not combine `none` with other addon values.

**Examples:**
```bash
--addons turborepo pwa
--addons biome husky
--addons none
```

#### Examples Options

| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--examples` | Multiple values | `[]` | Example applications |

**Available Example Values:**
- `todo` - Todo CRUD application
- `ai` - AI chat interface
- `none` - No examples

**Examples:**
```bash
--examples todo
--examples todo ai
--examples none
```

Note: Do not combine `none` with other example values.

#### Database Setup Options

| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--db-setup` | Single value | `none` | Database hosting setup |

**Available Database Setup Values:**
- `turso` - Turso SQLite hosting
- `neon` - Neon PostgreSQL
- `supabase` - Supabase PostgreSQL
- `prisma-postgres` - Prisma PostgreSQL
- `mongodb-atlas` - MongoDB Atlas
- `d1` - Cloudflare D1 (Workers only)
- `docker` - Local Docker setup
- `none` - Manual setup

**Examples:**
```bash
--db-setup neon
--db-setup docker
--db-setup none
```

#### Deployment Options

| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--web-deploy` | Single value | `none` | Web deployment setup |

**Available Deployment Values:**
- `workers` - Cloudflare Workers
- `none` - No deployment setup

**Examples:**
```bash
--web-deploy workers
--web-deploy none
```

#### Project Management Options

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--git` | boolean | `true` | Initialize git repository |
| `--no-git` | boolean | - | Skip git initialization |
| `--install` | boolean | `true` | Install dependencies |
| `--no-install` | boolean | - | Skip dependency installation |
| `--package-manager` | string | auto-detect | Package manager to use |

**Package Manager Values:**
- `npm` - Use npm
- `pnpm` - Use pnpm
- `bun` - Use bun

**Examples:**
```bash
--git --install --package-manager pnpm
--no-git --no-install
```

---

## `add` - Add to Existing Project

Add addons or deployment configurations to existing Better-T-Stack projects.

### Usage

<Tabs items={['bun', 'pnpm', 'npm']}>
  <Tab value="bun">
    ```bash
    # Interactive addon selection
    bun create better-t-stack@latest add

    # Add specific addons
    bun create better-t-stack@latest add --addons pwa tauri

    # Add deployment
    bun create better-t-stack@latest add --web-deploy workers

    # Add both
    bun create better-t-stack@latest add --addons biome --web-deploy workers
    ```
  </Tab>
  <Tab value="pnpm">
    ```bash
    pnpm create better-t-stack@latest add
    pnpm create better-t-stack@latest add --addons pwa tauri
    pnpm create better-t-stack@latest add --web-deploy workers
    pnpm create better-t-stack@latest add --addons biome --web-deploy workers
    ```
  </Tab>
  <Tab value="npm">
    ```bash
    npx create-better-t-stack@latest add
    npx create-better-t-stack@latest add --addons pwa tauri
    npx create-better-t-stack@latest add --web-deploy workers
    npx create-better-t-stack@latest add --addons biome --web-deploy workers
    ```
  </Tab>
</Tabs>

### Flags

| Flag | Values | Description |
|------|--------|-------------|
| `--addons` | Multiple values | Addons to add (same as init) |
| `--web-deploy` | Single value | Deployment to add |
| `--project-dir` | string | Target project directory (default: current) |
| `--install` | boolean | Install dependencies after adding |
| `--no-install` | boolean | Skip dependency installation |
| `--package-manager` | string | Package manager to use |

### Examples

```bash
# Add PWA support to current project
npx create-better-t-stack@latest add --addons pwa

# Add multiple addons with dependency installation
npx create-better-t-stack@latest add --addons biome husky --install

# Add to specific project directory
npx create-better-t-stack@latest add --project-dir ./my-project --addons tauri
```

---

## `sponsors` - View Sponsors

Display Better-T-Stack project sponsors.

### Usage

<Tabs items={['bun', 'pnpm', 'npm']}>
  <Tab value="bun">
    ```bash
    bun create better-t-stack@latest sponsors
    ```
  </Tab>
  <Tab value="pnpm">
    ```bash
    pnpm create better-t-stack@latest sponsors
    ```
  </Tab>
  <Tab value="npm">
    ```bash
    npx create-better-t-stack@latest sponsors
    ```
  </Tab>
</Tabs>

Shows a list of project sponsors with their GitHub profiles and websites.

---

## `docs` - Open Documentation

Open Better-T-Stack documentation in your default browser.

### Usage

<Tabs items={['bun', 'pnpm', 'npm']}>
  <Tab value="bun">
    ```bash
    bun create better-t-stack@latest docs
    ```
  </Tab>
  <Tab value="pnpm">
    ```bash
    pnpm create better-t-stack@latest docs
    ```
  </Tab>
  <Tab value="npm">
    ```bash
    npx create-better-t-stack@latest docs
    ```
  </Tab>
</Tabs>

Opens: https://better-t-stack.dev/docs

---

## `builder` - Open Stack Builder

Open the web-based interactive stack builder.

### Usage

<Tabs items={['bun', 'pnpm', 'npm']}>
  <Tab value="bun">
    ```bash
    bun create better-t-stack@latest builder
    ```
  </Tab>
  <Tab value="pnpm">
    ```bash
    pnpm create better-t-stack@latest builder
    ```
  </Tab>
  <Tab value="npm">
    ```bash
    npx create-better-t-stack@latest builder
    ```
  </Tab>
</Tabs>

Opens: https://better-t-stack.dev/new

The web builder provides a visual interface for configuring your stack and generates the corresponding CLI command.

---

## Complete Examples

### Full-Stack Web Application

```bash
bun create better-t-stack@latest my-webapp \
  --frontend tanstack-router \
  --backend hono \
  --runtime bun \
  --database postgres \
  --orm drizzle \
  --api trpc \
  --auth \
  --db-setup neon \
  --addons pwa turborepo \
  --examples todo ai
```

### Mobile + Web Application

```bash
bun create better-t-stack@latest my-mobile-app \
  --frontend tanstack-router native-nativewind \
  --backend hono \
  --database sqlite \
  --orm drizzle \
  --auth \
  --db-setup turso \
  --addons turborepo
```

### Cloudflare Workers Project

```bash
bun create better-t-stack@latest my-workers-app \
  --frontend tanstack-router \
  --backend hono \
  --runtime workers \
  --database sqlite \
  --orm drizzle \
  --db-setup d1 \
  --web-deploy workers
```

### API-Only Project

```bash
bun create better-t-stack@latest my-api \
  --frontend none \
  --backend fastify \
  --runtime node \
  --database postgres \
  --orm prisma \
  --api trpc \
  --db-setup docker
```

### Quick Defaults

```bash
# Use all defaults with immediate setup
bun create better-t-stack@latest my-project --yes

# Convex full-stack (automatically configures compatible options)
bun create better-t-stack@latest my-convex-app --backend convex
```

---

## Compatibility Notes

Some options have compatibility requirements:

- **Cloudflare Workers**: Only with `--backend hono`, `--orm drizzle` or `--orm none`, `--runtime workers`
- **MongoDB**: Requires `--orm mongoose` or `--orm prisma`
- **Convex**: Forces `--no-auth`, `--database none`, `--orm none`, `--api none`, `--runtime none`, `--db-setup none`; sets `--examples todo`; Solid frontend is not supported with Convex
- **PWA**: Requires compatible web frontend
- **Tauri**: Requires compatible web frontend
- **AI Examples**: Not compatible with `--backend elysia` or `--frontend solid`
- **tRPC + Nuxt/Svelte/Solid**: Use `--api orpc` (tRPC is not supported with `nuxt`, `svelte`, or `solid`)
- **Todo Example**: Requires a database when a backend (other than Convex) is selected
- **Web Deploy**: `--web-deploy workers` requires selecting a web frontend
- **Examples with `--api none`**: Cannot select examples when `--api none` (unless `--backend convex`)
- **Runtime `none`**: Only allowed with `--backend convex` or `--backend none`
- **Mongoose ORM**: Requires `--database mongodb`
- **Drizzle ORM**: Not compatible with `--database mongodb`
- **Database requires ORM**: Selecting a database requires a non-`none` ORM
- **ORM requires database**: Selecting a non-`none` ORM requires a database
- **Auth requires database**: `--auth` requires a non-`none` database
- **DB Setup constraints**:
  - `--db-setup turso` → requires `--database sqlite`
  - `--db-setup neon` → requires `--database postgres`
  - `--db-setup prisma-postgres` → requires `--database postgres`
  - `--db-setup mongodb-atlas` → requires `--database mongodb`
  - `--db-setup supabase` → requires `--database postgres`
  - `--db-setup d1` → requires `--database sqlite` and `--runtime workers`
  - `--db-setup docker` → not compatible with `--database sqlite` or `--runtime workers`

The CLI will validate compatibility and show helpful error messages for invalid combinations.