npm package: @tacobase/cli
Description: CLI tool for managing tacobase instances
Author: tacobase
Latest version: 0.1.4

<div align="center">
  <a href="https://tacobase.dev">
    <img src="https://www.tacobase.dev/taco-logo.svg" alt="tacobase logo" width="80" height="80">
  </a>

  <h3>@tacobase/cli</h3>

  <p>
    The <code>taco</code> command. Obviously.
  </p>

  <p>
    <a href="https://www.npmjs.com/package/@tacobase/cli"><img src="https://img.shields.io/npm/v/@tacobase/cli?color=F5A623&label=npm" alt="npm version"></a>
    <a href="https://www.npmjs.com/package/@tacobase/cli"><img src="https://img.shields.io/npm/dm/@tacobase/cli?color=F5A623" alt="npm downloads"></a>
    <a href="https://github.com/tacobase/tacobase/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-F5A623" alt="MIT license"></a>
  </p>

  <p>
    <a href="https://tacobase.dev/docs">Documentation</a>
    ·
    <a href="https://tacobase.dev/dashboard">Dashboard</a>
    ·
    <a href="https://github.com/tacobase/tacobase/issues">Report Bug</a>
  </p>
</div>

---

```bash
npm install -g @tacobase/cli
```

---

## Quick start

```bash
taco login                        # Authenticate
taco init my-app --template next  # Scaffold a new project
cd my-app && npm install
taco dev --with-app               # Postgres + dev server, one command
```

🌮 Wrapped. You're building.

---

## Table of Contents

