prisma · AmanVarshney01 · Jul 3, 2026 · Jul 3, 2026 · Jul 6, 2026 · Jul 6, 2026
diff --git a/docs/product/command-spec.md b/docs/product/command-spec.md
@@ -865,6 +865,34 @@ prisma-cli branch list
 prisma-cli branch list --json
 ```
 
+## `prisma-cli branch remove <branch> --project <id-or-name> --confirm <branch-id> --cascade`
+
+Purpose:
+
+- remove a preview Branch from the resolved project
+
+Behavior:
+
+- requires auth and resolved project context; accepts `--project <id-or-name>` as an explicit fallback
+- resolves `<branch>` by exact Branch id or exact git name within the resolved project
+- requires `--confirm <branch-id>` where the value exactly matches the resolved Branch id; `--yes` does not satisfy this confirmation
+- production Branches and the project's default Branch are protected: removal fails with `BRANCH_PROTECTED`, and `--cascade` never widens that; the protection check runs before any member resource is touched
+- without `--cascade`, a Branch that still has live Apps or databases fails with `BRANCH_NOT_EMPTY`; plain removal never deletes member resources, and the recovery steps offer both the cascade rerun and individual `app remove --branch` / `database` cleanup
+- with `--cascade`, the CLI removes the Branch's Apps, then its databases, then the Branch itself; the result lists every removed resource so the blast radius is explicit, in human output and in `result.removed` for `--json`
+- cascade is client-orchestrated because the platform's branch delete refuses non-empty Branches; a mid-cascade failure stops immediately and fails with `BRANCH_CASCADE_INCOMPLETE`, whose `meta` lists what was already removed (removed resources are not restored, and the Branch itself remains)
+- removal is a platform soft-delete: the Branch disappears from `branch list`, and the platform owns retention of soft-deleted Branches; cascaded member resources are removed through their own APIs
+- Branch creation stays implicit (git-push automation and `app deploy`); there is deliberately no `branch create`
+- never touches local Git branches
+- fails with `BRANCH_NOT_FOUND` when no Branch matches
+
+Examples:
+
+```bash
+prisma-cli branch remove feat-login --confirm br_123
+prisma-cli branch remove feat-login --confirm br_123 --cascade
+prisma-cli branch remove br_123 --confirm br_123 --json
+```
+
 ## `prisma-cli database list --project <id-or-name> --branch <git-name>`
 
 Purpose:
@@ -1829,16 +1857,18 @@ prisma-cli app rollback
 prisma-cli app rollback --app hello-world --to dep_123
 ```
 
-## `prisma-cli app remove [app] --app <name> -y --yes`
+## `prisma-cli app remove [app] --app <name> --branch <name> -y --yes`
 
 Purpose:
 
-- remove the app from the current branch
+- remove the app from the resolved branch
 
 Behavior:
 
 - requires auth and project context
-- resolves the selected app
+- resolves the branch it reads like the other management commands: explicit `--branch` honored as-is, then the active Git branch when it exists in the project, then the project's default branch
+- `--branch <name>` makes branch cleanup possible for branches that are not checked out locally, such as a teammate's preview branch
+- resolves the selected app within that branch
 - requires confirmation unless `-y` or `--yes` is passed
 - clears local selected app state when the removed app was selected
 

diff --git a/docs/product/error-conventions.md b/docs/product/error-conventions.md
@@ -181,6 +181,10 @@ These codes are the minimum stable set for the MVP:
 - `LOCAL_STATE_WRITE_FAILED`
 - `LOCAL_STATE_STALE`
 - `BRANCH_NOT_DEPLOYABLE`
+- `BRANCH_NOT_FOUND`
+- `BRANCH_PROTECTED`
+- `BRANCH_NOT_EMPTY`
+- `BRANCH_CASCADE_INCOMPLETE`
 - `COMPUTE_CONFIG_INVALID`
 - `COMPUTE_CONFIG_TARGET_REQUIRED`
 - `COMPUTE_CONFIG_TARGET_UNKNOWN`
@@ -252,6 +256,10 @@ Recommended meanings:
 - `LOCAL_STATE_WRITE_FAILED`: the CLI could not save local Project binding state such as `.prisma/local.json` or the matching `.gitignore` entry; callers should fix directory permissions or filesystem state before retrying
 - `LOCAL_STATE_STALE`: local Project pin no longer matches platform data and continuing would be ambiguous
 - `BRANCH_NOT_DEPLOYABLE`: command tried to deploy to a non-deployable branch context
