@prisma/cli 8.0.0-rc.13-dev.92 → 8.0.0-rc.13-dev.93

package/dist/cli.js

@@ -2522,6 +2522,7 @@ const authLoginCommand = defineCommand({
 	managesCredentials: true,
 	help: {
 		summary: "Log in to your Prisma platform account",
+		description: "Opens a browser sign-in and stores a session for one workspace, the account-level container that holds your Projects. Run it again to add a session for another workspace; 'auth workspace use' switches between stored sessions. In CI or other non-interactive environments, skip login and set PRISMA_SERVICE_TOKEN instead.",
 		examples: ["auth login"]
 	},
 	handler: async (_args, ctx) => {
@@ -2612,6 +2613,7 @@ const authLogoutCommand = defineCommand({
 	managesCredentials: true,
 	help: {
 		summary: "Clear stored authentication credentials",
+		description: "Ends every workspace session stored on this machine. To end just one and keep the others, use 'auth workspace logout' instead. A credential supplied via PRISMA_SERVICE_TOKEN is not stored here and stays in force.",
 		examples: ["auth logout"]
 	},
 	handler: async (_args, ctx) => {
@@ -2701,7 +2703,8 @@ function presentationsFor(spec, result) {
 }
 const authWhoamiCommand = defineCommand({
 	help: {
-		summary: "Show the authenticated user and accessible workspace",
+		summary: "Show who is signed in and which workspace commands target",
+		description: "Shows which identity the CLI is acting as and which workspace its commands will target. Run it to check you are in the right workspace before creating or deleting resources, or to see whether a PRISMA_SERVICE_TOKEN credential is overriding your stored sessions.",
 		examples: ["auth whoami", "auth whoami --json"]
 	},
 	handler: async (_args, ctx) => {
@@ -2792,6 +2795,7 @@ const authWorkspaceListCommand = defineCommand({
 	managesCredentials: true,
 	help: {
 		summary: "List your workspace sessions",
+		description: "Each 'auth login' stores one session per workspace. This lists the sessions on this machine and marks the current one, which every workspace-scoped command targets unless a PRISMA_SERVICE_TOKEN credential is set; that credential overrides stored sessions.",
 		examples: ["auth workspace list", "auth workspace list --json"]
 	},
 	handler: async (_args, ctx) => {
@@ -2855,6 +2859,7 @@ const authWorkspaceLogoutCommand = defineCommand({
 	}) } },
 	help: {
 		summary: "End one workspace session",
+		description: "Removes the stored session for one workspace and leaves the others in place. To clear every session on this machine, use 'auth logout'.",
 		examples: ["auth workspace logout my-workspace"]
 	},
 	handler: async (args, ctx) => {
@@ -2937,7 +2942,8 @@ const authWorkspaceUseCommand = defineCommand({
 		placeholder: "id-or-name"
 	}) } },
 	help: {
-		summary: "Make one of your workspace sessions current",
+		summary: "Make a workspace session current: commands target that workspace",
+		description: "Switches which workspace subsequent commands target. This changes local CLI state only; nothing is created or modified on the platform. Run without an argument to pick from your stored sessions. A PRISMA_SERVICE_TOKEN credential, when set, overrides stored sessions: commands keep targeting its workspace regardless of the selection here.",
 		examples: ["auth workspace use", "auth workspace use my-workspace"]
 	},
 	handler: async (args, ctx) => {
@@ -4289,11 +4295,12 @@ function listPresentations$8(result) {
 }
 const branchListCommand = defineCommand({
 	help: {
-		summary: "List Platform branches for the resolved project",
+		summary: "List a project's Platform branches",
+		description: "A Branch maps to a Git branch of the connected repository. Each one is an isolated environment with its own services, databases, buckets, and environment variables: the production branch serves live traffic, every other branch is a preview.",
 		examples: ["branch list", "branch list --project my-app"]
 	},
 	args: { flags: { project: flag.string({
-		brief: "Project id or name",
+		brief: "Project id or name (default: the project this directory is linked to)",
 		placeholder: "id-or-name"
 	}) } },
 	needs: { credentials: true },
@@ -4486,11 +4493,11 @@ function bucketApiError(summary, response, error) {
 /** Where a caller who is missing a bucket id finds one. */
 const LIST_BUCKETS_COMMAND = `${CLI_NAME} bucket list`;
 const projectFlag$3 = flag.string({
-	brief: "Project id or name",
+	brief: "Project id or name (default: the project this directory is linked to)",
 	placeholder: "id-or-name"
 });
 const branchFlag$2 = flag.string({
-	brief: "Branch git name",
+	brief: "Branch git name; use to target one branch's environment",
 	placeholder: "git-name"
 });
 const bucketPositional = positional.string({
@@ -4563,6 +4570,7 @@ const bucketCreateCommand = defineCommand({
 	} },
 	help: {
 		summary: "Create an object-store bucket",
+		description: "Creates blob storage in a Branch of the project. A bucket holds no credentials of its own: mint them with 'bucket key create', which prints them once.",
 		examples: [
 			"bucket create",
 			"bucket create --name my-store",
@@ -4628,6 +4636,7 @@ const bucketDeleteCommand = defineCommand({
 	args: { positionals: { bucketId: bucketPositional } },
 	help: {
 		summary: "Delete a bucket and all its access keys",
+		description: "Deletion is permanent: the stored objects are destroyed and every access key stops working. The exact bucket id is the consent token; pass it with --confirm to run non-interactively.",
 		examples: ["bucket delete bkt_123 --confirm bkt_123"]
 	},
 	needs: { credentials: true },
@@ -4707,17 +4716,18 @@ const bucketKeyCreateCommand = defineCommand({
 		positionals: { bucketId: bucketPositional },
 		flags: {
 			role: flag.enum({
-				brief: "Access role (default: read_write)",
+				brief: "Access role; read_write unless set, use read for consumers that only download",
 				values: ["read", "read_write"]
 			}),
 			name: flag.string({
-				brief: "Key display name (auto-generated if omitted)",
+				brief: "Key display name; use it to record which consumer holds the key (auto-generated if omitted)",
 				placeholder: "name"
 			})
 		}
 	},
 	help: {
 		summary: "Create a bucket access key and print its one-time credentials",
+		description: "Mints S3-compatible credentials for one bucket, shown exactly once; store them now, nothing prints them again. Give each consumer its own key so one can be revoked without breaking the others, and grant read-only consumers --role read.",
 		examples: [
 			"bucket key create bkt_123",
 			"bucket key create bkt_123 --role read",
@@ -4788,6 +4798,7 @@ const bucketKeyDeleteCommand = defineCommand({
 	} },
 	help: {
 		summary: "Revoke and delete a bucket access key",
+		description: "The key's credentials stop working immediately; anything still using them loses access to the bucket. The bucket and its other keys are untouched.",
 		examples: ["bucket key delete bkt_123 bkey_456"]
 	},
 	needs: { credentials: true },
@@ -4905,6 +4916,7 @@ const bucketKeyListCommand = defineCommand({
 	args: { positionals: { bucketId: bucketPositional } },
 	help: {
 		summary: "List access keys for a bucket",
+		description: "Shows each key's id, name, and role. Key secrets print once, at 'bucket key create'; listing never reveals them.",
 		examples: ["bucket key list bkt_123", "bucket key list bkt_123 --json"]
 	},
 	needs: { credentials: true },
@@ -4979,7 +4991,8 @@ const bucketListCommand = defineCommand({
 		branch: branchFlag$2
 	} },
 	help: {
-		summary: "List object-store buckets for the resolved project",
+		summary: "List a project's object-store buckets",
+		description: "A bucket is blob storage for files and uploads. Buckets are branch-bound: each belongs to one Branch, the isolated environment for one Git branch.",
 		examples: [
 			"bucket list",
 			"bucket list --branch preview",
@@ -5162,7 +5175,7 @@ async function postFeedback(endpoint, body, signal) {
 const feedbackCommand = defineCommand({
 	help: {
 		summary: "Send feedback to the Prisma CLI team",
-		description: "Anonymous unless --email is passed. Every submission includes the CLI\nversion, node version, and OS platform/arch, and nothing else.",
+		description: "Anonymous unless --email is passed. Every submission includes the CLI version, node version, and OS platform/arch, and nothing else.",
 		examples: ["feedback \"the deploy flow is great\"", "feedback \"please add X\" --email you@example.com"]
 	},
 	args: {
@@ -5282,7 +5295,7 @@ function formatGitConnectionDetail(status) {
 /** Workspace, project and the source-repository client for the
 *  `git *` commands. */
 const projectFlag$2 = flag.string({
-	brief: "Project id or name",
+	brief: "Project id or name (default: the project this directory is linked to)",
 	placeholder: "id-or-name"
 });
 async function resolveGitContext(ctx, explicitProject, commandName) {
@@ -5384,13 +5397,14 @@ function connectPresentations(result) {
 const gitConnectCommand = defineCommand({
 	args: {
 		positionals: { gitUrl: positional.optionalString({
-			brief: "GitHub repository URL",
+			brief: "GitHub repository URL (default: this repository's origin)",
 			placeholder: "git-url"
 		}) },
 		flags: { project: projectFlag$2 }
 	},
 	help: {
-		summary: "Connect the resolved project to a GitHub repository",
+		summary: "Connect a project to a GitHub repository so every push deploys",
+		description: "Turns on deploy-on-push: once connected, pushing a Git branch builds and deploys it to a matching Platform Branch, an isolated environment with its own services, databases, and buckets. If the Prisma GitHub App does not cover the repository yet, the command opens the install page and waits. Run without a URL to use this repository's origin remote.",
 		examples: [
 			"git connect",
 			"git connect git@github.com:prisma/prisma-cli.git",
@@ -5486,7 +5500,8 @@ function disconnectPresentations(result) {
 const gitDisconnectCommand = defineCommand({
 	args: { flags: { project: projectFlag$2 } },
 	help: {
-		summary: "Disconnect the GitHub repository from the resolved project",
+		summary: "Disconnect the GitHub repository: pushes stop deploying",
+		description: "Stops deploy-on-push by removing the repository connection. Nothing already deployed changes: existing branches, services, and databases stay as they are.",
 		examples: ["git disconnect", "git disconnect --project proj_123"]
 	},
 	needs: { credentials: true },
@@ -5760,8 +5775,8 @@ function bothSwitchesError() {
 }
 const skillsSyncCommand = defineCommand({
 	help: {
-		summary: "Copy the agent skills from installed Prisma packages into this project",
-		description: "Skills come from the Prisma packages the project installs, so they always describe the version in use. Sync copies them into the skill directories the agent harnesses read, and removes copies whose package is gone. It does nothing, and exits 0, when everything is already current.",
+		summary: "Copy the AI-agent instruction files (skills) from installed Prisma packages into this project",
+		description: "Agent skills are instruction files that teach AI coding agents (Claude Code, Cursor, and others) how to use the installed Prisma packages. They ship inside the packages themselves, so they always describe the version in use. Sync copies them into the skill directories the agent harnesses read, and removes copies whose package is gone. It does nothing, and exits 0, when everything is already current.",
 		examples: ["skills sync", "skills sync --disable"]
 	},
 	needs: { config: skillsConfigSection },
@@ -6268,7 +6283,7 @@ function initPresentations(result, postinstall, config, skills) {
 }
 const initCommand = defineCommand({
 	help: {
-		summary: "Prepare this repository for Prisma development",
+		summary: "Prepare this repository for Prisma: config file, dev dependency, AI-agent skills",
 		description: "Runs locally and calls no platform API. Adds a postinstall script to package.json that keeps the Prisma agent skills in sync on every install, adds prisma to devDependencies at this CLI's exact version when no dependency field declares it, scaffolds a prisma.config.ts recording which agents to install skills for, then syncs the skills once now. Everything lands in the current directory; a prisma.config.ts or postinstall script that already exists is never edited. Rerunning is safe: each step reports what is already done.",
 		examples: [
 			"init",
@@ -6840,11 +6855,11 @@ async function readWorkspaceSubscription(client, workspaceId, signal) {
 //#region src/commands/postgres/context.ts
 /** Workspace, project and provider for the `postgres *` commands. */
 const projectFlag$1 = flag.string({
-	brief: "Project id or name",
+	brief: "Project id or name (default: the project this directory is linked to)",
 	placeholder: "id-or-name"
 });
 const branchFlag$1 = flag.string({
-	brief: "Branch git name",
+	brief: "Branch git name; use to target one branch's environment",
 	placeholder: "git-name"
 });
 const databasePositional = positional.string({
@@ -7022,6 +7037,7 @@ const postgresBackupListCommand = defineCommand({
 	},
 	help: {
 		summary: "List backups for a database",
+		description: "Backups are created automatically by the platform. Use the listed backup ids with 'postgres backup restore'.",
 		examples: ["postgres backup list db_123", "postgres backup list acme-production --limit 50"]
 	},
 	needs: { credentials: true },
@@ -7104,11 +7120,11 @@ const postgresBackupRestoreCommand = defineCommand({
 		}) },
 		flags: {
 			backup: flag.string({
-				brief: "Backup to restore from",
+				brief: "Backup to restore from, listed by 'postgres backup list'",
 				placeholder: "backup-id"
 			}),
 			sourceDatabase: flag.string({
-				brief: "Database the backup belongs to (defaults to the target)",
+				brief: "Database the backup belongs to; use when restoring another database's backup into the target",
 				placeholder: "database"
 			}),
 			project: projectFlag$1,
@@ -7117,6 +7133,7 @@ const postgresBackupRestoreCommand = defineCommand({
 	},
 	help: {
 		summary: "Restore a database from a backup after exact id confirmation",
+		description: "Replaces the target database's current state with the backup's contents; anything written since that backup is lost, so the exact target database id is the consent token. To restore another database's backup into this one, name where the backup came from with --source-database.",
 		examples: ["postgres backup restore db_123 --backup bkp_456 --confirm db_123"]
 	},
 	needs: { credentials: true },
@@ -7166,7 +7183,7 @@ const postgresConnectionCreateCommand = defineCommand({
 		positionals: { database: databasePositional },
 		flags: {
 			name: flag.string({
-				brief: "Connection name",
+				brief: "Connection name; use it to record which consumer holds the credential",
 				placeholder: "name"
 			}),
 			project: projectFlag$1,
@@ -7174,7 +7191,8 @@ const postgresConnectionCreateCommand = defineCommand({
 		}
 	},
 	help: {
-		summary: "Create a database connection and print its one-time connection URL",
+		summary: "Create an additional connection URL for a database; printed exactly once",
+		description: "Mints an additional credential for an existing database, shown exactly once. Give each consumer (an app, CI, a teammate) its own named connection, so its access can later be rotated or revoked without touching the others.",
 		examples: ["postgres connection create db_123", "postgres connection create db_123 --name readonly"]
 	},
 	needs: { credentials: true },
@@ -7212,6 +7230,7 @@ const postgresConnectionDeleteCommand = defineCommand({
 	}) } },
 	help: {
 		summary: "Delete a database connection after exact id confirmation",
+		description: "Revokes the credential: anything still using its URL loses access to the database. The database itself and its other connections are untouched. The exact connection id is the consent token.",
 		examples: ["postgres connection delete conn_123 --confirm conn_123"]
 	},
 	needs: { credentials: true },
@@ -7324,6 +7343,7 @@ const postgresConnectionListCommand = defineCommand({
 	},
 	help: {
 		summary: "List database connection metadata without secret values",
+		description: "Each connection is an independent credential for the same database, so one consumer's access can be rotated or revoked without breaking the others. Listing shows metadata only; connection URLs print once, at create or rotate, and never again.",
 		examples: ["postgres connection list db_123", "postgres connection list acme-preview --branch preview --json"]
 	},
 	needs: { credentials: true },
@@ -7350,6 +7370,7 @@ const postgresConnectionRotateCommand = defineCommand({
 	}) } },
 	help: {
 		summary: "Rotate connection credentials and print the new one-time connection URL",
+		description: "Replaces the connection's credentials: the old URL stops working and the new one prints exactly once. Use it after a suspected leak or on a rotation schedule. The exact connection id is the consent token.",
 		examples: ["postgres connection rotate conn_123 --confirm conn_123"]
 	},
 	needs: { credentials: true },
@@ -7396,7 +7417,7 @@ const postgresCreateCommand = defineCommand({
 		}) },
 		flags: {
 			region: flag.string({
-				brief: "Prisma Postgres region id",
+				brief: "Prisma Postgres region id; set it when the data must live near a location",
 				placeholder: "region"
 			}),
 			project: projectFlag$1,
@@ -7405,6 +7426,7 @@ const postgresCreateCommand = defineCommand({
 	},
 	help: {
 		summary: "Create a Prisma Postgres database and print its one-time connection URL",
+		description: "Creates a database in a Branch of the project and prints its connection URL exactly once; store it now, nothing prints it again. Mint further URLs for other consumers with 'postgres connection create'.",
 		examples: ["postgres create my-db", "postgres create my-db --branch feature/foo --region eu-central-1"]
 	},
 	needs: { credentials: true },
@@ -7496,6 +7518,7 @@ const postgresDeleteCommand = defineCommand({
 	},
 	help: {
 		summary: "Delete a database after exact id confirmation",
+		description: "Deletion is permanent and destroys the data. The exact database id is the consent token; pass it with --confirm to run non-interactively.",
 		examples: ["postgres delete db_123 --confirm db_123"]
 	},
 	needs: { credentials: true },
@@ -7583,7 +7606,8 @@ const postgresListCommand = defineCommand({
 		branch: branchFlag$1
 	} },
 	help: {
-		summary: "List Prisma Postgres databases for the resolved project",
+		summary: "List a project's Prisma Postgres databases",
+		description: "Databases are branch-bound: each belongs to one Branch, the isolated environment for one Git branch. Without --branch, this lists databases across every branch of the project.",
 		examples: [
 			"postgres list",
 			"postgres list --branch feature/foo",
@@ -7704,6 +7728,7 @@ const postgresShowCommand = defineCommand({
 	},
 	help: {
 		summary: "Show database metadata without secret values",
+		description: "Shows a database's name, branch, region, and status. Connection URLs are secrets printed once, by 'postgres create' or 'postgres connection rotate'; this command never reveals them.",
 		examples: ["postgres show db_123", "postgres show acme-preview --branch preview --json"]
 	},
 	needs: { credentials: true },
@@ -8546,12 +8571,13 @@ const projectCreateCommand = defineCommand({
 			placeholder: "name"
 		}) },
 		flags: { region: flag.string({
-			brief: "Prisma Compute region id",
+			brief: "Prisma Compute region for the project's infrastructure; set it when data or users must stay near a location",
 			placeholder: "region"
 		}) }
 	},
 	help: {
-		summary: "Create a Project and link this directory",
+		summary: "Create a Project and link this directory: commands run here target it",
+		description: "Creates a Project in your workspace and links the current directory to it, so later commands resolve it without --project. A Project groups one product or codebase; its Branches are isolated environments, each with its own services, databases, and buckets. This is usually the first command after 'auth login' in a new repository.",
 		examples: ["project create my-app", "project create my-app --json"]
 	},
 	needs: { credentials: true },
@@ -8630,6 +8656,7 @@ const projectDeleteCommand = defineCommand({
 	}) } },
 	help: {
 		summary: "Delete a Project permanently after exact id confirmation",
+		description: "Deletion is permanent: it destroys the project's databases and stops its deployed services. Because of that, the command asks for the exact project id as a consent token; pass it with --confirm to run non-interactively.",
 		examples: ["project delete proj_123 --confirm proj_123"]
 	},
 	needs: { credentials: true },
@@ -9297,19 +9324,19 @@ function serializeEnvList(result) {
 /** Flags, scope resolution and presentation shared by the
 *  `project env *` commands. */
 const roleFlag = flag.enum({
-	brief: "Project template scope (production or preview)",
+	brief: "Project-wide scope: production, or preview (shared by every preview branch)",
 	values: ["production", "preview"]
 });
 const projectFlag = flag.string({
-	brief: "Project id or name",
+	brief: "Project id or name (default: the project this directory is linked to)",
 	placeholder: "id-or-name"
 });
 const branchFlag = flag.string({
-	brief: "Preview branch override scope",
+	brief: "Scope to one preview branch's override; use for values only that branch needs",
 	placeholder: "git-name"
 });
 const fileFlag = flag.string({
-	brief: "Read KEY=VALUE assignments from a dotenv file",
+	brief: "Read KEY=VALUE assignments from a dotenv file; use to import many variables at once",
 	placeholder: "path"
 });
 function requireEnvScope(flags, command) {
@@ -9462,7 +9489,8 @@ const projectEnvAddCommand = defineCommand({
 		}
 	},
 	help: {
-		summary: "Create a new environment variable.",
+		summary: "Create an environment variable in one scope: production, preview, or one branch",
+		description: "Variables reach a service's environment when it deploys. Writes always name their scope so production is never targeted by accident: --role production, --role preview (shared by every preview branch), or --branch for one branch's override. The value comes from KEY=VALUE, from the current shell environment when only KEY is given, or from a dotenv file with --file.",
 		examples: [
 			"project env add STRIPE_KEY=sk_test_xxx --role production",
 			"project env add STRIPE_KEY=sk_test_xxx --role preview",
@@ -9578,7 +9606,8 @@ const projectEnvDeleteCommand = defineCommand({
 		}
 	},
 	help: {
-		summary: "Delete an environment variable from a scope.",
+		summary: "Delete an environment variable from one scope: production, preview, or one branch",
+		description: "Removes the variable from the named scope only; the same key in other scopes is untouched. Services lose the value on their next deploy.",
 		examples: [
 			"project env delete STRIPE_KEY --role production",
 			"project env delete STRIPE_KEY --role preview",
@@ -9656,13 +9685,14 @@ const projectEnvListCommand = defineCommand({
 	args: { flags: {
 		role: roleFlag,
 		branch: flag.string({
-			brief: "Preview branch resolved scope",
+			brief: "Show what one preview branch resolves: the preview scope plus its overrides",
 			placeholder: "git-name"
 		}),
 		project: projectFlag
 	} },
 	help: {
-		summary: "List environment variable metadata for a scope (no values).",
+		summary: "List environment variables in a scope: names and ids, never values",
+		description: "Values are write-only through the CLI: listing shows names, ids, and status, never values. Without a scope flag it shows an overview of every scope; --role narrows to the production or preview scope, and --branch shows what one preview branch resolves.",
 		examples: [
 			"project env list",
 			"project env list --role production",
@@ -9728,7 +9758,8 @@ const projectEnvUpdateCommand = defineCommand({
 		}
 	},
 	help: {
-		summary: "Replace an existing environment variable's value.",
+		summary: "Replace an existing environment variable's value",
+		description: "Overwrites one variable's value in one scope; the variable must already exist there (use 'project env add' to create it). With --file, overwrites every variable the dotenv file lists. New values reach services on their next deploy.",
 		examples: [
 			"project env update STRIPE_KEY=sk_new_xxx --role production",
 			"project env update STRIPE_KEY=sk_new_xxx --role preview",
@@ -9877,7 +9908,8 @@ const projectLinkCommand = defineCommand({
 		placeholder: "id-or-name"
 	}) } },
 	help: {
-		summary: "Link this directory to a Project",
+		summary: "Link this directory to a Project: commands run here target it by default",
+		description: "Records locally that this directory belongs to an existing Project, so later commands resolve it without --project. Linking itself changes local state only. Run without an argument to pick from your workspace's projects; that picker also offers creating a new Project, which does create one on the platform.",
 		examples: [
 			"project link",
 			"project link proj_123",
@@ -9958,6 +9990,7 @@ function listPresentations$1(result) {
 const projectListCommand = defineCommand({
 	help: {
 		summary: "List all projects in your workspace",
+		description: "A Project groups one product or codebase. It is the child of a workspace and the parent of Branches: isolated environments that hold your services, databases, and buckets.",
 		examples: ["project list", "project list --json"]
 	},
 	needs: { credentials: true },
@@ -10018,12 +10051,13 @@ const projectRenameCommand = defineCommand({
 			placeholder: "name"
 		}) },
 		flags: { project: flag.string({
-			brief: "Project id or name",
+			brief: "Project id or name (default: the project this directory is linked to)",
 			placeholder: "id-or-name"
 		}) }
 	},
 	help: {
-		summary: "Rename the resolved Project",
+		summary: "Rename a Project",
+		description: "Changes the display name of the linked project, or of the one named by --project. The project id stays the same, so existing links and automation keep working.",
 		examples: ["project rename \"Acme Dashboard v2\"", "project rename billing-api --project proj_123"]
 	},
 	needs: { credentials: true },
@@ -10153,11 +10187,12 @@ function showPresentations$1(result, cwd, env) {
 }
 const projectShowCommand = defineCommand({
 	args: { positionals: { project: positional.optionalString({
-		brief: "Project id or name (default: the linked project)",
+		brief: "Project id or name (default: the project this directory is linked to)",
 		placeholder: "id-or-name"
 	}) } },
 	help: {
-		summary: "Show this directory's Project binding",
+		summary: "Show which Project this directory is linked to",
+		description: "Reports which Project this directory is linked to, or that it is not linked, with next steps. Pass an id or name to inspect any project without changing the local link.",
 		examples: ["project show", "project show proj_123 --json"]
 	},
 	needs: { credentials: true },
@@ -10341,17 +10376,18 @@ const projectTransferCommand = defineCommand({
 		}) },
 		flags: {
 			toWorkspace: flag.string({
-				brief: "Locally authenticated workspace to receive the project",
+				brief: "Receiving workspace, when it is one of your own stored sessions",
 				placeholder: "id-or-name"
 			}),
 			recipientToken: flag.string({
-				brief: "Access token for the receiving workspace",
+				brief: "Access token for the receiving workspace, when you are not a member of it",
 				placeholder: "token"
 			})
 		}
 	},
 	help: {
 		summary: "Transfer a Project to another workspace after exact id confirmation",
+		description: "Moves a project, with everything in it, out of the current workspace. Name the receiving workspace with --to-workspace when you are logged in to it too, or pass --recipient-token when someone else owns it. The exact project id is the consent token.",
 		examples: ["project transfer proj_123 --to-workspace \"Prisma Labs\" --confirm proj_123", "project transfer proj_123 --recipient-token <token> --confirm proj_123"]
 	},
 	needs: { credentials: true },
@@ -11549,6 +11585,7 @@ async function resolveServiceDomainTarget(ctx, options) {
 const serviceCreateCommand = defineCommand({
 	help: {
 		summary: "Create a service in a project",
+		description: "Registers a service on a Branch ahead of its first deploy. Deploying through a connected repository or 'deploy' creates services automatically, so reach for this only when a service must exist before anything has been deployed to it.",
 		examples: ["service create my-service", "service create my-service --region us-east-1 --branch main"]
 	},
 	args: {
@@ -11558,15 +11595,15 @@ const serviceCreateCommand = defineCommand({
 		}) },
 		flags: {
 			project: flag.string({
-				brief: "Project id or name",
+				brief: "Project id or name (default: the project this directory is linked to)",
 				placeholder: "id-or-name"
 			}),
 			region: flag.string({
-				brief: "Prisma Compute region id",
+				brief: "Prisma Compute region id; set it when the service must run near a location",
 				placeholder: "region"
 			}),
 			branch: flag.string({
-				brief: "Branch name",
+				brief: "Branch to create the service on (default: the default branch)",
 				placeholder: "branch"
 			})
 		}
@@ -11718,7 +11755,8 @@ function destroyProgressReporter(ctx, serviceName) {
 //#region src/commands/service/delete.ts
 const serviceDeleteCommand = defineCommand({
 	help: {
-		summary: "Delete the service from the resolved branch",
+		summary: "Delete a service from one branch",
+		description: "Removes the service from the targeted Branch only: its versions stop serving and its URL goes away. The same service on other branches is untouched. Pass the confirmation token with --confirm to run non-interactively.",
 		examples: ["service delete my-service", "service delete my-service --confirm my-service"]
 	},
 	args: {
@@ -11789,11 +11827,11 @@ function domainTargetArgs() {
 	return {
 		flags: {
 			service: flag.string({
-				brief: "Service id or name",
+				brief: "Service id or name the domain belongs to",
 				placeholder: "name"
 			}),
 			project: flag.string({
-				brief: "Project id or name",
+				brief: "Project id or name (default: the project this directory is linked to)",
 				placeholder: "id-or-name"
 			}),
 			branch: flag.string({
@@ -11812,6 +11850,7 @@ function domainTargetArgs() {
 const serviceDomainAddCommand = defineCommand({
 	help: {
 		summary: "Register a custom domain on the service's production branch",
+		description: "Points a hostname you own at the service instead of its generated URL. After registering, create the DNS record the platform asks for, then 'service domain wait' blocks until verification and TLS provisioning finish.",
 		examples: ["service domain add shop.acme.com --service my-service"]
 	},
 	args: domainTargetArgs(),
@@ -11844,6 +11883,7 @@ const serviceDomainAddCommand = defineCommand({
 const serviceDomainDeleteCommand = defineCommand({
 	help: {
 		summary: "Delete a custom domain from the service",
+		description: "The hostname stops routing to the service immediately; the service itself and its generated URL keep working. Pass the hostname with --confirm to run non-interactively.",
 		examples: ["service domain delete shop.acme.com --service my-service", "service domain delete shop.acme.com --service my-service --confirm shop.acme.com"]
 	},
 	args: domainTargetArgs(),
@@ -11874,6 +11914,7 @@ const serviceDomainDeleteCommand = defineCommand({
 const serviceDomainRetryCommand = defineCommand({
 	help: {
 		summary: "Retry custom domain DNS verification and TLS provisioning",
+		description: "Run it after fixing what made the domain fail, typically a missing or wrong DNS record reported by 'service domain show'.",
 		examples: ["service domain retry shop.acme.com --service my-service"]
 	},
 	args: domainTargetArgs(),
@@ -11902,6 +11943,7 @@ const serviceDomainRetryCommand = defineCommand({
 const serviceDomainShowCommand = defineCommand({
 	help: {
 		summary: "Show custom domain status and certificate details",
+		description: "Reports where the domain is in its lifecycle: DNS verification, TLS certificate issuance, active, or failed with the fix to apply. Check here first when a domain is not serving.",
 		examples: ["service domain show shop.acme.com --service my-service"]
 	},
 	args: domainTargetArgs(),
@@ -11968,6 +12010,7 @@ const DURATION = /^(\d+)(ms|s|m|h)$/;
 const serviceDomainWaitCommand = defineCommand({
 	help: {
 		summary: "Wait until a custom domain is active or failed",
+		description: "Blocks while DNS verification and TLS provisioning run, then exits with the outcome; useful in scripts and CI after 'service domain add'.",
 		examples: ["service domain wait shop.acme.com --service my-service", "service domain wait shop.acme.com --service my-service --timeout 30m"]
 	},
 	args: {
@@ -12032,15 +12075,16 @@ const serviceDomainWaitCommand = defineCommand({
 const serviceListCommand = defineCommand({
 	help: {
 		summary: "List the services in a project",
+		description: "A service is one HTTP application (a frontend or a backend) deployed on a Branch of the project. Each deploy produces a service version; at most one version serves traffic at a time.",
 		examples: ["service list", "service list --project my-app --json"]
 	},
 	args: { flags: {
 		project: flag.string({
-			brief: "Project id or name",
+			brief: "Project id or name (default: the project this directory is linked to)",
 			placeholder: "id-or-name"
 		}),
 		branch: flag.string({
-			brief: "Branch name",
+			brief: "Branch the services live on (default: the default branch)",
 			placeholder: "branch"
 		})
 	} },
@@ -12303,6 +12347,7 @@ async function resolveLogsTarget(ctx, options) {
 const serviceLogsCommand = defineSessionCommand({
 	help: {
 		summary: "Read logs for a version of the service",
+		description: "Reads the live version's logs by default; point --version-id at any other version, such as a failed build being debugged. --follow keeps streaming new lines, and --tail or --from-start choose where reading starts.",
 		examples: [
 			"service logs my-service",
 			"service logs my-service --tail 500",
@@ -12325,7 +12370,7 @@ const serviceLogsCommand = defineSessionCommand({
 				placeholder: "name"
 			}),
 			versionId: flag.string({
-				brief: "Service version id to read (default: the live version)",
+				brief: "Service version id to read; use for a failed or stopped version (default: the live version)",
 				placeholder: "id"
 			}),
 			tail: flag.number({
@@ -12417,7 +12462,8 @@ const serviceOpenCommand = defineCommand({
 //#region src/commands/service/show.ts
 const serviceShowCommand = defineCommand({
 	help: {
-		summary: "Show the service and its current version",
+		summary: "Show a service and the version currently serving traffic",
+		description: "Shows the version serving traffic and the service's live URL, when the service has a live version; a service that has never deployed has none yet. Inspect other versions with 'service version list' and 'service version show'.",
 		examples: ["service show my-service", "service show my-service --branch feature-x"]
 	},
 	args: {
@@ -12465,6 +12511,7 @@ const serviceShowCommand = defineCommand({
 const serviceVersionDeleteCommand = defineCommand({
 	help: {
 		summary: "Delete a service version and the artifact it holds",
+		description: "Permanently removes the version and its built artifact, so it can no longer be started or rolled back to. Pass the exact version id with --confirm to run non-interactively.",
 		examples: ["service version delete cpv_123", "service version delete cpv_123 --confirm cpv_123"]
 	},
 	args: { positionals: { version: positional.string({
@@ -12510,6 +12557,7 @@ const serviceVersionDeleteCommand = defineCommand({
 const serviceVersionListCommand = defineCommand({
 	help: {
 		summary: "List versions of the service",
+		description: "Every deploy produces an immutable service version; at most one serves traffic at a time. Use the listed ids with 'service version' promote, rollback, start, stop, and delete.",
 		examples: ["service version list my-service", "service version list my-service --branch feature-x"]
 	},
 	args: {
@@ -12554,6 +12602,7 @@ const serviceVersionListCommand = defineCommand({
 const serviceVersionPromoteCommand = defineCommand({
 	help: {
 		summary: "Promote a service version to production by rebuilding with production env vars",
+		description: "The normal release path: take a version that proved itself on a preview branch, rebuild its source with production environment variables, and switch production traffic to the result. To undo a release, use 'service version rollback', which needs no rebuild.",
 		examples: ["service version promote cpv_123"]
 	},
 	args: { positionals: { version: positional.string({
@@ -12615,6 +12664,7 @@ const serviceVersionPromoteCommand = defineCommand({
 const serviceVersionRollbackCommand = defineCommand({
 	help: {
 		summary: "Roll back production to a previous service version",
+		description: "Returns production traffic to an already-built version without rebuilding, which makes it the fastest way out of a bad release. Defaults to the version before the live one; name an exact target with --to.",
 		examples: [
 			"service version rollback my-service",
 			"service version rollback my-service --to cpv_123",
@@ -12632,7 +12682,7 @@ const serviceVersionRollbackCommand = defineCommand({
 				placeholder: "name"
 			}),
 			to: flag.string({
-				brief: "Version id to roll back to (default: the version before the live one)",
+				brief: "Version id to roll back to; use when the last good version is further back (default: the version before the live one)",
 				placeholder: "version"
 			})
 		},
@@ -12709,6 +12759,7 @@ const serviceVersionRollbackCommand = defineCommand({
 const serviceVersionShowCommand = defineCommand({
 	help: {
 		summary: "Show a service version in detail",
+		description: "Version ids are globally unique, so the id alone is the complete target: no --project or --branch scope is needed.",
 		examples: ["service version show cpv_123"]
 	},
 	args: { positionals: { version: positional.string({
@@ -12862,6 +12913,7 @@ const skillsCommandFamily = defineCommandFamily({
 		list: defineCommand({
 			help: {
 				summary: "Show which Prisma agent skills are installed in this project",
+				description: "Shows each skill, the package and version it came from, and whether the synced copies are current. Run 'skills sync' to bring stale copies up to date.",
 				examples: ["skills list", "skills list --json"]
 			},
 			needs: { config: skillsConfigSection },
@@ -12981,26 +13033,146 @@ const ormCommandFamily$1 = ormCommandFamily;
 *  text that belongs to them; both halves are spread in below. */
 const telemetry = telemetryCommandGroup({ docsUrl: CLI_DOCS_URL });
 const cliGroups = {
-	auth: { brief: "Manage local authentication for the CLI" },
-	project: { brief: "Manage and inspect your Prisma projects" },
-	"project env": { brief: "Manage environment variables for the active project" },
-	postgres: { brief: "Manage Prisma Postgres databases for a project" },
-	"postgres backup": { brief: "Inspect and restore platform-created database backups" },
-	"postgres connection": { brief: "Manage one-time-view database connection strings" },
-	bucket: { brief: "Manage object-store buckets for a project" },
-	"bucket key": { brief: "Manage access keys for an object-store bucket" },
-	branch: { brief: "View your Platform branches" },
-	git: { brief: "Manage Git repository connections for a project" },
-	service: { brief: "Manage services and their versions for a project" },
-	"service domain": { brief: "Manage custom domains for a service" },
-	"service version": { brief: "Manage the versions of a service" },
-	"auth workspace": { brief: "Manage local workspace sessions" },
-	contract: { brief: "Define and emit your application data contract" },
-	db: { brief: "Verify, sign and update your database against the contract" },
-	migration: { brief: "Plan, inspect and scaffold on-disk migrations" },
-	"migration ref": { brief: "Manage named refs that point at contracts" },
+	auth: {
+		brief: "Manage authentication for the Prisma Platform. Sign in and out, inspect identity, switch workspaces",
+		description: "Signing in opens a browser flow and stores a session for one workspace: the account-level container that holds your Projects, members, and billing. Commands act on the current session's workspace; log in once per workspace and switch with the 'workspace' subcommands. A PRISMA_SERVICE_TOKEN environment credential overrides stored sessions, which is the way to authenticate CI."
+	},
+	project: {
+		brief: "Manage Prisma Platform projects. CRUD, link a directory, transfer ownership, manage environment variables",
+		description: "A Project groups one product or codebase. It is the child of a workspace and the parent of Branches: isolated environments, one per Git branch, each holding its own services, databases, and buckets. 'Linking' connects a local directory to a Project: the link is stored locally, and every project-scoped command run in that directory targets the linked project unless --project names another. 'create' links automatically; 'link' points a directory at an existing Project; 'show' reports the link.",
+		workflow: [
+			{
+				run: "project create my-app",
+				brief: "Create a Project, link this directory"
+			},
+			{
+				run: "git connect",
+				brief: "Connect GitHub so every push deploys"
+			},
+			{
+				run: "project env add KEY=value --role preview",
+				brief: "Set env vars services get at deploy"
+			}
+		]
+	},
+	"project env": {
+		brief: "Manage a project's environment variables. Add, update, list, and delete values per scope",
+		description: "Variables live in scopes: production, preview (shared by every preview branch), or a single branch's override. Values reach services when they deploy, and are write-only afterwards: list shows metadata, never values."
+	},
+	postgres: {
+		brief: "Manage Prisma Postgres databases. CRUD, usage metrics, backups, and connection credentials",
+		description: "Databases are branch-bound: each belongs to a Branch, the isolated environment for one Git branch of a project, so commands take --branch to target one. Address a database by its id (db_...) or name. Connection URLs are secrets that print exactly once, at create or rotate; nothing shows them again. 'backup' restores platform-taken backups, and 'connection' manages per-consumer credentials.",
+		workflow: [
+			{
+				run: "postgres create app-db",
+				brief: "Create a database; its URL prints once"
+			},
+			{
+				run: "postgres connection create app-db --name ci",
+				brief: "Mint one credential per consumer"
+			},
+			{
+				run: "postgres connection rotate conn_123",
+				brief: "Replace a leaked credential"
+			}
+		]
+	},
+	"postgres backup": {
+		brief: "Inspect and restore database backups. The platform takes them automatically",
+		description: "The platform takes backups automatically; there is no backup-create command. Restore replaces a database's current state with a backup's contents after exact id confirmation."
+	},
+	"postgres connection": {
+		brief: "Manage database connection credentials. Create, rotate, and revoke per-consumer connection URLs",
+		description: "A connection is one independent credential (a connection URL) for one database. Give each consumer (an app, CI, a teammate) its own, so one can be rotated or revoked without breaking the others. URLs print once, at create or rotate; list shows metadata only."
+	},
+	bucket: {
+		brief: "Manage S3-compatible object-store buckets for a project. CRUD operations and access keys",
+		description: "A bucket is blob storage for files and uploads, bound to one Branch of a project and reachable through the standard S3 API. Access goes through S3-compatible keys minted per consumer with 'bucket key create', which prints credentials (endpoint, key id, secret) exactly once.",
+		workflow: [{
+			run: "bucket create --name uploads",
+			brief: "Create a bucket in the branch"
+		}, {
+			run: "bucket key create bkt_123",
+			brief: "Mint S3 credentials, shown once"
+		}]
+	},
+	"bucket key": {
+		brief: "Manage a bucket's access keys. Create, list, and revoke per-consumer S3 credentials",
+		description: "A key is one consumer's S3-compatible credentials for one bucket, with role read or read_write. Secrets print once at create; delete revokes access immediately."
+	},
+	branch: {
+		brief: "View Platform branches: the isolated environment behind each Git branch",
+		description: "A Branch maps to a Git branch of the connected repository. Each is an isolated environment with its own services, databases, buckets, and environment variables: the production branch serves live traffic, every other branch is a preview."
+	},
+	git: {
+		brief: "Manage the GitHub connection that deploys on push. Connect or disconnect a repository",
+		description: "Connecting a GitHub repository turns on deploy-on-push: pushing a Git branch builds and deploys it to a matching Platform Branch. Disconnecting stops push deploys without touching anything already deployed."
+	},
+	service: {
+		brief: "Manage deployed services. Logs, versions, promote and rollback releases, custom domains",
+		description: "A service is one HTTP application (a frontend or a backend) deployed on a Branch. Every deploy produces an immutable service version; at most one serves traffic at a time. The 'version' subcommands move which one that is: promote releases a preview build into production, rollback returns production to a previous version without rebuilding. 'logs' reads and streams output, and 'domain' attaches hostnames you own.",
+		workflow: [
+			{
+				run: "service logs my-api --follow",
+				brief: "Stream the live version's logs"
+			},
+			{
+				run: "service version promote cpv_123",
+				brief: "Release a preview build to production"
+			},
+			{
+				run: "service version rollback my-api",
+				brief: "Put production back on the previous version"
+			}
+		]
+	},
+	"service domain": {
+		brief: "Manage custom domains for a service. Register hostnames, drive DNS and TLS verification, inspect status",
+		description: "Custom domains point hostnames you own at a service's production branch. After add, create the DNS record the platform reports; wait and retry drive DNS verification and TLS provisioning to done.",
+		workflow: [
+			{
+				run: "service domain add shop.acme.com --service my-api",
+				brief: "Register the hostname"
+			},
+			{
+				run: "service domain wait shop.acme.com --service my-api",
+				brief: "Block until active or failed"
+			},
+			{
+				run: "service domain show shop.acme.com --service my-api",
+				brief: "Inspect status and certificate"
+			}
+		]
+	},
+	"service version": {
+		brief: "Manage a service's deploy versions. List, inspect, promote, roll back, start, stop, delete",
+		description: "Every deploy produces an immutable version; at most one serves traffic at a time on each branch. List and show inspect them. Promote and rollback choose which version serves traffic; start, stop, and delete drive one version's lifecycle."
+	},
+	"auth workspace": {
+		brief: "Manage stored workspace sessions. List them, switch the current one, end one",
+		description: "One session is stored per workspace you log in to. List them, switch the current one, or end one without touching the others."
+	},
+	contract: {
+		brief: "Author your data contract: the PSL source of your data model. Emit, infer, format",
+		description: "A contract is the declarative description of your application's data model, authored in PSL (Prisma Schema Language). Migrations are planned from it, and live databases are verified and signed against it. Emit generates its artifacts, infer derives a contract from an existing database, and format normalizes the source."
+	},
+	db: {
+		brief: "Run contract operations against a live database. Verify, sign, update, migrate",
+		description: "These commands run against a live database, addressed with --db <url>. Verify checks the database against the contract (the PSL description of your data model), sign marks it as matching, and update and migrate advance its schema."
+	},
+	migration: {
+		brief: "Manage on-disk migrations derived from contract changes. Plan, inspect, check, track history",
+		description: "A migration is an on-disk package describing one schema change, derived from edits to your contract (the PSL description of your data model). Plan writes one; the rest inspect, check integrity, and track what has run where. Apply them with 'db migrate'."
+	},
+	"migration ref": {
+		brief: "Manage refs: named pointers to contracts. Set, list, delete",
+		description: "A ref is a named pointer to a contract, letting commands target a contract by a stable name. Set, list, and delete refs here."
+	},
 	orm: { brief: "Initialize a Prisma ORM project" },
-	skills: { brief: "Keep this project's Prisma agent skills current" },
+	skills: {
+		brief: "Manage Prisma skills for AI coding agents. Sync and list the instruction files",
+		description: "Agent skills are instruction files that teach AI coding agents (Claude Code, Cursor, and others) how to use the installed Prisma packages. They ship inside the packages; sync copies them into the directories the agent harnesses read."
+	},
 	...telemetry.groups
 };
 const mountedCommands = {
@@ -13103,7 +13275,25 @@ function buildCli() {
 		commands: mountedCommands,
 		help: {
 			tagline: "The Prisma Developer Platform, from your terminal",
-			description: "Deploy your app with isolated infrastructure for every branch.",
+			description: "Deploy your app with isolated infrastructure for every branch: a Project groups one product, and each of its Branches maps to a Git branch with its own services, databases, and buckets. The production branch serves live traffic; every other branch is a preview.",
+			workflow: [
+				{
+					run: "auth login",
+					brief: "Sign in to your Prisma workspace"
+				},
+				{
+					run: "project create my-app",
+					brief: "Create a Project, link this directory"
+				},
+				{
+					run: "git connect",
+					brief: "Connect GitHub so every push deploys"
+				},
+				{
+					run: "deploy",
+					brief: "Or build and deploy straight from this machine"
+				}
+			],
 			examples: [
 				"auth login",
 				"project list",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prisma/cli",
-  "version": "8.0.0-rc.13-dev.92",
+  "version": "8.0.0-rc.13-dev.93",
   "description": "Command-line interface for the Prisma Developer Platform.",
   "type": "module",
   "bin": {
@@ -41,10 +41,10 @@
   "dependencies": {
     "@manypkg/tools": "^2.1.2",
     "@prisma/cli-engine": "0.3.0",
-    "@prisma/composer-cli": "0.17.0-dev.1",
+    "@prisma/composer-cli": "0.17.0-dev.2",
     "@prisma/compute-sdk": "0.42.0",
     "@prisma/management-api-sdk": "1.69.0",
-    "@prisma/orm-toolchain": "8.0.0-rc.8-dev.13",
+    "@prisma/orm-toolchain": "8.0.0-rc.8-dev.18",
     "@vercel/detect-agent": "^1.2.3",
     "better-result": "^2.9.2",
     "dotenv": "^17.4.2",
@@ -52,11 +52,11 @@
     "open": "^11.0.0"
   },
   "devDependencies": {
-    "@prisma/composer": "0.17.0-dev.1",
+    "@prisma/composer": "0.17.0-dev.2",
     "@prisma/credentials-store": "^7.8.0",
-    "@repo/cli-conformance": "8.0.0-rc.13-dev.92",
-    "@repo/cli-telemetry": "8.0.0-rc.13-dev.92",
-    "@repo/tsconfig": "8.0.0-rc.13-dev.92",
+    "@repo/cli-conformance": "8.0.0-rc.13-dev.93",
+    "@repo/cli-telemetry": "8.0.0-rc.13-dev.93",
+    "@repo/tsconfig": "8.0.0-rc.13-dev.93",
     "@types/node": "^22.19.19",
     "tsdown": "^0.21.10",
     "tsx": "^4.22.4",