CLI

The Pearl CLI scaffolds new projects and generates boilerplate files so you can skip the repetitive setup and focus on your application logic. Every generated file follows the same conventions — correctly placed, correctly named, ready to fill in.

Install

Use it via npx without installing, or install globally to use pearl as a command:

···

# No install needed
npx pearl new my-api

# Or install globally
npm install -g @pearl-framework/cli
pearl new my-api

Commands

Command	What it does
`pearl new <name>`	Scaffold a complete new project
`pearl serve`	Start a hot-reload dev server
`pearl migrate`	Run pending SQL migrations
`pearl make:controller <Name>`	Generate a controller class
`pearl make:model <Name>`	Generate a model with Drizzle schema
`pearl make:middleware <Name>`	Generate a middleware function
`pearl make:request <Name>`	Generate a FormRequest validation class
`pearl make:event <Name>`	Generate an event class
`pearl make:listener <Name>`	Generate a listener class
`pearl make:job <Name>`	Generate a background job class
`pearl make:mail <Name>`	Generate a Mailable email class
`pearl make:migration <name>`	Generate a timestamped SQL migration file

Scaffold a new project

pearl new creates a full project structure, installs dependencies, and generates a .env from .env.example:

···

npx pearl new my-api
cd my-api

# Edit .env with your database and Redis credentials
# then start the dev server:
pearl serve

Generator examples

All generators follow the same pattern — PascalCase name, correct directory, correct file extension:

···

pearl make:controller PostController
# → src/controllers/PostController.ts

pearl make:model Post
# → src/models/Post.ts  (includes Drizzle schema)

pearl make:request CreatePostRequest
# → src/requests/CreatePostRequest.ts

pearl make:event UserRegisteredEvent
# → src/events/UserRegisteredEvent.ts

pearl make:listener SendWelcomeEmailListener
# → src/listeners/SendWelcomeEmailListener.ts

pearl make:job SendWelcomeEmailJob
# → src/jobs/SendWelcomeEmailJob.ts

pearl make:mail WelcomeMail
# → src/mail/WelcomeMail.ts

pearl make:migration create_posts_table
# → database/migrations/20260101_create_posts_table.sql

Dev server

pearl serve starts your app with hot reload — any change to a .ts file restarts the server automatically:

···

pearl serve
# 🦪 Pearl running on http://localhost:3000
# Watching for changes...