CLI Reference

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

Installation

npm install -g @kardoe/quickback

Commands

Create a Project

quickback create <template> <name>

Templates:

• cloudflare - Cloudflare Workers + D1 + Better Auth (free)
• bun - Bun + SQLite + Better Auth (free)
• turso - Turso/LibSQL + Better Auth (pro)

Example:

quickback create cloudflare my-app

This scaffolds a complete project with:

• quickback.config.ts - Project configuration
• definitions/features/ - Your table definitions
• Example todos feature with full security configuration

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.

Initialize Structure

quickback init

Creates the Quickback folder structure in an existing project:

quickback/
  definitions/
    features/
    auth/
  quickback.config.ts

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. Create a new project
quickback create cloudflare my-app
cd my-app

# 2. Define your tables in definitions/features/
# (Already has example todos feature)

# 3. Compile
quickback compile

# 4. Run
npm run dev

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 @kardoe/quickback

Or use npx:

npx @kardoe/quickback create cloudflare my-app

Compile errors

1. Check your quickback.config.ts exists and is valid
2. Ensure all tables in definitions/features/ have valid exports
3. Run quickback compile with --verbose for detailed output

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