prisma/prisma

CLI

Active contributors: jacek-prisma, Oleksii Orlenko, Søren Bramer Schmidt

Purpose

packages/cli is the prisma binary itself. It dispatches every top-level subcommand the user can type — init, generate, studio, format, validate, version, debug, telemetry, plus the db and migrate namespaces (which delegate into packages/migrate).

The package publishes as prisma on npm; the CLI executable is built into packages/cli/build/index.js from packages/cli/src/bin.ts.

Directory layout

packages/cli/
├── src/
│   ├── bin.ts                    # CLI executable entry
│   ├── CLI.ts                    # Top-level command dispatch
│   ├── Init.ts                   # prisma init
│   ├── Generate.ts               # prisma generate
│   ├── Format.ts                 # prisma format
│   ├── Validate.ts               # prisma validate
│   ├── Version.ts                # prisma version / -v
│   ├── DebugInfo.ts              # prisma debug
│   ├── Telemetry.ts              # prisma telemetry (internal)
│   ├── Status.ts                 # prisma status
│   ├── Studio.ts                 # prisma studio
│   ├── studio-server.ts          # Runtime-specific Studio server
│   ├── studio-entry.ts           # Studio frontend entry
│   ├── SubCommand.ts             # SubCommand base class
│   ├── status-page.ts            # HTML status page rendering
│   ├── bootstrap/                # Bootstrap helpers (e.g., engine resolution)
│   ├── generate/                 # Generate subcommand internals
│   ├── init/                     # Init subcommand templates and helpers
│   ├── management-api/           # Prisma Management API client (cloud features)
│   ├── mcp/                      # MCP server (Model Context Protocol)
│   ├── platform/                 # Platform-related glue (Accelerate/Pulse)
│   ├── postgres/                 # `prisma postgres` (Prisma Postgres dev server)
│   ├── utils/                    # CLI-specific utilities
│   └── __tests__/                # Jest + Vitest tests
├── build/                         # Build output (CLI bundle, studio bundle)
├── helpers/build.ts              # Package builder
├── jest.config.js
├── vitest.config.ts
└── package.json

Key abstractions

Symbol	File	What it does
`bin.ts` (top-level script)	`packages/cli/src/bin.ts`	Executable shebang. Resolves engines, loads config, instantiates `CLI`
`CLI` class	`packages/cli/src/CLI.ts`	Top-level command parsing. Maps argv to a `Command` implementation
`Command` interface	`packages/cli/src/SubCommand.ts`	The contract every subcommand implements
`Generate`	`packages/cli/src/Generate.ts`	Reads schema → DMMF → invokes generators → writes output
`Init`	`packages/cli/src/Init.ts`	`prisma init` and `prisma init --datasource-provider <provider>` scaffolding
`Studio`	`packages/cli/src/Studio.ts`	Starts the Studio HTTP server and bundles the prebuilt frontend
`Format`	`packages/cli/src/Format.ts`	Formats `.prisma` files via the Wasm PSL formatter
`Validate`	`packages/cli/src/Validate.ts`	Validates schemas via the Wasm parser
`DebugInfo`	`packages/cli/src/DebugInfo.ts`	Prints platform/engine/schema diagnostics (`prisma debug`)
`Version`	`packages/cli/src/Version.ts`	Prints version info for the CLI, `@prisma/client`, and engines
`Telemetry`	`packages/cli/src/Telemetry.ts`	Internal-only command for telemetry verification

How it works

graph TD
    User[User runs prisma <args>] --> Bin[bin.ts]
    Bin --> EngineResolve[Resolve engines via @prisma/engines]
    Bin --> ConfigLoad[Load prisma.config.ts via @prisma/config]
    Bin --> CLI[CLI.ts dispatch]

    CLI -->|init| Init
    CLI -->|generate| Gen[Generate.ts]
    CLI -->|format| Fmt[Format.ts]
    CLI -->|validate| Val[Validate.ts]
    CLI -->|studio| Std[Studio.ts]
    CLI -->|version| Ver[Version.ts]
    CLI -->|db ...| DbCmd[DbCommand → packages/migrate]
    CLI -->|migrate ...| MigCmd[MigrateCommand → packages/migrate]

    Gen -->|reads schema| Schema[(schema.prisma)]
    Gen -->|invokes| Generators[client-generator-ts / client-generator-js / external]
    Generators -->|writes| Generated[(./generated)]

    Std -->|HTTP server| Frontend[Bundled studio.js / studio.css]
    Std -->|queries via| Client[@prisma/client]

