Skip to content

feat(cli): Prisma 7 dev subcommands and flags say what to run in Prisma 8 - #429

Merged
SevInf merged 11 commits into
mainfrom
v7-command-redirects
Nov 13, 2026
Merged

SevInf merged 11 commits into
mainfrom
v7-command-redirects

Conversation

@StevenMcClankerton

@StevenMcClankerton StevenMcClankerton commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Linked issue

Refs prisma/prisma-cli#390 (the @prisma/cli-engine 0.10.0 redirect fields this PR uses) and prisma/orm#31027 (the ORM's Prisma 7 commands).

Summary

A Prisma 7 user or agent who runs prisma dev ls, prisma dev start or prisma dev --port 5555 against Prisma 8 now learns in that one run what to do instead, rather than getting "Too many arguments" or "No flag registered". All of them exit 2.

Prisma 7 Code Next actions
dev ls CLI.V7_COMMAND emulator list, emulator list --help
dev start CLI.V7_COMMAND dev --detach, dev --help
dev rm CLI.V7_COMMAND dev --fresh, dev --help
--port, --db-port, --shadow-db-port, --debug on dev CLI.V7_FLAG dev --help
--debug on dev stop CLI.V7_FLAG dev stop --help

Every error's reason ends by saying how to keep using Prisma 7: "To keep using Prisma 7, install its CLI with npm install --save-dev @prisma/prisma7@7 and run prisma7 dev rm <name>." @prisma/prisma7 installs Prisma 7's CLI as a prisma7 binary next to Prisma 8's prisma. Each prisma7 command line includes a placeholder for every value Prisma 7 requires, for example prisma7 dev --port <port>.

The summary wording matches the prisma-cli shell and the ORM, so a v7 command reads the same whichever package answers it.

Testing performed

  • bun test in packages/0-framework/3-tooling/cli: 514 pass, 0 fail.
    • v7-redirects.test.ts runs every path and flag and asserts the code, exit 2, summary, exact reason and exact nextActions in --json output.
    • It also checks the full human output.
  • bun test in packages/9-public/composer-cli: 32 pass. This includes dev ls against the published family, which mounts emulator list.
  • pnpm typecheck, pnpm lint, lint:casts, lint:deps, check:family-static-graph, check:floor-imports, check:orm-pins.
  • deploy --stage output is unchanged on 0.10.0. Its test now asserts the full output.
  • Local-only failures, which I expect CI to pass:
    • check:cli-engine-pin and check:skill-packaging stop in stage-skills.mjs with EACCES from fs.cpSync on a virtiofs mount. check:cli-engine-pin passed its own checks before that point.

Checklist

  • All commits are signed off (git commit -s) per the DCO.
  • I read CONTRIBUTING.md and the change is scoped to one logical concern.
  • The PR title is a conventional commit.
  • Tests are updated.

Notes for the reviewer

  • The engine refuses a flag redirect whose command is not mounted, so a host that mounts this family must mount dev and dev stop. The prisma host already does. The test setups now mount the whole family the way the host does (878af77b). That commit passes on its own against the old family.ts.
  • The base family's dev ls points at emulator list, which only the published family mounts.
  • No version bump here. A stable composer-cli with the 0.10.0 peer needs the usual chore(release) PR after this one.

🤖 Generated with Claude Code

StevenMcClankerton and others added 8 commits November 13, 2026 16:41
0.10.0 lets a redirect name its own error code and summary, a help page
and a docs URL, and several replacement steps or none, which the Prisma 7
command redirects need. The engine now stores a redirect's replacement as
a list of steps, so the family test reads it that way. deploy --stage
settles with the same code, summary, reason and next action as on 0.9.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Steven McClankerton <tatarintsev+clanker@prisma.io>
…host does

The harnesses mounted only the commands each test ran, with dev at the root
and no group, because an older engine could not make dev both a command and
a group. The engine allows that now, and a flag redirect on dev or dev stop
requires the command it names to be mounted. Every harness now mounts the
family's commands with the dev group, as the prisma host does, through one
helper; the composer-cli tests add the dev group the same way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Steven McClankerton <tatarintsev+clanker@prisma.io>
…ma 8

prisma dev ls, dev rm and dev start, and --port, --db-port, --shadow-db-port
and --debug on dev and --debug on dev stop, failed with CLI.INVALID_ARGUMENTS
("Too many arguments" or "No flag registered") and no next step. They now
fail with CLI.V7_COMMAND or CLI.V7_FLAG, exit 2, the summary the prisma
shell uses for its own Prisma 7 redirects, a reason that says what Prisma 8
does instead, and next actions: emulator list for dev ls, dev --detach for
dev start, the CLI docs for dev rm, and the help of dev or dev stop for the
flags.

