Rework the command surface: explicit targeting, delete verbs, workflow-grouped commands

.drive/projects/prisma-cli-v8/assets/command-review.md

@@ -0,0 +1,205 @@
+# Prisma CLI v8 — command review
+
+Every command the CLI mounts, for a semantic review of what each command means and how the tree is organized. Regenerated 2026-08-21 after the command grammar cleanup (PM review: compute config and `init` removed, destroying `remove` commands renamed `delete`, `postgres restore`/`ref`/`migrate`/`format` moved, composer's verbs mounted at the root). Generated from the mounted command tree in `packages/cli/src/cli.ts`. Flags and options are deliberately omitted. 86 commands in total.
+
+The tree has five sources: the platform family (this repo), the Composer family (`@prisma/composer-cli`, re-wrapped to `deploy` and `dev`), the ORM family (`@prisma/orm-toolchain`), the engine's telemetry group, and a few local utilities with no owning package.
+
+## Top-level commands
+
+| Command | Meaning |
+| --- | --- |
+| `dev` | Bring up the application whose root node is the entry's default export, entirely on this machine |
+| `deploy` | Deploy the application whose root node is the entry's default export |
+| `lsp` | Start the Prisma Next language server |
+| `feedback` | Send feedback to the Prisma CLI team |
+
+Notes for the review: there is no top-level `init` (the compute-config wizard was removed; the ORM's project initializer stays at `orm init`) and no `version` command — the engine's `--version` answers.
+
+## `auth` — Manage local authentication for the CLI
+
+| Command | Meaning |
+| --- | --- |
+| `auth login` | Log in to your Prisma platform account |
+| `auth logout` | Clear stored authentication credentials |
+| `auth whoami` | Show the authenticated user and accessible workspace |
+
+### `auth workspace` — Manage local workspace sessions
+
+| Command | Meaning |
+| --- | --- |
+| `auth workspace list` | List your workspace sessions |
+| `auth workspace use` | Make one of your workspace sessions current |
+| `auth workspace logout` | End one workspace session |
+
+## `project` — Manage and inspect your Prisma projects
+
+| Command | Meaning |
+| --- | --- |
+| `project list` | List all projects in your workspace |
+| `project show` | Show this directory's Project binding |
+| `project create` | Create a Project and link this directory |
+| `project link` | Link this directory to a Project |
+| `project rename` | Rename the resolved Project |
+| `project delete` | Delete a Project permanently after exact id confirmation |
+| `project transfer` | Transfer a Project to another workspace after exact id confirmation |
+
+### `project env` — Manage environment variables for the active project
+
+| Command | Meaning |
+| --- | --- |
+| `project env add` | Create a new environment variable |
+| `project env update` | Replace an existing environment variable's value |
+| `project env list` | List environment variable metadata for a scope (no values) |
+| `project env delete` | Delete an environment variable from a scope |
+
+## `postgres` — Manage Prisma Postgres databases for a project
+
+| Command | Meaning |
+| --- | --- |
+| `postgres list` | List Prisma Postgres databases for the resolved project |
+| `postgres show` | Show database metadata without secret values |
+| `postgres create` | Create a Prisma Postgres database and print its one-time connection URL |
+| `postgres usage` | Show usage metrics for a database |
+| `postgres delete` | Delete a database after exact id confirmation |
+
+### `postgres backup` — Inspect and restore platform-created database backups
+
+| Command | Meaning |
+| --- | --- |
+| `postgres backup list` | List backups for a database |
+| `postgres backup restore` | Restore a database from a backup after exact id confirmation |
+
+### `postgres connection` — Manage one-time-view database connection strings
+
+| Command | Meaning |
+| --- | --- |
+| `postgres connection list` | List database connection metadata without secret values |
+| `postgres connection create` | Create a database connection and print its one-time connection URL |
+| `postgres connection rotate` | Rotate connection credentials and print the new one-time connection URL |
+| `postgres connection delete` | Delete a database connection after exact id confirmation |
+
+## `bucket` — Manage object-store buckets for a project
+
+| Command | Meaning |
+| --- | --- |
+| `bucket list` | List object-store buckets for the resolved project |
+| `bucket create` | Create an object-store bucket |
+| `bucket delete` | Delete a bucket and all its access keys |
+
+### `bucket key` — Manage access keys for an object-store bucket
+
+| Command | Meaning |
+| --- | --- |
+| `bucket key list` | List access keys for a bucket |
+| `bucket key create` | Create a bucket access key and print its one-time credentials |
+| `bucket key delete` | Revoke and delete a bucket access key |
+
+## `branch` — View your Platform branches
+
+| Command | Meaning |
+| --- | --- |
+| `branch list` | List Platform branches for the resolved project |
+
+## `git` — Manage Git repository connections for a project
+
+| Command | Meaning |
+| --- | --- |
+| `git connect` | Connect the resolved project to a GitHub repository |
+| `git disconnect` | Disconnect the GitHub repository from the resolved project |
+
+## `service` — Manage services and deployments for a project
+
+| Command | Meaning |
+| --- | --- |
+| `service list` | List the services in a project |
+| `service create` | Create a service in a project |
+| `service show` | Show the service and its current deployment |
+| `service open` | Open the service's live URL |
+| `service logs` | Read logs for a deployment of the service |
+| `service delete` | Delete the service from the resolved branch |
+
+### `service deployment` — Manage deployments for a service
+
+| Command | Meaning |
+| --- | --- |
+| `service deployment list` | List deployments for the service |
+| `service deployment show` | Show a deployment in detail |
+| `service deployment promote` | Promote a deployment to production by rebuilding with production env vars |
+| `service deployment rollback` | Roll back production to a previous deployment |
+| `service deployment start` | Start a stopped deployment |
+| `service deployment stop` | Stop a running deployment |
+| `service deployment delete` | Delete a deployment and the artifact it holds |
+
+### `service domain` — Manage custom domains for a service
+
+| Command | Meaning |
+| --- | --- |
+| `service domain add` | Register a custom domain on the service's production branch |
+| `service domain show` | Show custom domain status and certificate details |
+| `service domain delete` | Delete a custom domain from the service |
+| `service domain retry` | Retry custom domain DNS verification and TLS provisioning |
+| `service domain wait` | Wait until a custom domain is active or failed |
+
+## `contract` — Define and emit your application data contract
+
+| Command | Meaning |
+| --- | --- |
+| `contract emit` | Emit your contract artifacts |
+| `contract infer` | Infer a PSL contract from the live database schema |
+| `contract format` | Format your PSL contract source |
+
+## `db` — Verify, sign and update your database against the contract
+
+| Command | Meaning |
+| --- | --- |
+| `db init` | Bootstrap a database to match the current contract and sign it |
+| `db schema` | Inspect the live database schema |
+| `db sign` | Sign the database with your contract so you can safely run queries |
+| `db update` | Update your database schema to match your contract |
+| `db verify` | Check whether the database marker and live schema match your contract |
+| `db migrate` | Apply planned migrations to advance the database |
+
+## `migration` — Plan, inspect and scaffold on-disk migrations
+
+| Command | Meaning |
+| --- | --- |
+| `migration plan` | Plan a migration from contract changes |
+| `migration new` | Scaffold a new migration for manual authoring |
+| `migration list` | List on-disk migrations per contract space |
+| `migration show` | Display migration package contents |
+| `migration status` | Show migration path and pending status |
+| `migration log` | Show executed migration history |
+| `migration graph` | Show the migration graph topology |
+| `migration check` | Verify artifact and graph integrity |
+
+Applying migrations is `db migrate`.
+
+### `migration ref` — Manage named refs that point at contracts
+
+| Command | Meaning |
+| --- | --- |
+| `migration ref list` | List every named ref |
+| `migration ref set` | Point a ref at a contract |
+| `migration ref delete` | Delete a ref |
+
+## `orm` — Initialize a Prisma ORM project
+
+| Command | Meaning |
+| --- | --- |
+| `orm init` | Initialize a new Prisma Next project |
+
+## `agent` — Manage Prisma skills for AI coding agents
+
+| Command | Meaning |
+| --- | --- |
+| `agent install` | Install Prisma skills for AI coding agents |
+| `agent update` | Refresh Prisma skills for AI coding agents |
+| `agent status` | Show installed Prisma skills |
+
+## `telemetry` — Inspect and change anonymous CLI telemetry
+
+| Command | Meaning |
+| --- | --- |
+| `telemetry status` | Show whether anonymous CLI telemetry is enabled and why |
+| `telemetry enable` | Enable anonymous CLI telemetry |
+| `telemetry disable` | Disable anonymous CLI telemetry |

.drive/projects/prisma-cli-v8/assets/s2/command-inventory.md

@@ -699,3 +699,7 @@ Fixture-mode counts are references to `fixturePath` per file (see command sectio
   - `auth logout --workspace X` duplicating `auth workspace logout X` is a compat shim worth collapsing.
   - `project env` is the env surface (moved off `app`); the S2 brief's "app (incl. env…)" reflects the old layout — env controllers still live in files named `app-env*.ts` and types in `types/app-env.ts` even though the commands are `project env *`.
   - Group descriptor `branch` says "View your Platform branches" — read-only group with one verb; fine, but the deploy path creates branches implicitly (POST branches), which the grammar should own explicitly.
+
+---
+
+**2026-08-21 note (PM review, command grammar cleanup):** this inventory is a historical grounding document for the S2 ports. The mounted tree has since changed: top-level `init` is removed, the six destroying `remove` commands are `delete`, `postgres restore` is `postgres backup restore`, `migrate`/`format`/`ref *` are `db migrate`/`contract format`/`migration ref *`, and composer's `deploy` and `dev` are root commands. The regenerated tree lives in [`../command-review.md`](../command-review.md).

.drive/projects/prisma-cli-v8/assets/s2/parity-divergences-s3.md

@@ -272,3 +272,7 @@ added; the guard remains the required explicit `--stage` /
 `--production` target, exactly as legacy. If destroy deserves a
 confirmation it is a composer product decision, raised upstream rather
 than built at the mount.
+
+## Command grammar cleanup (2026-08-21 PM review)
+
+The `composer` group is dissolved: `composer deploy` and `composer dev` mount at the root as `deploy` and `dev`, and `composer destroy` and `composer log` are dropped from the mounted tree entirely. The sections above describe the family as S3 mounted it.

.drive/projects/prisma-cli-v8/assets/s2/parity-divergences-s7.md

@@ -42,3 +42,7 @@ imports behind dynamic imports, which is prisma/prisma's change to
 make, not this repo's. Mirrored in
 [`../../deferred.md`](../../deferred.md) under "Upstream, not ours to
 land".
+
+## Command grammar cleanup (2026-08-21 PM review)
+
+The ORM mounts moved: `migrate` → `db migrate`, `format` → `contract format`, `ref list|set|delete` → `migration ref list|set|delete`. The shipped `migration ref` redirect is dropped at the mount (the spelling is live again) and `migration apply`'s replacement is respelled to `{bin} db migrate --to <contract>`. Command behaviour is unchanged.

.drive/projects/prisma-cli-v8/assets/s2/parity-divergences-s8.md

@@ -213,3 +213,7 @@ of a check here is the requirement being met, not a gap in it.
 
 The same holds for `delete` against a running deployment: the API states
 the stop precondition, the CLI does not pre-empt it.
+
+## Command grammar cleanup (2026-08-21 PM review)
+
+`service remove` is renamed `service delete` (result field `removed` becomes `deleted`; `SERVICE.REMOVE_FAILED` becomes `SERVICE.DELETE_FAILED`), and every service command that targets an existing service now requires `--service` or `PRISMA_SERVICE_ID` — the interactive picker and the remembered selection are gone, and `--branch` no longer falls back to the local git branch.

.drive/projects/prisma-cli-v8/assets/s2/parity-divergences-service-logs.md

@@ -107,3 +107,7 @@ signalled run at 128 + the signal "whatever the handler concluded"
 [`parity-divergences-s3.md`](parity-divergences-s3.md)). S2c would have
 settled 130 too. The exit code comes from the engine rule, not from
 anything this slice changed.
+
+## Command grammar cleanup (2026-08-21 PM review)
+
+`service logs` now requires a service target (`--service` or `PRISMA_SERVICE_ID`) unless `--deployment` names a deployment id with no service target, which resolves globally within the project. The picker and remembered selection are gone.

.drive/projects/prisma-cli-v8/assets/s2/parity-divergences.md

@@ -1606,3 +1606,7 @@ Three ported commands reached directly into `process` for host facts, because no
 ## Ruled during the S7 merge (operator, 2026-08-12)
 
 **Top-level `init` is the platform's compute-config wizard; the ORM's project initializer mounts at `orm init`.** The unified grammar had both families claiming `init` — the S2d contract for the platform wizard, the ORM family's own command key for the initializer — and the collision only became mountable when S7 landed the ORM family. Users of the old ORM CLI who type `prisma init` expecting a schema scaffold now get the compute wizard and must type `orm init`. The `orm` group exists solely for this command until the ORM family grows more residents or the ruling is revisited (TML-3189 holds the final grammar).
+
+## Command grammar cleanup (2026-08-21 PM review)
+
+The grammar cleanup slice supersedes several spellings this record documents. Top-level `init` and the compute config (`prisma.compute.ts`/`.json`) are removed; service commands take parameters only (`--service`/`PRISMA_SERVICE_ID`, `--branch`; the picker, remembered selection, and git-branch inference are gone); `project remove`, `project env remove`, `postgres remove`, `postgres connection remove`, `service remove`, and `service domain remove` are renamed to `delete`; `postgres restore` moves to `postgres backup restore`. No aliases or redirects for the old spellings. This entry records the change; the sections above stay as written for history.