@pearl-framework/cli

Scaffold and generate Pearl.js projects from the command line.

Installation

npm install -g @pearl-framework/cli

Or use directly without installing:

npx @pearl-framework/cli new my-app

pearl new — Scaffold a Project

Creates a new Pearl.js project with all packages, TypeScript, Vitest, and hot-reload configured:

pearl new my-app

Options:

| Flag | Description | |---|---| | --pnpm | Use pnpm | | --yarn | Use yarn | | --npm | Use npm | | --no-install | Skip dependency install |

pearl new my-app --pnpm
pearl new my-app --no-install

What gets created:

my-app/
├── src/
│   ├── server.ts                    ← entry point
│   ├── providers/
│   │   └── AppServiceProvider.ts
│   ├── controllers/
│   ├── schema/                      ← Drizzle table definitions
│   ├── requests/
│   ├── jobs/
│   ├── events/
│   ├── listeners/
│   ├── mail/
│   └── middleware/
├── database/
│   └── migrations/
├── tests/
│   └── example.test.ts
├── .env                             ← pre-filled with sensible defaults
├── .env.example
├── package.json
├── tsconfig.json
└── vitest.config.ts

After scaffolding, start the dev server:

cd my-app
npm run dev
# → Server running on http://localhost:3000

pearl serve — Dev Server

Start the development server with hot reload powered by tsx watch:

pearl serve
pearl serve --port 8080
pearl serve --host 0.0.0.0

The command looks for src/server.ts first, then falls back to src/main.ts.

Generators

All generators create files in the conventional location. Use --force to overwrite an existing file.

Controllers

pearl make:controller Post               # src/controllers/PostController.ts
pearl make:controller Post --resource    # with index, show, store, update, destroy methods

Models & Migrations

pearl make:model Post                    # src/models/Post.ts
pearl make:model Post --migration        # model + database/migrations/<timestamp>_create_posts.ts
pearl make:migration create_posts_table  # migration only

Middleware

pearl make:middleware RequireAdmin       # src/middleware/RequireAdminMiddleware.ts

Validation

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

Jobs

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

Events & Listeners

pearl make:event UserRegistered                              # src/events/UserRegisteredEvent.ts
pearl make:listener SendWelcomeEmail                        # src/listeners/SendWelcomeEmailListener.ts
pearl make:listener SendWelcomeEmail --event UserRegistered # pre-wired to the event

Mail

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

Resources

pearl make:resource UserResource        # src/resources/UserResource.ts

What's included in every project

| Feature | Details | |---|---| | All @pearl-framework/* packages | Pre-installed and ready to use | | TypeScript | ESM + Bundler module resolution, strict: true | | Hot reload | tsx watch via npm run dev | | Testing | vitest with an example test | | Environment | .env pre-filled for Postgres, Redis, JWT, and mail |

Requirements

• Node.js v20+
• pnpm, yarn, or npm