prisma-cli

prisma is the public-beta command-line interface for the Prisma Developer Platform, published as a release candidate under the prisma package. It replaces app-specific tooling with a single binary spanning the traditional Prisma ORM workflow (schema, migrate, db, contract, lsp) and the newer platform surface: authentication, project and branch management, Prisma Postgres provisioning, object-storage buckets, service deployments, and Composer app development.

Internally the published package is a thin shell (packages/prisma in the monorepo) that re-exports the actual command implementation from @prisma/cli, which runs on @prisma/cli-engine — a dedicated execution engine with its own command-family grammar, structured error/result protocol, credential and telemetry subsystems, and a conformance test suite. Every command supports both human-readable and --json output, plus non-interactive flags and headless authentication via PRISMA_SERVICE_TOKEN for CI and agent use.

What You Get

• Unified ORM + platform CLI - one prisma binary covers the schema/migration workflow (db, migration, contract, lsp) and platform operations (project, branch, postgres, bucket, service) instead of separate tools.
• Structured automation output - every command supports --json alongside human-readable output, plus --no-interactive/--yes flags for CI and agent scripts.
• Headless authentication - PRISMA_SERVICE_TOKEN lets CI pipelines and agents run authenticated commands without an interactive login flow.
• Composer app lifecycle - dev/deploy commands run and ship Composer apps directly from the CLI.
• Prisma Postgres management - create, inspect, back up, restore, and delete managed Postgres databases and their connections from the command line.

Common Use Cases

• Deploying a service from CI - a pipeline authenticates with PRISMA_SERVICE_TOKEN, then runs prisma service list/promote with --json to gate a rollout on structured output.
• Provisioning a new environment - a developer runs prisma project create, connects the repo with prisma git connect, and sets secrets via prisma project env add --file .env.
• Managing Prisma Postgres databases - a team creates, backs up, and restores a Prisma Postgres instance without leaving the terminal.
• Running the day-to-day ORM workflow - prisma migrate/db/orm init commands cover the schema and migration flow developers already know from the classic Prisma CLI.

Under The Hood

Architecture

The published prisma package (packages/prisma) is a deliberately thin shell: src/bin.ts re-exports @prisma/cli’s bundled bin so the prisma and prisma-cli binaries share one implementation, and src/config.ts re-exports definePrismaConfig from @prisma/cli-engine so user repos never depend on the engine directly. The real architecture lives in @prisma/cli-engine (packages/cli-engine), which defines a command-family grammar (command-family.ts, commands.ts) validated at construction time — collisions, reserved flags, and grammar violations fail the build, not a user’s run. Execution flows through execution/engine.ts, built on @stricli/core, which resolves a command tree, checks declared “needs” (config sections, credentials) before a handler runs, and settles every run into a typed Result/Diagnostic protocol shared by human rendering and --json output. The Runtime interface injects all environment access (streams, cwd, signals, exit) so the engine never touches Node globals directly, and a documented signal policy (first SIGINT aborts and awaits teardown, second forces exit with 130/143) is engine-owned rather than left to each command.

Tech Stack

TypeScript throughout, targeting Node >=22.18 for the published package (repo dev environment pins Node 24.19 via .node-version), built with tsdown and orchestrated across the pnpm/Turbo monorepo (turbo.json, pnpm-workspace.yaml). Command parsing and routing sit on @stricli/core; supporting libraries include execa for child-process spawning, dotenv for environment loading, @vercel/detect-agent for coding-agent detection, and workspace-internal packages (@prisma/cli-engine, @prisma/composer-cli, @prisma/compute-sdk, @prisma/management-api-sdk, @prisma/orm-toolchain) that the CLI composes rather than reimplements. Biome (v2) handles both linting and formatting across the whole repo.

Code Quality

The engine package carries an extensive Vitest suite (20+ test files covering command-family construction, credential management, telemetry gating, CI detection, engine execution, and even a no-child-process-in-dist guard), plus .test-d.ts/.type-test.ts files that assert on inferred TypeScript types rather than just runtime behavior — an unusually rigorous signal for a CLI. strict: true is enforced repo-wide via the shared @repo/tsconfig base, and CI (pr-quality.yml, test.yml) runs typecheck and a matrix test job across Ubuntu and Windows as required PR checks, so type errors and platform-specific regressions both block merges. Naming and module boundaries are consistent with the documented docs/architecture and docs/product conventions, which the repo’s own ARCHITECTURE.md explicitly tells contributors to follow rather than infer.

What Makes It Unique

Rather than shipping the ORM CLI, a deploy tool, and a platform CLI as separate packages, this repo collapses them behind one binary with one command-family engine, so the grammar, error protocol, and telemetry model are shared infrastructure instead of being reimplemented per surface. The command engine treats validation as a build-time concern (bad flag names, reserved-flag collisions, and config-section mismatches throw during createCli() construction, not at runtime), and telemetry is opt-in by construction — it only activates when a host explicitly wires both a TelemetryDeclaration and a spawnTelemetry runtime seam, with a detached forked sender so reporting never blocks command execution.