# CLI Reference

The Quickback CLI is the fastest way to create, compile, and manage your backend projects.

## Installation

```bash
# One-shot via npx — recommended for first run
npx @quickback-dev/cli start

# Or install globally for repeat use
npm install -g @quickback-dev/cli
```

## Commands

### Start a Project (interactive)

```bash
quickback start
```

Interactive onboarding designed for new users. No flags required.

- Prompts for a template (curated free-tier picker: `cloudflare`, `todos`, `blog`, `empty`)
- Prompts for a project name (defaults to the current directory's name if empty)
- Auto-detects whether to scaffold in-place or create a `./<name>/` subdirectory
- Defers login until just before the compile step — cancel at the auth prompt and the scaffold stays on disk, ready for `quickback compile` later

**Example:**
```bash
mkdir my-app && cd my-app
npx @quickback-dev/cli start
```

### Create a Project (scriptable)

```bash
quickback create <template> <name>
```

**Templates:**
- `cloudflare` — Cloudflare Workers + D1 + Better Auth, bare scaffold (free)
- `todos` — Working todos example with masking + actions + a named view (free)
- `blog` — Single-tenant blog, PUBLIC reads, admin writes (free)
- `empty` — Cloudflare scaffold, no example features (free)
- `saas` — Full B2B SaaS: orgs, R2 file storage, webhooks, split databases, realtime (pro)

**Example:**
```bash
quickback create todos my-app
```

This scaffolds a complete project with:
- `quickback.config.ts` — Project configuration
- `quickback/features/` — Your table definitions
- Example feature with full security configuration (for `todos` / `blog` / `saas`)

See the [Templates](/compiler/getting-started/templates) page for a deeper guide on choosing between them.

### Compile Definitions

```bash
quickback compile
```

Reads your definitions and generates:
- Database migrations (Drizzle)
- API route handlers (Hono)
- TypeScript client SDK
- OpenAPI specification

Run this after making changes to your definitions.

#### Generated `src/` is hermetic

Every file under `src/` carries a `Generated by quickback.dev` header and is owned by the compiler. Before each compile writes its output, the CLI:

1. Snapshots the existing `src/` tree to `quickback/.archives/src-<ISO-timestamp>/` (a plain recursive copy — `cp -R` semantics, no compression).
2. Wipes `src/` entirely.
3. Writes the fresh manifest from the compiler.

This prevents stale output: removed features stop leaving orphan folders, deleted SPA assets with old content hashes get cleared, and `.DS_Store` files don't keep retired directories alive.

The most recent **3** archives are retained (older ones are pruned automatically). If a compile produces unexpected output, your last-known-good tree is sitting in `quickback/.archives/` ready to grep or copy back:

```bash
ls quickback/.archives/
# src-2026-04-27T16-31-02-014/
# src-2026-04-27T16-29-44-882/
# src-2026-04-27T16-12-19-301/
```

As a safety net, the wipe is **skipped** when the manifest contains zero files for the target directory — that's almost always an upstream compile bug, and we'd rather keep your last working tree than overwrite it with nothing.

### View Documentation

```bash
quickback docs              # List available topics
quickback docs <topic>      # Show documentation for a topic
```

**Available topics:**
- `firewall` - Data isolation layer
- `access` - Role-based permissions
- `guards` - Field protection
- `masking` - PII redaction
- `actions` - Custom business logic
- `api` - CRUD endpoints reference
- `config` - Configuration reference
- `features` - Schema definitions

Documentation is bundled with the CLI and works offline.

### Manage Claude Code Skill

```bash
quickback claude install     # Interactive install
quickback claude install --global   # Install to ~/.claude/skills/
quickback claude install --local    # Install to ./quickback/.claude/
quickback claude update      # Update to latest version
quickback claude remove      # Remove installed skill
quickback claude status      # Check installation status
```

The Quickback skill for Claude Code provides AI assistance for:
- Creating resource definitions with proper security layers
- Configuring Firewall, Access, Guards, and Masking
- Debugging configuration issues
- Understanding security patterns

## Authentication

### Login

```bash
quickback login
```

Uses the [OAuth 2.0 Device Authorization Grant](https://datatracker.ietf.org/doc/html/rfc8628) (RFC 8628) to authenticate securely without exposing tokens in URLs.

**How it works:**

1. The CLI requests a one-time device code from the Quickback API.
2. A code is displayed in your terminal (e.g., `AUL8-H93S`).
3. Your browser opens to the Quickback account page where you approve the code.
4. The CLI detects approval and exchanges it for a session token.
5. If you belong to one organization, it's auto-selected. If you have multiple, you choose one.
6. Credentials are stored locally.

```
$ quickback login

🔐 Quickback Login

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Your code: AUL8-H93S

  Visit: https://account.quickback.dev/cli/authorize

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Login successful!
Welcome, Paul Stenhouse!

Using organization: Acme
✓ Active organization: Acme
```

This flow works in headless environments (SSH, containers, WSL) since it doesn't require a localhost callback.

### Logout

```bash
quickback logout
```

Clears stored credentials from `~/.quickback/credentials.json`.

### Check Auth Status

```bash
quickback whoami
```

Shows the currently authenticated user, organization, and token expiration.

### Credential Storage

Credentials are stored at `~/.quickback/credentials.json`:

```json
{
  "token": "...",
  "user": {
    "id": "...",
    "email": "paul@example.com",
    "name": "Paul Stenhouse",
    "tier": "free"
  },
  "expiresAt": "2026-02-16T01:42:21.519Z",
  "organization": {
    "id": "...",
    "name": "Acme",
    "slug": "acme"
  }
}
```

Sessions expire after 7 days. Run `quickback login` again to re-authenticate.

### Organizations

After login, the CLI auto-selects your organization:
- **One organization** - automatically set as active.
- **Multiple organizations** - you're prompted to choose one.

The active organization is stored in your credentials and sent with compile requests, so the compiler knows which org context to use.

## Quick Start

```bash
# 1. Start a new project (interactive — picks template, scaffolds,
#    prompts for login only when needed)
mkdir my-app && cd my-app
npx @quickback-dev/cli start

# 2. Run locally
npm run dev
```

Or the scriptable form:

```bash
# 1. Create the project (scaffolds + compiles + installs)
quickback create todos my-app   # prompts for login on first compile
cd my-app

# 2. Run
npm run dev

# 3. Recompile after editing definitions
quickback compile
```

## Options

| Flag | Description |
|------|-------------|
| `-v, --version` | Show version number |
| `-h, --help` | Show help message |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `QUICKBACK_API_KEY` | API key for authentication (alternative to `quickback login`) |
| `QUICKBACK_API_URL` | Override compiler API URL |

### API Key Authentication

Use an API key instead of interactive login. Useful for CI/CD pipelines and automated workflows:

```bash
# Pass API key for a single command
QUICKBACK_API_KEY=your_api_key quickback compile

# Or export for the session
export QUICKBACK_API_KEY=your_api_key
quickback compile
```

The API key takes precedence over stored credentials from `quickback login`.

You can create API keys from your [Quickback account](https://account.quickback.dev/profile). Each key is scoped to your organization.

### Custom Compiler URL

Point the CLI to a different compiler (local or custom):

```bash
# Use a local compiler
QUICKBACK_API_URL=http://localhost:3020 quickback compile

# Or export for the session
export QUICKBACK_API_URL=http://localhost:3020
quickback compile
```

See [Local Compiler](/compiler/cloud-compiler/local-compiler) for running the compiler locally with Docker.

## Troubleshooting

### "Command not found: quickback"

Make sure the CLI is installed globally:
```bash
npm install -g @quickback-dev/cli
```

Or use npx (no global install needed):
```bash
npx @quickback-dev/cli start
```

### Compile errors

1. Check your `quickback.config.ts` exists and is valid
2. Ensure all tables in `quickback/features/` have valid exports
3. Run `quickback compile` with `--verbose` for detailed output
4. For rename-related Drizzle failures in CI/headless runs, configure `compiler.migrations.renames` in `quickback.config.ts`

### Authentication issues

Clear credentials and re-authenticate:
```bash
quickback logout
quickback login
```

### "Could not load organizations"

This can happen if your session token expired or if the API is temporarily unavailable. Re-login:
```bash
quickback logout
quickback login
```
