CLI Reference

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

Installation

# 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)

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:

mkdir my-app && cd my-app
npx @quickback-dev/cli start

Create a Project (scriptable)

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:

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 page for a deeper guide on choosing between them.

Compile Definitions

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:

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

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

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

quickback login

Uses the OAuth 2.0 Device Authorization Grant (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

quickback logout

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

Check Auth Status

quickback whoami

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

Credential Storage

Credentials are stored at ~/.quickback/credentials.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

# 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:

# 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

Environment Variables

API Key Authentication

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

# 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. Each key is scoped to your organization.

Custom Compiler URL

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

# 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 for running the compiler locally with Docker.

Troubleshooting

"Command not found: quickback"

Make sure the CLI is installed globally:

npm install -g @quickback-dev/cli

Or use npx (no global install needed):

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:

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:

quickback logout
quickback login