The dev ls entry names emulator list, which only the published family
mounts. It stays in the base family because the engine does not check that
a help path is mounted; a composer-cli test runs dev ls and emulator list
--help against the published family. A flag redirect does require its
command to be mounted, so a host that mounts this family must mount dev
and dev stop.

The deploy --stage test now asserts its whole settlement, which is the same
as on engine 0.9.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Steven McClankerton <tatarintsev+clanker@prisma.io>
… and the skill

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Steven McClankerton <tatarintsev+clanker@prisma.io>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Steven McClankerton <tatarintsev+clanker@prisma.io>
…d word for word

Prisma 7's dev rm deleted a local server and its data. Its redirect said
Prisma 8 keeps no local servers to remove and offered only dev stop, which
keeps the data. It now names dev --fresh as the replacement, with dev's help,
and says that dev --fresh deletes the app's local services, databases and
buckets and their data in one environment, while dev stop only stops them.

The ports reason now says what an environment is and that dev url takes a
node's address. Both reasons define an environment the same way, from the
--environment flag's own help.

The tests compare every path's and flag's reason exactly, in --json and in
human output, and the human-output test now runs the five flags as well. The
test file's opening doc comment is removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Steven McClankerton <tatarintsev+clanker@prisma.io>
…t name a command

The guide said every Prisma 7 dev error names a command to run. The flags
point only to the command's help. The guide and the skill now say that, and
name dev --fresh for dev rm.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Steven McClankerton <tatarintsev+clanker@prisma.io>
…read as the dev command

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Steven McClankerton <tatarintsev+clanker@prisma.io>
@prisma-gizmo

prisma-gizmo Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

✅ Gizmo reviewed 51de17b — posted 0 inline comment(s) this pass.

Open findings: none

Change walkthrough

This PR adds Prisma 7 → Prisma 8 redirect guidance across the Composer CLI family: retired dev subcommands (dev ls, dev start, dev rm) and retired flags (--port, --db-port, --shadow-db-port, --debug on dev; --debug on dev stop) now fail with CLI.V7_COMMAND / CLI.V7_FLAG errors that name the Prisma 8 replacement, list nextActions, and tell the user to install @prisma/prisma7@7 to keep using Prisma 7. An incremental pass covered the remaining delta in scripts/e2e-verify-deploy-list.ts.

E2E verification script — scripts/e2e-verify-deploy-list.ts previously mounted only deploy and deploy list from the Composer family, because the retired --stage flag on deploy needs a mounted redirect target. With this PR's new V7 flag redirects, that is no longer enough: the engine refuses a flag redirect whose command is not mounted, and the family's flag redirects now also name dev and dev stop (confirmed against the V7_REDIRECTS table in family.ts). The script now mounts the whole family record via commands: family.commands and declares the deploy, dev, and emulator groups those commands mount under, matching how the prisma host mounts the family.

Fit with the codebase — the redirect machinery lives in the CLI family under packages/0-framework/3-tooling/cli with dedicated test coverage in v7-redirects.test.ts, and the composer-cli package's tests mount the full family the same way this script now does. The change keeps the e2e script aligned with that mounting invariant rather than special-casing it.

@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: 4683ff9b-cb15-4eb2-9cbc-f2f3d6fa70fb
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@pkg-pr-new

pkg-pr-new Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/@prisma/composer@429
npm i https://pkg.pr.new/@prisma/composer-cli@429
npm i https://pkg.pr.new/@prisma/composer-prisma-cloud@429

commit: 51de17b

@prisma-gizmo prisma-gizmo Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New findings: none · trace

@prisma-gizmo prisma-gizmo Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No Gizmo finding is open and the head commit has been reviewed. Approving.

The v7Command and v7Flag helpers end each reason with one sentence: install
Prisma 7's CLI with npm install --save-dev @prisma/prisma7@7 and run
prisma7 followed by the Prisma 7 invocation, which includes the flag for a
flag entry. @prisma/prisma7 installs that CLI as a prisma7 binary next to
Prisma 8's prisma. The tests assert the full reason, and the guide and the
skill say what the errors add.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Steven McClankerton <tatarintsev+clanker@prisma.io>

@prisma-gizmo prisma-gizmo Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New findings: none · trace

@prisma-gizmo prisma-gizmo Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No Gizmo finding is open and the head commit has been reviewed. Approving.