bin.ts does the resolve-and-dispatch dance:

Resolve engine binaries via @prisma/engines (downloads happen at install time, not invocation time).
Load prisma.config.ts via @prisma/config. The result is a PrismaConfigInternal carried into every subcommand.
Instantiate CLI from CLI.ts, register the subcommand map, and parse argv.
Hand off to the matched subcommand.

The CLI uses arg (a small commander-like library) for parsing per-subcommand. Help is auto-generated; every command supports -h/--help.

Subcommand inventory

Command	Implementation
`prisma` (no command)	`packages/cli/src/CLI.ts`
`prisma init`	`packages/cli/src/Init.ts`
`prisma generate`	`packages/cli/src/Generate.ts`
`prisma format`	`packages/cli/src/Format.ts`
`prisma validate`	`packages/cli/src/Validate.ts`
`prisma version`	`packages/cli/src/Version.ts`
`prisma debug`	`packages/cli/src/DebugInfo.ts`
`prisma studio`	`packages/cli/src/Studio.ts`
`prisma telemetry`	`packages/cli/src/Telemetry.ts` (internal)
`prisma status`	`packages/cli/src/Status.ts`
`prisma db ...`	`packages/migrate/src/commands/DbCommand.ts`
`prisma migrate ...`	`packages/migrate/src/commands/MigrateCommand.ts`
`prisma postgres ...`	`packages/cli/src/postgres/`
`prisma platform ...`	`packages/cli/src/platform/`
`prisma mcp`	`packages/cli/src/mcp/`

The legacy introspect command is still routed for back-compat; it invokes the same code path as prisma db pull (packages/migrate/src/commands/DbPull.ts).

Studio

prisma studio launches a local HTTP server hosting the Studio frontend. Important implementation notes from AGENTS.md:

The frontend is pre-bundled into packages/cli/build/studio.js and packages/cli/build/studio.css. The React source for Studio is not in this repo.
Studio routes are registered explicitly in Studio.ts; the runtime-specific server bindings live in studio-server.ts.
A regression-prone area: a past Node bug treated GET requests with bodies like HEAD and dropped them. There's listener-level coverage in packages/cli/src/__tests__/studio-server.vitest.ts to prevent recurrence.
To verify Studio in isolation without dragging in bin.ts, run pnpm exec tsx packages/cli/src/Studio.ts with a config object that preserves loadedFromFile. SQLite URLs resolve relative to the config file when loadedFromFile is set.

Bundle size

The CLI bundle is fully self-contained — every internal dependency is bundled by esbuild. The bundle-size CI (bundle-size.yml) enforces ~6MB on packages/cli/build/index.js and ~16MB on the unpacked tarball. Per CONTRIBUTING.md:

The reported bundle size of packages/cli/build/index.js in the size-limit report 📦 comment in the PR needs to stay below ~6MB.

If you change CLI dependencies, expect the bundle-size comment to move and react accordingly.

Integration points

@prisma/engines for engine downloads
@prisma/config for prisma.config.ts loading
@prisma/internals for getDMMF, getConfig, getGenerators, error rendering, etc.
@prisma/migrate as the implementation of db and migrate
@prisma/client-generator-ts and @prisma/client-generator-js for prisma generate
@prisma/generator-helper for the IPC contract that external generators use

Entry points for modification

Add a new subcommand: implement a class that satisfies SubCommand (packages/cli/src/SubCommand.ts), register it in CLI.ts, add tests under packages/cli/src/__tests__/commands/.
Change prisma generate flow: packages/cli/src/Generate.ts and packages/cli/src/generate/.
Change init templates: packages/cli/src/init/.
Studio behavior: Studio.ts + studio-server.ts. Leave the bundled frontend alone unless you're updating the Studio version (handled by update-studio-version.yml).