+- `BRANCH_NOT_FOUND`: requested branch id or git name does not exist in the resolved project
+- `BRANCH_PROTECTED`: branch removal refused because the branch is the project's production or default branch
+- `BRANCH_NOT_EMPTY`: branch removal refused because the branch still has live apps or databases
+- `BRANCH_CASCADE_INCOMPLETE`: a --cascade branch removal failed partway; meta lists the resources already removed and the branch remains
 - `COMPUTE_CONFIG_INVALID`: `prisma.compute.ts` failed to load or validate
 - `COMPUTE_CONFIG_TARGET_REQUIRED`: a multi-app compute config needs an `[app]` target and none was given or inferred
 - `COMPUTE_CONFIG_TARGET_UNKNOWN`: the `[app]` target matches no configured app

diff --git a/docs/product/resource-model.md b/docs/product/resource-model.md
@@ -63,6 +63,14 @@ Rules:
 - every other named branch is a preview branch by default
 - preview branches are disposable by default
 - non-production branches can become durable later
+- Branch creation is implicit (git-push automation and `app deploy`); the CLI
+  has no `branch create`
+- `branch remove` removes a preview Branch with exact id confirmation; the
+  platform refuses production/default Branches outright, and plain removal
+  refuses Branches that still have live Apps or databases
+- `branch remove --cascade` removes a preview Branch's Apps and databases with
+  it, with the blast radius listed explicitly; production/default Branches stay
+  refused regardless of flags
 - `local` is local CLI context only, not a branch
 - branch context comes from explicit targeting, Git, or safe command defaults,
   not `prisma.config.ts`

diff --git a/packages/cli/src/adapters/mock-api.ts b/packages/cli/src/adapters/mock-api.ts
@@ -38,6 +38,7 @@ interface BranchRecord {
   projectId: string;
   name: string;
   role: "production" | "preview";
+  isDefault?: boolean;
   currentDeploymentId: string | null;
 }
 
@@ -279,6 +280,94 @@ export class MockApi {
     );
   }
 
