CLI Reference

Command reference for Quackback development and operations.

Development Commands

Start Development Server

bun run dev

Starts the development server at http://localhost:3000.

Options:

• Hot reloading enabled
• Source maps enabled
• OTP codes printed to console

Build for Production

bun run build

Creates optimized production build in .output/.

Preview Production Build

bun run preview

Preview the production build locally. Run from apps/web/ directory.

Start Production Server

bun run start

Starts the production server. Requires bun run build first. Run from apps/web/ directory.

Database Commands

Run Migrations

bun run db:migrate

Applies pending database migrations. Safe to run multiple times.

Generate Migration

bun run db:generate

Creates a new migration from schema changes. Run after modifying files in packages/db/src/schema/.

Open Drizzle Studio

bun run db:studio

Opens visual database browser at https://local.drizzle.studio.

Seed Demo Data

bun run db:seed

Populates database with demo workspace and sample data.

Reset Database

bun run db:reset

Warning:
This command destroys all data. It drops and recreates the database, then runs migrations. Use with caution.

Code Quality

Lint Code

bun run lint

Runs ESLint checks. Exits with error if issues found.

Type Check

cd apps/web && bun run typecheck

Runs TypeScript compiler in check mode. No output if successful. Must be run from apps/web/ directory.

Generate Routes

cd apps/web && bun run generate:routes

Generates TanStack Router route definitions. Automatically run as part of typecheck.

Testing

Run Unit Tests

bun run test

Runs Vitest unit tests. By default runs in watch mode.

Run Specific Test

bun run test path/to/test.ts

Runs a specific test file.

E2E Tests

bun run test:e2e

Runs Playwright end-to-end tests in headless mode.

E2E with UI

cd apps/web && bun run test:e2e:ui

Opens Playwright's interactive test UI. Must be run from apps/web/ directory.

E2E Headed

cd apps/web && bun run test:e2e:headed

Runs E2E tests in visible browser windows. Must be run from apps/web/ directory.

Setup & Utilities

Initial Setup

bun run setup

Tip:
This is the recommended way to get started. It handles all the setup steps in one command.

One-time setup script:

1. Checks prerequisites
2. Installs dependencies
3. Creates .env from template
4. Generates auth secret
5. Starts PostgreSQL
6. Runs migrations

Install Dependencies

bun install

Installs all project dependencies.

Docker Commands

Start Services

docker compose up -d

Starts PostgreSQL and application in background.

View Logs

docker compose logs -f

Follow logs from all services.

docker compose logs app --tail 100

View last 100 lines from app service.

Stop Services

docker compose down

Stops and removes containers (preserves volumes).

Reset Everything

docker compose down -v

Warning:
This command stops containers and removes volumes, destroying all data. Use only when you want a clean slate.

Rebuild Images

docker compose build --no-cache

Rebuilds Docker images from scratch.

Environment Variables

Example

# Copy template
cp .env.example .env

# Generate secret
openssl rand -base64 32

Data Import

Import Data

bun run import

CLI tool for importing data from other feedback platforms.

Import from UserVoice

bun run import:uservoice

Import data from UserVoice exports.

Generate Sample CSV

bun run db:generate-csv

Generates sample CSV data for testing imports.

AI Features

Backfill AI Data

bun run ai:backfill

Backfill AI-generated data (embeddings, sentiment) for existing posts.

Quick Reference

Troubleshooting

Command Not Found

# Ensure Bun is installed
curl -fsSL https://bun.sh/install | bash

# Restart shell or source profile
source ~/.bashrc

Permission Denied

# Fix script permissions
chmod +x scripts/*.sh

Port in Use

# Find process
lsof -i :3000

# Kill it
kill -9 <PID>

Next Steps

• Development Setup - Full setup guide
• Environment Variables - Configuration
• Docker Deployment - Production deployment