- [taco login](#taco-login)
- [taco init](#taco-init)
- [taco dev](#taco-dev)
- [taco typegen](#taco-typegen)
- [taco status](#taco-status)
- [taco logs](#taco-logs)
- [taco seed](#taco-seed)
- [taco doctor](#taco-doctor)
- [taco dashboard](#taco-dashboard)
- [Configuration](#configuration)
- [Framework templates](#framework-templates)
- [Troubleshooting](#troubleshooting)

---

## taco login

Authenticate with tacobase. Opens a browser session to sign in.

```bash
taco login
```

Your auth token is stored in `~/.taco/config.json`. Sign in once, taco forever.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

---

## taco init

Scaffold a new tacobase project. Creates a cloud instance, generates your API key, and optionally sets up a framework template.

```bash
taco init my-project                 # Interactive template picker
taco init my-app --template next     # Next.js + App Router
taco init my-app --template react    # React + Vite
taco init my-app --template vue      # Vue
taco init my-app --template svelte   # Svelte
```

What happens:
1. Creates a tacobase instance in the dashboard
2. Generates an API key (`tbk_...`)
3. Writes `.env.local` with `TACOBASE_URL` and `TACOBASE_API_KEY`
4. Scaffolds your project with the selected framework template

**Options:**
- `-t, --template <template>` — Framework template (`next`, `react`, `vue`, `svelte`)

<p align="right">(<a href="#readme-top">back to top</a>)</p>

---

## taco dev

Spins up a local Postgres instance via Docker. Your database, local, zero config.

```bash
taco dev                         # Postgres on :5432
taco dev --with-app              # Postgres + npm run dev
taco dev --run "vite"            # Postgres + custom app command
taco dev -p 9090 --run "vite"   # Custom port + custom command
```

What it does:
1. Starts a `postgres:16` Docker container named `tacobase-dev-postgres`
2. Prints your local `DATABASE_URL`
3. Injects `DATABASE_URL` and `DATABASE_URL_UNPOOLED` into your app process
4. Tears everything down on `Ctrl+C` — clean exit, no leftovers

**Options:**
- `-p, --port <port>` — Postgres port (default: `5432`)
- `-a, --with-app` — Also run `npm run dev`
- `-r, --run <command>` — Custom command to start your app

> **Prerequisite:** [Docker Desktop](https://www.docker.com/products/docker-desktop) must be installed and running.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

---

## taco typegen

Generate TypeScript types from your live collection schemas. Run once, get autocomplete forever.

```bash
taco typegen                          # → ./src/types/tacobase.ts
taco typegen --output ./types/db.ts   # Custom output path
taco typegen --watch                  # Auto-regenerate on schema changes
taco typegen --watch --interval 10    # 10-second poll interval
```

**Example output:**

```typescript
export interface PostsRecord extends BaseRecord {
  title: string;
  content: string;
  author: string;
  published: boolean;
}

export type CollectionName = 'posts' | 'users' | 'comments';
```

Comes with a typed `db` instance — zero extra setup:

```typescript
import { db } from './src/types/tacobase'

const posts = await db.collection('posts').getList(1, 20)
//                                ^-- autocomplete  ^-- PostsRecord[]
posts.items[0].title  // ✓ typed
```

**Options:**
- `-o, --output <path>` — Output file path (default: `./src/types/tacobase.ts`)
- `-i, --instance <id>` — Instance ID (defaults to current project)
- `-w, --watch` — Watch for schema changes and regenerate
- `--interval <seconds>` — Poll interval in watch mode (default: `5`)

<p align="right">(<a href="#readme-top">back to top</a>)</p>

---

## taco status

Check what's cooking with your current project.

```bash
taco status
taco status --instance <instance-id>
```

**Options:**
- `-i, --instance <id>` — Instance ID (defaults to current project)

<p align="right">(<a href="#readme-top">back to top</a>)</p>

---

## taco logs

Tail your project logs. Great for watching things go sideways in real time.

```bash
taco logs                   # Last 100 lines
taco logs --tail 50         # Last 50 lines
taco logs --follow          # Stream in real-time
taco logs --instance <id>   # Specific project
```

**Options:**
- `-n, --tail <lines>` — Number of lines (default: `100`)
- `-f, --follow` — Stream logs in real-time
- `-i, --instance <id>` — Instance ID

<p align="right">(<a href="#readme-top">back to top</a>)</p>

---

## taco seed

Seed your collections with data. Point at a file, run it, done.

```bash
taco seed                          # Auto-detects tacobase.seed.{ts,js,json}
taco seed --file ./data/seed.json  # Explicit file
taco seed --reset                  # Wipe existing data first, then seed
taco seed --reset --file seed.ts
```

**Options:**
- `-f, --file <path>` — Path to seed file
- `-r, --reset` — Clear existing data before seeding
- `-i, --instance <id>` — Instance ID

<p align="right">(<a href="#readme-top">back to top</a>)</p>

---

## taco doctor

Runs diagnostic checks. Something's not working? Start here.

```bash
taco doctor
taco doctor --instance <id>
```

<p align="right">(<a href="#readme-top">back to top</a>)</p>

---

## taco dashboard

Open your project dashboard in the browser.

```bash
taco dashboard
taco dashboard --instance <instance-id>
```

<p align="right">(<a href="#readme-top">back to top</a>)</p>

---

## Configuration

Stored in `~/.taco/config.json`:

```json
{
  "authToken": "your-auth-token",
  "currentInstance": "inst_abc123",
  "instances": {
    "inst_abc123": {
      "id": "inst_abc123",
      "name": "my-project",
      "url": "https://my-project.tacobase.dev",
      "apiKey": "tbk_abc123..."
    }
  }
}
```

<p align="right">(<a href="#readme-top">back to top</a>)</p>

---

## Framework templates

### Next.js

App Router, TypeScript, `@tacobase/client` and `@tacobase/react` pre-wired.

```bash
taco init my-app --template next
cd my-app && npm install && npm run dev
```

### React (Vite)

React + Vite + TypeScript, tacobase ready to go.

```bash
taco init my-app --template react
cd my-app && npm install && npm run dev
```

Includes `@tacobase/client`, `@tacobase/react`, `src/tacobase.ts`, and `.env` pre-filled.

### Vue, Svelte — coming soon 🌮

<p align="right">(<a href="#readme-top">back to top</a>)</p>

---

## Troubleshooting

**"You must be logged in"** → Run `taco login`.

**"No instance found"** → Run `taco init` or pass `--instance <id>`.

**"Docker not found" / "Docker daemon is not running"** → Install [Docker Desktop](https://www.docker.com/products/docker-desktop) and make sure it's running before `taco dev`.

**Types not updating** → Run `taco typegen` after modifying collection schemas. Or run with `--watch` so it stays current automatically.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

---

## Related packages

| Package | Description |
|---|---|
| [`@tacobase/client`](https://www.npmjs.com/package/@tacobase/client) | Core SDK — CRUD, auth, realtime, storage |
| [`@tacobase/react`](https://www.npmjs.com/package/@tacobase/react) | React hooks — `useAuth`, `useCollection`, `useRealtime` |
| [`@tacobase/taco`](https://www.npmjs.com/package/@tacobase/taco) | Drop-in AI context — installs client + writes `TACOBASE.md` |
| [`@tacobase/mcp-server`](https://www.npmjs.com/package/@tacobase/mcp-server) | MCP server — let your AI manage schema via natural language |

---

[tacobase.dev](https://tacobase.dev) · [docs](https://tacobase.dev/docs) · [github](https://github.com/tacobase/tacobase) · [issues](https://github.com/tacobase/tacobase/issues)

## License

MIT