+  cascadeBranchResources(branchId: string): {
+    apps: Array<{ id: string; name: string }>;
+    databases: Array<{ id: string; name: string }>;
+  } {
+    const branch = this.data.branches.find(
+      (candidate) => candidate.id === branchId,
+    );
+    if (!branch) {
+      return { apps: [], databases: [] };
+    }
+
+    const databases = (this.data.databases ?? []).filter(
+      (database) => database.branchId === branchId,
+    );
+    const databaseIds = new Set(databases.map((database) => database.id));
+    // The fixture has no standalone app records; deployments on the branch
+    // stand in for its apps.
+    const apps = this.data.deployments.filter(
+      (deployment) =>
+        deployment.projectId === branch.projectId &&
+        deployment.branch === branch.name,
+    );
+
+    this.data.databases = (this.data.databases ?? []).filter(
+      (database) => database.branchId !== branchId,
+    );
+    this.data.databaseConnections = (
+      this.data.databaseConnections ?? []
+    ).filter((connection) => !databaseIds.has(connection.databaseId));
+    this.data.deployments = this.data.deployments.filter(
+      (deployment) =>
+        !(
+          deployment.projectId === branch.projectId &&
+          deployment.branch === branch.name
+        ),
+    );
+
+    return {
+      apps: apps.map((deployment) => ({
+        id: deployment.id,
+        name: deployment.id,
+      })),
+      databases: databases.map((database) => ({
+        id: database.id,
+        name: database.name,
+      })),
+    };
+  }
+
+  removeBranch(
+    branchId: string,
+  ):
+    | { outcome: "removed"; branch: BranchRecord }
+    | { outcome: "not-found" }
+    | { outcome: "protected" }
+    | { outcome: "not-empty" } {
+    const branch = this.data.branches.find(
+      (candidate) => candidate.id === branchId,
+    );
+    if (!branch) {
+      return { outcome: "not-found" };
+    }
+    // Mirrors the platform rule: production and default branches are
+    // protected outright.
+    if (branch.role === "production" || branch.isDefault) {
+      return { outcome: "protected" };
+    }
+
+    // Mirrors the platform rule: removal is refused while the branch still
+    // has live member resources.
+    const hasDatabases = (this.data.databases ?? []).some(
+      (database) => database.branchId === branchId,
+    );
+    const hasDeployments = this.data.deployments.some(
+      (deployment) =>
+        deployment.projectId === branch.projectId &&
+        deployment.branch === branch.name,
+    );
+    if (hasDatabases || hasDeployments) {
+      return { outcome: "not-empty" };
+    }
+
+    this.data.branches = this.data.branches.filter(
+      (candidate) => candidate.id !== branchId,
+    );
+    return { outcome: "removed", branch };
+  }
+
   getDeployment(deploymentId: string): DeploymentRecord | undefined {
     return this.data.deployments.find(
       (deployment) => deployment.id === deploymentId,

diff --git a/packages/cli/src/commands/app/index.ts b/packages/cli/src/commands/app/index.ts
@@ -835,18 +835,21 @@ function createRemoveCommand(runtime: CliRuntime): Command {
       "App target from prisma.compute.ts when the config defines multiple apps",
     )
     .addOption(new Option("--app <name>", "App name"))
-    .addOption(new Option("--project <id-or-name>", "Project id or name"));
+    .addOption(new Option("--project <id-or-name>", "Project id or name"))
+    .addOption(new Option("--branch <name>", "Branch name"));
   addGlobalFlags(command);
 
   command.action(async (configTarget: string | undefined, options) => {
     const appName = (options as { app?: string }).app;
     const projectRef = (options as { project?: string }).project;
+    const branchName = (options as { branch?: string }).branch;
 
     await runCommand<AppRemoveResult>(
       runtime,
       "app.remove",
       options as Record<string, unknown>,
-      (context) => runAppRemove(context, appName, projectRef, configTarget),
+      (context) =>
+        runAppRemove(context, appName, projectRef, configTarget, branchName),
       {
         renderHuman: (context, descriptor, result) =>
           renderAppRemove(context, descriptor, result),

diff --git a/packages/cli/src/commands/branch/index.ts b/packages/cli/src/commands/branch/index.ts
@@ -1,15 +1,20 @@
-import { Command } from "commander";
+import { Command, Option } from "commander";
 
-import { runBranchList } from "../../controllers/branch";
-import { renderBranchList, serializeBranchList } from "../../presenters/branch";
+import { runBranchList, runBranchRemove } from "../../controllers/branch";
+import {
+  renderBranchList,
+  renderBranchRemove,
+  serializeBranchList,
+  serializeBranchRemove,
+} from "../../presenters/branch";
 import { attachCommandDescriptor } from "../../shell/command-meta";
 import { runCommand } from "../../shell/command-runner";
 import {
   addCompactGlobalFlags,
   addGlobalFlags,
 } from "../../shell/global-flags";
 import { type CliRuntime, configureRuntimeCommand } from "../../shell/runtime";
-import type { BranchListResult } from "../../types/branch";
+import type { BranchListResult, BranchRemoveResult } from "../../types/branch";
 
 export function createBranchCommand(runtime: CliRuntime): Command {
   const branch = attachCommandDescriptor(
@@ -20,10 +25,53 @@ export function createBranchCommand(runtime: CliRuntime): Command {
   addCompactGlobalFlags(branch);
 
   branch.addCommand(createBranchListCommand(runtime));
+  branch.addCommand(createBranchRemoveCommand(runtime));
 
   return branch;
 }
 
+function createBranchRemoveCommand(runtime: CliRuntime): Command {
+  const command = attachCommandDescriptor(
+    configureRuntimeCommand(new Command("remove"), runtime),
+    "branch.remove",
+  );
+
+  command
+    .argument("<branch>", "Branch id or git name")
+    .addOption(new Option("--project <id-or-name>", "Project id or name"))
+    .addOption(
+      new Option("--confirm <branch-id>", "Exact branch id required to remove"),
+    )
+    .addOption(
+      new Option(
+        "--cascade",
+        "Also remove the branch's apps and databases (preview branches only)",
+      ),
+    );
+  addGlobalFlags(command);
+
+  command.action(async (branchRef: string, options) => {
+    const projectRef = (options as { project?: string }).project;
+    const confirm = (options as { confirm?: string }).confirm;
+    const cascade = (options as { cascade?: boolean }).cascade;
+
+    await runCommand<BranchRemoveResult>(
+      runtime,
+      "branch.remove",
+      options as Record<string, unknown>,
+      (context) =>
+        runBranchRemove(context, branchRef, { projectRef, confirm, cascade }),
+      {
+        renderHuman: (context, descriptor, result) =>
+          renderBranchRemove(context, descriptor, result),
+        renderJson: (result) => serializeBranchRemove(result),
+      },
+    );
+  });
+
+  return command;
+}
+
 function createBranchListCommand(runtime: CliRuntime): Command {
   const command = attachCommandDescriptor(
     configureRuntimeCommand(new Command("list"), runtime),

diff --git a/packages/cli/src/controllers/app.ts b/packages/cli/src/controllers/app.ts
@@ -584,7 +584,7 @@
 }

 async function runSingleAppDeploy(
  context: CommandContext,
  appName: string | undefined,
  options: AppDeployOptions | undefined,
  preloadedConfig: LoadedComputeConfig | null,
@@ -1179,9 +1179,9 @@
            : deployment.deployment.live,
      },
    },
    warnings: [],
    nextSteps: [],
  };
 }

 export async function runAppOpen(
@@ -1560,10 +1560,10 @@
      context.runtime.signal,
    );
    current = await target.provider
      .showDomain(current.id, { signal: context.runtime.signal })
      .catch((error) => {
        throw domainCommandError("wait", error, normalizedHostname);
      });
  }
 }

@@ -2043,6 +2043,7 @@
   appName: string | undefined,
   projectRef?: string,
   configTarget?: string,
+  branchName?: string,
 ): Promise<CommandSuccess<AppRemoveResult>> {
   ensurePreviewAppMode(context);
 
@@ -2056,6 +2057,12 @@
     await requireProviderAndProjectContext(context, projectRef, {
       commandName: "app remove",
       projectDir: compute.projectDir,
+      // Branch cleanup needs "remove this app from that branch" even when the
+      // branch is not checked out locally, so an explicit --branch is honored
+      // as-is like the other read-branch commands.
+      branch: branchName
+        ? await resolveDeployBranch(context, branchName)
+        : undefined,
     });
   const apps = await listApps(context, provider, projectId, target.branch.name);
   const selectedApp = await requireReleaseAppSelection(
@@ -2125,7 +2132,7 @@
  const branch = resolveDomainBranch(options?.branchName);
  if (toBranchKind(branch.name) !== "production") {
    throw new CliError({
      code: "BRANCH_NOT_DEPLOYABLE",
      domain: "branch",
      summary: "Custom domains require the production branch",
      why: `Custom domains on preview branch "${branch.name}" are not supported in Public Beta.`,
@@ -2258,7 +2265,7 @@
    throw new CliError({
      code: "DOMAIN_HOSTNAME_INVALID",
      domain: "app",
      summary: `Invalid custom domain "${hostname}"`,
      why: "Custom domains must be valid hostnames without protocol, path, wildcard, or port.",
      fix: "Pass a hostname like shop.acme.com.",
      exitCode: 2,
@@ -2293,14 +2300,14 @@
 }

 function sameDomainHostname(left: string, right: string): boolean {
  return (
    left.trim().replace(/\.$/, "").toLowerCase() ===
    right.trim().replace(/\.$/, "").toLowerCase()
  );
 }

 function toAppDomainSummary(domain: DomainRecord): AppDomainSummary {
  return {
    id: domain.id,
    type: domain.type,
    url: domain.url,
@@ -2388,7 +2395,7 @@
  error: unknown,
  hostname: string,
 ): CliError {
  if (error instanceof DomainApiError) {
    if (
      command === "add" &&
      (error.status === 400 || error.status === 422) &&
@@ -2554,7 +2561,7 @@
 }

 function domainNotFoundError(hostname: string): CliError {
  return new CliError({
    code: "DOMAIN_NOT_FOUND",
    domain: "app",
    summary: `Custom domain "${hostname}" not found`,
@@ -2590,7 +2597,7 @@
    throw usageError(
      `Invalid timeout "${value}"`,
      "Timeout must be a duration such as 0, 30s, 15m, or 1h.",
      "Pass --timeout 15m, or --timeout 0 to poll once.",
      ["prisma-cli app domain wait shop.acme.com --timeout 15m"],
      "app",
    );
@@ -2606,11 +2613,11 @@
        : unit === "s"
          ? 1000
          : 1;
  return amount * multiplier;
 }

 function readDomainWaitPollIntervalMs(context: CommandContext): number {
  const raw = context.runtime.env.PRISMA_CLI_DOMAIN_WAIT_POLL_MS;
  if (!raw) {
    return 5_000;
  }
@@ -3384,7 +3391,7 @@
      ),
    commandName: options?.commandName,
  });
  if (resolvedResult.isErr()) {
    throw projectResolutionErrorToCliError(resolvedResult.error);
  }
  const resolved = resolvedResult.value;
@@ -3418,7 +3425,7 @@
  client: ManagementApiClient,
  provider: ReturnType<typeof createAppProvider>,
  explicitProject: string | undefined,
  options: {
    branch?: ResolvedDeployBranch;
    createProjectName?: string;
    envProjectId?: string;
@@ -4093,7 +4100,7 @@
      !configFile.exists &&
      !hasAnyPackageDependency(packageJson, framework.detectPackages)
    ) {
      continue;
    }

    // Next.js standalone output gets a richer annotation; everything else is
@@ -4106,8 +4113,8 @@
          : "detected from package.json";

    return {
      key: framework.key,
      buildType: framework.buildType,
      displayName: framework.displayName,
      annotation,
    };
@@ -4130,10 +4137,10 @@
        exists: true,
        standalone: /\boutput\s*:\s*["'`]standalone["'`]/.test(content),
        path: filePath,
      };
    } catch (error) {
      if (signal.aborted) throw error;
      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
        throw error;
      }
    }