CLI Reference

forge new

Create a new project.

forge new [project-name] --demo|--minimal [options]

Option	Description
--demo	Full demo project with User CRUD, jobs, crons, workflows, webhooks
--minimal	Clean scaffolding with empty directories and commented examples
--output, -o <dir>	Output directory (defaults to project name)
--no-lock	Skip generating bun.lock before initial commit

One of --demo or --minimal is required.

# Demo project with working examples
forge new my-app --demo

# Clean slate for experienced developers
forge new my-app --minimal

# Custom output directory
forge new my-app --demo --output /path/to/projects/my-app

---

forge dev

Start the development environment.

forge dev [action] [options]

Option	Description
--docker	Run with Docker Compose instead of cargo/bun
--no-open	Skip automatic browser open

Actions

Action	Description
(none)	Start backend + frontend + embedded PostgreSQL
down	Stop the development environment
down --clear	Stop and remove target/ and pg_data/ directories

# Start development (embedded postgres, hot reload)
forge dev

# Start without opening browser
forge dev --no-open

# Run with Docker Compose
forge dev --docker

# Stop environment
forge dev down

# Stop and clean build artifacts
forge dev down --clear

Services

When running, the following services are available:

Service	URL
Frontend	http://localhost:5173
Backend	http://localhost:8080

Requirements (bare metal)

Tool	Minimum Version
cargo	1.92+
cargo-watch	any
bun	1.3+

---

forge check

Validate project configuration and dependencies.

forge check [options]

Option	Description
--config, -c <path>	Path to forge.toml (default: ./forge.toml)
--no-db	Skip database connectivity check

Checks Performed

• forge.toml validity and required sections
• Cargo.toml and forge dependency
• Directory structure (src/, src/schema/, src/functions/, migrations/)
• Migration file naming and -- @up markers
• Function files with forge macros
• Schema files with #[forge::model]
• Rust linting (cargo fmt, clippy)
• Environment variables and DATABASE_URL
• Database connectivity
• Frontend configuration (if present)
• Frontend linting (ESLint, Prettier)

# Full project check
forge check

# Skip database check (offline validation)
forge check --no-db

# Custom config location
forge check --config ./config/forge.toml

---

forge add

Add a new component to the project.

forge add [component] [name]

Components

Component	Description	Output File
model	Database model with #[forge::model]	src/schema/[name].rs
query	Read-only query function	src/functions/[name].rs
mutation	Write operation function	src/functions/[name].rs
job	Background job with retry logic	src/functions/[name]_job.rs
cron	Scheduled task	src/functions/[name]_cron.rs
workflow	Multi-step durable workflow	src/functions/[name]_workflow.rs

Names are normalized: UserProfile becomes user_profile (snake_case for files/functions) and UserProfile (PascalCase for structs).

# Add a model
forge add model User

# Add a query
forge add query get_active_users

# Add a mutation
forge add mutation create_order

# Add a background job
forge add job send_email

# Add a scheduled task
forge add cron cleanup_expired

# Add a workflow
forge add workflow user_onboarding

---

forge generate

Generate TypeScript client code from Rust schema.

forge generate [options]

Option	Description
--force	Force regeneration even if files exist
--output, -o <dir>	Output directory (default: frontend/src/lib/forge)
--src, -s <dir>	Source directory to scan (default: src)
--skip-runtime	Only regenerate types, skip runtime update
--yes, -y	Auto-accept prompts (useful for CI)

Generated Files

File	Description
types.ts	TypeScript interfaces from Rust models
api.ts	Function bindings (queries, mutations)
stores.ts	Svelte store exports
runes.svelte.ts	Svelte 5 runes helpers
index.ts	Re-exports all modules
.forge/svelte/	Runtime package (@forge/svelte)

# Generate all TypeScript code
forge generate

# Force regenerate everything
forge generate --force

# Only update types (keep runtime)
forge generate --skip-runtime

# CI mode (no prompts)
forge generate -y

# Custom directories
forge generate --src ./backend/src --output ./web/src/lib/forge

---

forge migrate

Manage database migrations.

forge migrate [action] [options]

Option	Description
--config, -c <path>	Configuration file path (default: forge.toml)
--migrations-dir, -m <dir>	Migrations directory (default: migrations)

Actions

Action	Description
up	Run all pending migrations
down [count]	Rollback the last N migrations (default: 1)
status	Show migration status

# Run pending migrations
forge migrate up

# Rollback last migration
forge migrate down

# Rollback last 3 migrations
forge migrate down 3

# Check migration status
forge migrate status

# Use custom paths
forge migrate up --config ./config/forge.toml --migrations-dir ./db/migrations

Migration File Format

Migration files must be named NNNN_name.sql (e.g., 0001_initial.sql) and contain -- @up marker.

-- @up
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email TEXT UNIQUE NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now()
);

-- @down
DROP TABLE users;

---

Environment Variables

Variable	Description	Used By
DATABASE_URL	PostgreSQL connection string	All commands
RUST_LOG	Log level (e.g., info, debug, trace)	forge dev
HOST	Backend host (default: 0.0.0.0)	forge dev
PORT	Backend port (default: 8080)	forge dev

---

Exit Codes

Code	Description
0	Success
1	Error (configuration, validation, or runtime failure)