@roostjs/cli Guides

Task-oriented instructions for scaffolding, code generation, migrations, and deployment.

How to scaffold a new project

Use roost new with flags to include the packages your application needs. Generated projects are deployment-ready on Cloudflare Workers.

# Minimal project
roost new my-app

# With AI agents
roost new my-app --with-ai

# Full-featured app
roost new my-app --with-ai --with-billing --with-queue

# Overwrite existing directory
roost new my-app --force

After scaffolding, copy .env.example to .dev.vars and fill in your credentials before running roost dev.

cd my-app
cp .env.example .dev.vars
# Edit .dev.vars with your credentials
roost dev

How to generate models, controllers, and other code

Use the make: generators to create boilerplate files. Each generator creates a file in the conventional location with TODO comments for customization.

# Model + migration
roost make:model Post

# Controller
roost make:controller PostController

# Background job
roost make:job SendWelcomeEmail

# AI agent
roost make:agent SupportAgent

# AI tool
roost make:tool OrderStatusTool

# MCP server
roost make:mcp-server AppServer

# Middleware
roost make:middleware RateLimit

Generator names are used as class names directly. Use PascalCase for classes (PostController).

How to run migrations

Run all pending migrations with roost migrate.

# Run pending migrations
roost migrate

# Generate migration files from Drizzle schema changes
roost migrate:generate

Migrations run in filename order. The CLI tracks which migrations have run in a migrations table in your D1 database. See the migrations guide for defining columns and indexes.

How to deploy your application

Use roost deploy to build and push to Cloudflare Workers in one step.

# Build and deploy
roost deploy

Before deploying, make sure your production secrets are set in the Cloudflare dashboard — roost deploy does not push .dev.vars values.

# Set a secret for production (interactive)
wrangler secret put STRIPE_SECRET_KEY

# Or use the dashboard:
# Workers > my-app > Settings > Variables

After first deployment, run migrations against the production D1 database:

# Run migrations against production D1
wrangler d1 execute my-app-db --remote --file=database/migrations/0001_create_users.sql

See the deployment guide for custom domains, preview deployments, and CI/CD setup.