Prisma 7's dev rm, dev start and dev stop require a server name, and
--port, --db-port and --shadow-db-port take a port, so the install
sentence's prisma7 command failed when run as written. An entry can now give
its Prisma 7 command line, and the sentence names prisma7 dev rm <name>,
prisma7 dev start <name>, prisma7 dev stop <name> --debug and
prisma7 dev --port <port> (and the same for the other two port flags).
dev ls and dev --debug need no value. Checked against prisma7 dev --help
and each subcommand's --help from @prisma/prisma7 7.10.1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Steven McClankerton <tatarintsev+clanker@prisma.io>

@prisma-gizmo prisma-gizmo Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New findings: none · trace

@prisma-gizmo prisma-gizmo Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No Gizmo finding is open and the head commit has been reviewed. Approving.

SevInf pushed a commit to prisma/prisma-cli that referenced this pull request Nov 13, 2026
…rror (#391)

## Intent

A follow-up to #390. Someone who runs a Prisma 7 command against Prisma
8 and still needs Prisma 7 should also learn how to install and run
Prisma 7's CLI. Every Prisma 7 command and `init` flag error now ends
its `why` with:

> To keep using Prisma 7, install its CLI with `npm install --save-dev
@prisma/prisma7@7` and run `prisma7 init --url <url>`.

`@prisma/prisma7` installs the Prisma 7 CLI as a `prisma7` binary, next
to Prisma 8's `prisma`. It is the package `prisma orm init` installs for
projects coming from Prisma 7. Nothing suggests `npx`.

## Changes

- `packages/cli/src/v7-redirects.ts`: `v7Command` and `v7Flag` append
the sentence, so no entry repeats it. Each `prisma7` command line has a
placeholder for every value Prisma 7 requires, so it does something when
run as written. For example, `prisma7 complete <shell>` and `prisma7
init --output <path>`.
- `platform status`: the reason now says no command reports whether
Prisma Data Platform services are up. Before, it described an account
status, which is not what Prisma 7's command shows.
- `packages/cli/tests/v7-redirects.test.ts`: the full `why` is asserted
for all 15 entries. A test fails if `npx` appears, or if Prisma 7 or
`prisma7` is mentioned outside the closing sentence.
- `docs/reference/error-reference.md`: the `CLI.V7_COMMAND` and
`CLI.V7_FLAG` entries describe the closing sentence.

The same sentence lands in prisma/orm#31027 and prisma/composer#429 for
the paths they own.

## Verification

- `pnpm typecheck`, `pnpm lint`, `pnpm check:error-reference`
- `pnpm --filter @prisma/cli test`: 1185 passed, 1 skipped
- Every `prisma7 …` command line was run with the real `prisma7` 7.10.1
binary in an empty directory, with the placeholders filled in.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@SevInf
SevInf enabled auto-merge November 13, 2026 18:16
e2e-verify-deploy-list.ts mounted only deploy and deploy list. The family's
Prisma 7 flag redirects name dev and dev stop, and the engine refuses a flag
redirect whose command is not mounted, so building the CLI threw "redirect
for flag 'port' names 'dev', which is not a mounted command" in the Deploy,
verify, destroy job. The script now mounts every command of the family with
the deploy, dev and emulator groups, as the prisma host does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Steven McClankerton <tatarintsev+clanker@prisma.io>

@prisma-gizmo prisma-gizmo Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New findings: none · trace

@prisma-gizmo prisma-gizmo Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No Gizmo finding is open and the head commit has been reviewed. Approving.

@SevInf
SevInf merged commit 88184e4 into main Nov 13, 2026
23 checks passed
@SevInf
SevInf deleted the v7-command-redirects branch November 13, 2026 18:34
opensource-fork-sync Bot pushed a commit to cla7aye15I4nd/opensource-prisma__orm that referenced this pull request Nov 13, 2026
…at to run instead (prisma#31027)

## Linked issue

Refs prisma/prisma-cli#390 (the `@prisma/cli-engine` 0.10.0 redirect
fields this PR uses). The same Prisma 7 install sentence lands in
prisma/prisma-cli#391 and prisma/composer#429.

## Summary

A Prisma 7 user or agent who runs `prisma generate`, `prisma db push` or
`prisma migrate dev` against Prisma 8 now learns in that one run what
replaced the command and what to run next, instead of getting
`CLI.UNKNOWN_COMMAND`. Each of the 14 Prisma 7 paths the ORM owns fails
with `CLI.V7_COMMAND` and exit 2. Where Prisma 8 has an equivalent, the
answer lists it as `run-command` steps with a pointer to its `--help`.
Where there is none (`studio`, `validate`, `db seed`, `db execute`), it
links to the CLI docs.

- New: `generate` → `contract emit`, `format` → `contract format`, `db
pull` → `contract infer`, `db push` → `db update`, plus `validate`,
`studio`, `db seed`, `db execute` with no equivalent.
- The six existing `migrate *` redirects move from `CLI.COMMAND_MOVED`
to `CLI.V7_COMMAND` with the shared summary, and keep their mappings.
`migrate dev` now lists its three commands as ordered steps.
- Every reason ends with how to install and run Prisma 7's CLI: "To keep
using Prisma 7, install its CLI with `npm install --save-dev
@prisma/prisma7@7` and run `prisma7 generate`."
- `migrate dev`, `deploy`, `status`, `reset` and `resolve` keep their
condition instead: "While Prisma 7 still owns this project's migrations,
install its CLI with … and run `prisma7 migrate dev` instead."
- Each `prisma7` command line has a placeholder for every value Prisma 7
requires, for example `prisma7 db execute --file <path>` and `prisma7
migrate resolve --applied <migration>`.
  - Nothing suggests `npx`.
- `migration apply` and the `migration status` flag redirects are
unchanged.
- Every `@prisma/cli-engine` pin moves to 0.10.0, with an
upgrade-instructions fragment.

The summary wording matches the prisma-cli shell and composer-cli, so a
v7 command reads the same whichever repo answers it.

## Testing performed

- `vitest run test/orm/cli.test.ts`: 31 passed. One case per Prisma 7
path checks the code, exit 2, the summary, the reason and the exact
`nextActions`.
- `pnpm --filter @internal/cli typecheck`, `pnpm lint:agent`, `pnpm
lint:deps:agent`, `node scripts/check-upgrade-coverage.mjs --mode pr`,
`node scripts/list-error-codes.mjs --verify`.
- `pnpm --filter @internal/cli test`: 2373 passed, and the 40 failures
are all specific to the local machine:
- 39 `init-prisma7-*` tests fail with `EACCES` from `fs.cpSync` on a
virtiofs mount.
  - 1 test, `no-parallel-ci-detection`, times out.
  - CI should run both normally.
- `pnpm typecheck` passes except `prisma7-adoption`, which can't
download Prisma 7 engines for NixOS locally.

## Skill update

`skills/prisma-8/references/migrations.md` now names `CLI.V7_COMMAND`
and says how to install and run Prisma 7's CLI (`prisma7 migrate
<command>`). `docs/reference/error-reference.md` documents the code, and
the Migration System architecture doc's redirect table lists all 14
paths.

## Checklist

- [x] All commits are signed off (`git commit -s`) per the
[DCO](../CONTRIBUTING.md#developer-certificate-of-origin-dco).
- [x] Tests are updated.
- [x] The **Skill update** section above is filled in.

## Notes for the reviewer

- The first commit moves the engine pin only. The redirect test expects
the engine's new list-form `replacement` and is updated in the second
commit, so the first commit fails that test on its own. Squash-merging
avoids this.
- `db execute`'s reason says "a script file of statements" rather than
"SQL", because of the framework vocabulary lint.

🤖 Generated with [Claude Code](https://claude.com/claude-code)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

<!-- coderabbit-ai-generated:v1 -->

## Summary by CodeRabbit

* **Documentation**
* Updated guidance for retired Prisma 7 commands, including how to
install and run the Prisma 7 CLI and which Prisma 8 alternatives or
documentation to use.
* Added migration-specific guidance, including a step-by-step workflow
for `migrate dev` and the `db sign` alternative for `migrate resolve`.
* **Bug Fixes**
* Prisma 7 commands now return a dedicated error code, distinguishing
them from other removed commands and helping scripts identify the
required next steps.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Steven McClankerton <tatarintsev@prisma.io>
Co-authored-by: Steven McClankerton <tatarintsev@prisma.io>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
wmadden-electric added a commit that referenced this pull request Nov 16, 2026
Brings in #424 (prisma dev stops services before exiting), #426 (deploy copies no local value to platform variables), #429 and the v0.39.0 release.

#426 carried the deploy preflight's findings to the Alchemy child in PRISMA_COMPOSER_PREFLIGHT_FINDINGS. Deploy now runs in process, so the findings reach lower() as a value, LowerOptions.findings, and that environment variable and its reader are gone. prisma deploy repeats the list of platform variables with no value at the end of its human output, as the child's report did on main.

This branch's ADR-0064 becomes ADR-0065, since main owns ADR-0064.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants