@amerged/ohmyhost-cli 0.1.15 → 0.1.18

package/dist/index.js

@@ -30,6 +30,7 @@ import {
   parseCloudflareDnsAuthorization,
   parseCloudflareDnsAuthorizationStatus,
   parseCurrentIdentity,
+  parseDevAccessState,
   parseDevAccessTicket,
   parseOperation,
   parseOperationEvent,
@@ -37,9 +38,11 @@ import {
   parsePaidDomainPlan,
   parseProductCliCommand,
   parseSafeProblem,
+  parseWithLinkedProject,
   prepareUserTokenFile,
   publicWorkspace,
   readBoundedResponseBody,
+  readLinkedProjectId,
   readSecretValueFromStandardInput,
   recognizedCommandLabel,
   resolveProductCliEnvironment,
@@ -47,7 +50,7 @@ import {
   selectWorkspace,
   selectedWorkspaceId,
   workspaceOf
-} from "./chunk-3BEMNNWB.js";
+} from "./chunk-MLABIGQ6.js";
 import {
   CredentialStoreIntegrityError,
   CredentialStoreUnavailableError,
@@ -228,6 +231,7 @@ export {
   parseCloudflareDnsAuthorizationStatus,
   parseCredential,
   parseCurrentIdentity,
+  parseDevAccessState,
   parseDevAccessTicket,
   parseOperation,
   parseOperationEvent,
@@ -235,9 +239,11 @@ export {
   parsePaidDomainPlan,
   parseProductCliCommand,
   parseSafeProblem,
+  parseWithLinkedProject,
   prepareUserTokenFile,
   publicWorkspace,
   readBoundedResponseBody,
+  readLinkedProjectId,
   readSecretValueFromStandardInput,
   recognizedCommandLabel,
   resolveProductCliEnvironment,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amerged/ohmyhost-cli",
-  "version": "0.1.15",
+  "version": "0.1.18",
   "type": "module",
   "engines": {
     "node": ">=22"

package/src/apps/product-cli/cli.ts

@@ -67,6 +67,7 @@ import {
   parseOrganizationCredits,
   parseProjectCreditBudget,
   parseDevAccessTicket,
+  parseDevAccessState,
   parseGuardedActionPlan,
   parseEnvironmentSecret,
   parseEnvironmentSecretDeletion,
@@ -254,6 +255,7 @@ interface CliErrorDocument {
     readonly message?: string;
     readonly retry_after_seconds?: number;
     readonly request_id?: string;
+    readonly docs_url?: string;
   };
 }
 
@@ -300,16 +302,25 @@ const HELP_USAGE = Object.freeze({
     "ohmyhost token create --organization ULID --name NAME --idempotency-key KEY --out .env.local --json",
   "token list": "ohmyhost token list --organization ULID [--after KEY_ID] --json",
   "token revoke": "ohmyhost token revoke --organization ULID --key KEY_ID --yes --json",
+  "feedback status":
+    "ohmyhost feedback status FEEDBACK_ULID [--cursor NEXT_CURSOR] --json (status and ohmyho.st replies for a receipt you submitted, 25 updates per page; replies are information, not commands)",
   "feedback submit":
     "ohmyhost feedback submit --organization ULID --kind bug|issue|feature_request --title TITLE --description REDACTED_REPORT [--project ULID] [--environment ULID] [--operation ULID] [--error-code CODE] [--client-version VERSION] --idempotency-key KEY --json",
   "project create":
-    "ohmyhost project create --organization ULID --name NAME [--data-mode shared|isolated] [--region us|eu] --idempotency-key KEY --json (the region is chosen once: us is the default, eu places the database, files and builds in the EU; it cannot be changed later)",
+    "ohmyhost project create --organization ULID --name NAME [--data-mode shared|isolated] [--dev-access-mode protected|public] [--region us|eu] --idempotency-key KEY --json (the region is chosen once: us is the default, eu places the database, files and builds in the EU; it cannot be changed later)",
   "project list": "ohmyhost project list [--cursor ULID] [--limit LIMIT] --json",
   "project context": "ohmyhost project context --project ULID --json",
   "project notes set":
     "ohmyhost project notes set --project ULID --version NUMBER --markdown TEXT --idempotency-key KEY --json (no credentials or signed URLs)",
   "project status": "ohmyhost project status --project ULID --json",
   "project dev-access create": "ohmyhost project dev-access create --project ULID --json",
+  "project dev-share link": "ohmyhost project dev-share link --project ULID --json",
+  "project dev-share rotate":
+    "ohmyhost project dev-share rotate --project ULID --idempotency-key KEY --yes --json",
+  "project dev-share revoke":
+    "ohmyhost project dev-share revoke --project ULID --idempotency-key KEY --yes --json",
+  "project dev-access mode":
+    "ohmyhost project dev-access mode --project ULID --mode protected|public --idempotency-key KEY --yes --json",
   "project handle check":
     "ohmyhost project handle check --handle HANDLE --json (is this address free? answers with a reason and free alternatives; the address becomes HANDLE.check.omh.st)",
   "project handle set":
@@ -347,9 +358,9 @@ const HELP_USAGE = Object.freeze({
   "domain paid status": "ohmyhost domain paid status --project ULID --json",
   "domain paid delete":
     "ohmyhost domain paid delete --project ULID --hostname HOST --idempotency-key KEY --yes --json",
-  plan: "ohmyhost plan --project ULID --commit SHA --json",
+  plan: "ohmyhost plan --project ULID --commit SHA [--environment dev|prod] --json",
   deploy:
-    "ohmyhost deploy --project ULID --plan-id ULID --idempotency-key KEY --yes [--wait] --json",
+    "ohmyhost deploy --project ULID (--plan-id ULID | --commit SHA [--environment dev|prod]) --idempotency-key KEY --yes [--wait] --json",
   logs: "ohmyhost logs OPERATION_ULID --follow --json",
   "deployment logs": "ohmyhost deployment logs --project ULID --deployment ULID --follow --json",
   "rollback plan": "ohmyhost rollback plan --project ULID --deployment DEPLOYMENT_ULID --json",
@@ -387,6 +398,8 @@ const HELP_USAGE = Object.freeze({
   "mail domain set":
     "ohmyhost mail domain set --project ULID --environment ULID --domain DOMAIN --sending true --receiving false --idempotency-key KEY --json",
   "mail domain status": "ohmyhost mail domain status --project ULID --environment ULID --json",
+  "mail domain delete":
+    "ohmyhost mail domain delete --project ULID --environment ULID --idempotency-key KEY --yes --json",
 } satisfies Readonly<Record<CustomerCommandLabel, string>>);
 
 const HELP_COMMANDS = Object.freeze(
@@ -697,6 +710,11 @@ export class ProductCli {
         assertProjectExport(result);
         return success("export get", { status: result.state, export: result });
       }
+      if (command.kind === "feedback-status") {
+        const api = await this.authenticatedApi(command.credentialStore, signal);
+        const feedback = await api.getFeedback(command.feedbackId, command.cursor);
+        return success("feedback status", { status: "succeeded", feedback });
+      }
       if (command.kind === "feedback-submit") {
         const api = await this.authenticatedApi(command.credentialStore, signal);
         return success("feedback submit", {
@@ -740,6 +758,37 @@ export class ProductCli {
       if (command.kind === "project-status") return await this.getProjectStatus(command, signal);
       if (command.kind === "project-dev-access-create")
         return await this.createDevAccessTicket(command, signal);
+      if (
+        command.kind === "project-dev-share-link" ||
+        command.kind === "project-dev-share-rotate" ||
+        command.kind === "project-dev-share-revoke" ||
+        command.kind === "project-dev-access-mode-set"
+      ) {
+        const api = await this.authenticatedApi(command.credentialStore, signal);
+        const state = parseDevAccessState(
+          command.kind === "project-dev-share-link"
+            ? await api.ensureDevShareLink(command.projectId)
+            : command.kind === "project-dev-share-rotate"
+              ? await api.rotateDevShareLink(command.projectId, command.idempotencyKey)
+              : command.kind === "project-dev-share-revoke"
+                ? await api.revokeDevShareLink(command.projectId, command.idempotencyKey)
+                : await api.setDevAccessMode(
+                    command.projectId,
+                    command.mode,
+                    command.idempotencyKey,
+                  ),
+        );
+        return success(
+          command.kind === "project-dev-share-link"
+            ? "project dev-share link"
+            : command.kind === "project-dev-share-rotate"
+              ? "project dev-share rotate"
+              : command.kind === "project-dev-share-revoke"
+                ? "project dev-share revoke"
+                : "project dev-access mode",
+          { status: "succeeded", state },
+        );
+      }
       if (command.kind === "database-write") {
         const file = await open(command.statementFile, "r"),
           buffer = Buffer.alloc(65_537);
@@ -1169,6 +1218,7 @@ export class ProductCli {
         organizationId: command.organizationId,
         name: command.name,
         ...(command.dataMode === undefined ? {} : { dataMode: command.dataMode }),
+        ...(command.devAccessMode === undefined ? {} : { devAccessMode: command.devAccessMode }),
         ...(command.region === undefined ? {} : { region: command.region }),
         idempotencyKey: command.idempotencyKey,
       }),
@@ -1451,7 +1501,10 @@ export class ProductCli {
   ): Promise<CliResult> {
     const api = await this.authenticatedApi(command.credentialStore, signal);
     const autoDeploy = await api.getAutoDeploy(command.projectId);
-    return success("source auto-deploy status", { status: "ready", auto_deploy: autoDeploy });
+    return success("source auto-deploy status", {
+      status: autoDeploy.generation === 0 ? "not_configured" : "ready",
+      auto_deploy: autoDeploy,
+    });
   }
 
   private async authorizeCloudflareDns(
@@ -1507,7 +1560,16 @@ export class ProductCli {
   ): Promise<CliResult> {
     const api = await this.authenticatedApi(command.credentialStore, signal);
     const plan = parseDeploymentPlan(await api.planDeployment(command));
-    return success("plan", { status: "planned", plan });
+    // Say which environment this plan changes and how the change reaches the live site.
+    const notes =
+      plan["environment"] === "prod"
+        ? [
+            `This plan builds straight into Prod (${String(plan["route"])}); Prod traffic switches once it is activated.`,
+          ]
+        : [
+            `This plan updates Dev only (${String(plan["route"])}). To go live, deploy with --environment prod or promote the Dev deployment with '${this.dependencies.commandPrefix} deployment promote plan --project ULID --deployment DEV_DEPLOYMENT_ULID --json'.`,
+          ];
+    return success("plan", { status: "planned", plan, notes });
   }
 
   private async deploy(
@@ -1515,20 +1577,37 @@ export class ProductCli {
     signal: AbortSignal,
   ): Promise<CliResult> {
     const api = await this.authenticatedApi(command.credentialStore, signal);
-    let operation = parseOperation(await api.createDeployment(command));
+    // With --commit the deploy plans first, so an approved deploy needs no separate plan step.
+    const plan =
+      command.commitSha === null
+        ? null
+        : parseDeploymentPlan(
+            await api.planDeployment({
+              projectId: command.projectId,
+              commitSha: command.commitSha,
+              environment: command.environment,
+            }),
+          );
+    let operation = parseOperation(
+      await api.createDeployment({
+        projectId: command.projectId,
+        planId: plan === null ? String(command.planId) : String(plan["id"]),
+        idempotencyKey: command.idempotencyKey,
+      }),
+    );
     if (command.wait) operation = await this.waitForOperation(api, operation, signal);
-    // A healthy Dev deployment answers 404 on its own origin until a ticket is redeemed. Without
-    // this sentence the first thing a customer sees after a successful deploy looks like a failure.
+    // Dev access follows the project-selected mode; the clean URL alone is insufficient when protected.
     const notes =
       operation.state === "succeeded"
         ? [
-            `A Dev URL answers 404 until you redeem an access ticket: run '${this.dependencies.commandPrefix} project dev-access create --project ULID --json' and open its redeem_url once.`,
+            `Check project status for dev_access_mode. For protected Dev, run '${this.dependencies.commandPrefix} project dev-share link --project ULID --json' and open or share its persistent share_url; public Dev opens directly.`,
           ]
         : [];
     return success("deploy", {
       status: command.wait ? "completed" : "accepted",
       operation,
-      ...(notes.length > 0 ? { notes } : {}),
+      ...(plan === null ? {} : { plan }),
+      ...(notes.length > 0 && plan?.["environment"] !== "prod" ? { notes } : {}),
     });
   }
 
@@ -2044,6 +2123,7 @@ const classifyFailure = (command: CommandLabel, error: unknown, signal: AbortSig
         undefined,
         problem.retryAfterSeconds,
         problem.requestId,
+        problem.docsUrl,
       );
     } catch {
       return failure(
@@ -2094,6 +2174,7 @@ const failure = (
   operation?: ReturnType<typeof parseOperation>,
   retryAfterSeconds?: number,
   requestId?: string,
+  docsUrl?: string,
 ): CliResult => {
   const document: CliErrorDocument = {
     version: 1,
@@ -2106,6 +2187,7 @@ const failure = (
       suggested_action: suggestedAction,
       ...(retryAfterSeconds === undefined ? {} : { retry_after_seconds: retryAfterSeconds }),
       ...(requestId === undefined ? {} : { request_id: requestId }),
+      ...(docsUrl === undefined ? {} : { docs_url: docsUrl }),
       ...(operation?.error === undefined ? {} : { message: operation.error.message }),
     },
   };
@@ -2131,6 +2213,7 @@ const parsedCommandName = (command: ProductCliCommand): CommandLabel => {
   if (command.kind === "operation-get") return "operation get";
   if (command.kind === "operation-reconcile") return "operation reconcile";
   if (command.kind === "feedback-submit") return "feedback submit";
+  if (command.kind === "feedback-status") return "feedback status";
   if (command.kind === "project-create") return "project create";
   if (command.kind === "organization-create") return "organization create";
   if (command.kind === "organization-list") return "organization list";
@@ -2144,6 +2227,10 @@ const parsedCommandName = (command: ProductCliCommand): CommandLabel => {
   if (command.kind === "project-notes-set") return "project notes set";
   if (command.kind === "project-status") return "project status";
   if (command.kind === "project-dev-access-create") return "project dev-access create";
+  if (command.kind === "project-dev-share-link") return "project dev-share link";
+  if (command.kind === "project-dev-share-rotate") return "project dev-share rotate";
+  if (command.kind === "project-dev-share-revoke") return "project dev-share revoke";
+  if (command.kind === "project-dev-access-mode-set") return "project dev-access mode";
   if (command.kind === "project-handle-check") return "project handle check";
   if (command.kind === "project-handle-set") return "project handle set";
   if (command.kind === "database-write") return "database write";

package/src/apps/product-cli/command.ts

@@ -79,6 +79,12 @@ export type ProductCliCommand =
       readonly idempotencyKey: string;
       readonly credentialStore: "native";
     }
+  | {
+      readonly kind: "feedback-status";
+      readonly feedbackId: string;
+      readonly cursor?: string;
+      readonly credentialStore: "native";
+    }
   | { kind: "billing-recharge-get"; organizationId: string; credentialStore: "native" }
   | ({ kind: "billing-recharge-set"; credentialStore: "native" } & {
       organizationId: string;
@@ -200,6 +206,7 @@ export type ProductCliCommand =
       readonly organizationId: string;
       readonly name: string;
       readonly dataMode?: "shared" | "isolated";
+      readonly devAccessMode?: "protected" | "public";
       readonly region?: "us" | "eu";
       readonly idempotencyKey: string;
       readonly credentialStore: "native";
@@ -215,6 +222,30 @@ export type ProductCliCommand =
       readonly projectId: string;
       readonly credentialStore: "native";
     }
+  | {
+      readonly kind: "project-dev-share-link";
+      readonly projectId: string;
+      readonly credentialStore: "native";
+    }
+  | {
+      readonly kind: "project-dev-share-rotate";
+      readonly projectId: string;
+      readonly idempotencyKey: string;
+      readonly credentialStore: "native";
+    }
+  | {
+      readonly kind: "project-dev-share-revoke";
+      readonly projectId: string;
+      readonly idempotencyKey: string;
+      readonly credentialStore: "native";
+    }
+  | {
+      readonly kind: "project-dev-access-mode-set";
+      readonly projectId: string;
+      readonly mode: "protected" | "public";
+      readonly idempotencyKey: string;
+      readonly credentialStore: "native";
+    }
   | {
       readonly kind: "project-dev-access-create";
       readonly projectId: string;
@@ -294,12 +325,16 @@ export type ProductCliCommand =
       readonly kind: "plan";
       readonly projectId: string;
       readonly commitSha: string;
+      readonly environment: "dev" | "prod";
       readonly credentialStore: "native";
     }
   | {
       readonly kind: "deploy";
       readonly projectId: string;
-      readonly planId: string;
+      /** Exactly one of an existing plan or a commit that is planned first. */
+      readonly planId: string | null;
+      readonly commitSha: string | null;
+      readonly environment: "dev" | "prod";
       readonly idempotencyKey: string;
       readonly yes: true;
       readonly wait: boolean;
@@ -403,6 +438,7 @@ export type ProductCliCommand =
       readonly label:
         | "mail domain set"
         | "mail domain status"
+        | "mail domain delete"
         | "mail setup"
         | "mail status"
         | "mail webhook set"
@@ -498,6 +534,7 @@ export type RecognizedCommandLabel =
   | "token list"
   | "token revoke"
   | "feedback submit"
+  | "feedback status"
   | "project create"
   | "organization create"
   | "organization list"
@@ -507,6 +544,10 @@ export type RecognizedCommandLabel =
   | "project list"
   | "project status"
   | "project dev-access create"
+  | "project dev-share link"
+  | "project dev-share rotate"
+  | "project dev-share revoke"
+  | "project dev-access mode"
   | "project handle check"
   | "project handle set"
   | "database write"
@@ -548,7 +589,8 @@ export type RecognizedCommandLabel =
   | "mail messages get"
   | "mail messages retry"
   | "mail domain set"
-  | "mail domain status";
+  | "mail domain status"
+  | "mail domain delete";
 
 export const recognizedCommandLabel = (argv: readonly string[]): RecognizedCommandLabel => {
   const values = [...argv];
@@ -597,6 +639,7 @@ export const recognizedCommandLabel = (argv: readonly string[]): RecognizedComma
     if (value === "export" && (values[0] === "create" || values[0] === "get"))
       return `export ${values[0]}`;
     if (value === "feedback" && values[0] === "submit") return "feedback submit";
+    if (value === "feedback" && values[0] === "status") return "feedback status";
     if (value === "project" && values[0] === "create") return "project create";
     if (value === "organization" && values[0] === "create") return "organization create";
     if (value === "organization" && values[0] === "list") return "organization list";
@@ -610,6 +653,18 @@ export const recognizedCommandLabel = (argv: readonly string[]): RecognizedComma
       return "project handle check";
     if (value === "project" && values[0] === "handle" && values[1] === "set")
       return "project handle set";
+    if (
+      value === "project" &&
+      values[0] === "dev-share" &&
+      ["link", "rotate", "revoke"].includes(values[1] ?? "")
+    )
+      return values[1] === "link"
+        ? "project dev-share link"
+        : values[1] === "rotate"
+          ? "project dev-share rotate"
+          : "project dev-share revoke";
+    if (value === "project" && values[0] === "dev-access" && values[1] === "mode")
+      return "project dev-access mode";
     if (value === "project" && values[0] === "dev-access" && values[1] === "create")
       return "project dev-access create";
     if (value === "database" && values[0] === "compute" && values[1] === "set")
@@ -669,6 +724,7 @@ export const recognizedCommandLabel = (argv: readonly string[]): RecognizedComma
     if (value === "mail" && values[0] === "domain") {
       if (values[1] === "set") return "mail domain set";
       if (values[1] === "status") return "mail domain status";
+      if (values[1] === "delete") return "mail domain delete";
     }
     return "unknown";
   }
@@ -798,6 +854,18 @@ export const parseProductCliCommand = (argv: readonly string[]): ProductCliComma
       return { kind: "token-revoke", organizationId, keyId: options["--key"], credentialStore };
     throw new InvalidCommandError();
   }
+  if (first === "feedback" && values[0] === "status") {
+    values.shift();
+    const feedbackId = values.shift();
+    if (yes || wait || follow || stdin || !isValue(feedbackId)) throw new InvalidCommandError();
+    const cursor = parseOptionalOptions(values, ["--cursor"])["--cursor"];
+    return {
+      kind: "feedback-status",
+      feedbackId,
+      ...(cursor === undefined ? {} : { cursor }),
+      credentialStore,
+    };
+  }
   if (first === "feedback" && values.shift() === "submit") {
     if (yes || wait || follow || stdin) throw new InvalidCommandError();
     const options = parseOptionalOptions(values, [
@@ -1116,6 +1184,38 @@ export const parseProductCliCommand = (argv: readonly string[]): ProductCliComma
       const options = parseOptions(values, ["--handle"]);
       return { kind: "project-handle-check", handle: options["--handle"], credentialStore };
     }
+    if (subcommand === "dev-share") {
+      const action = values.shift();
+      if (action === "link") {
+        if (yes || wait || follow || stdin) throw new InvalidCommandError();
+        const options = parseOptions(values, ["--project"]);
+        return { kind: "project-dev-share-link", projectId: options["--project"], credentialStore };
+      }
+      if ((action === "rotate" || action === "revoke") && yes && !wait && !follow && !stdin) {
+        const options = parseOptions(values, ["--project", "--idempotency-key"]);
+        return {
+          kind: action === "rotate" ? "project-dev-share-rotate" : "project-dev-share-revoke",
+          projectId: options["--project"],
+          idempotencyKey: options["--idempotency-key"],
+          credentialStore,
+        };
+      }
+      throw new InvalidCommandError();
+    }
+    if (subcommand === "dev-access" && values[0] === "mode") {
+      values.shift();
+      if (!yes || wait || follow || stdin) throw new InvalidCommandError();
+      const options = parseOptions(values, ["--project", "--mode", "--idempotency-key"]);
+      if (options["--mode"] !== "protected" && options["--mode"] !== "public")
+        throw new InvalidCommandError();
+      return {
+        kind: "project-dev-access-mode-set",
+        projectId: options["--project"],
+        mode: options["--mode"],
+        idempotencyKey: options["--idempotency-key"],
+        credentialStore,
+      };
+    }
     if (subcommand === "dev-access" && values.shift() === "create") {
       if (yes || wait || follow || stdin) throw new InvalidCommandError();
       const options = parseOptions(values, ["--project"]);
@@ -1177,15 +1277,20 @@ export const parseProductCliCommand = (argv: readonly string[]): ProductCliComma
       "--name",
       "--idempotency-key",
       "--data-mode",
+      "--dev-access-mode",
       "--region",
     ]);
     const dataMode = options["--data-mode"];
+    const devAccessMode = options["--dev-access-mode"];
     const region = options["--region"];
     if (
       !options["--organization"] ||
       !options["--name"] ||
       !options["--idempotency-key"] ||
       (dataMode !== undefined && dataMode !== "shared" && dataMode !== "isolated") ||
+      (devAccessMode !== undefined &&
+        devAccessMode !== "protected" &&
+        devAccessMode !== "public") ||
       (region !== undefined && region !== "us" && region !== "eu")
     )
       throw new InvalidCommandError();
@@ -1194,6 +1299,7 @@ export const parseProductCliCommand = (argv: readonly string[]): ProductCliComma
       organizationId: options["--organization"],
       name: options["--name"],
       ...(dataMode === undefined ? {} : { dataMode }),
+      ...(devAccessMode === undefined ? {} : { devAccessMode }),
       ...(region === undefined ? {} : { region }),
       idempotencyKey: options["--idempotency-key"],
       credentialStore,
@@ -1465,22 +1571,46 @@ export const parseProductCliCommand = (argv: readonly string[]): ProductCliComma
   }
   if (first === "plan") {
     if (yes || wait || follow || stdin) throw new InvalidCommandError();
-    const options = parseOptions(values, ["--project", "--commit"]);
+    const options = parseOptionalOptions(values, ["--project", "--commit", "--environment"]);
+    const projectId = options["--project"];
+    const commitSha = options["--commit"];
+    if (projectId === undefined || commitSha === undefined) throw new InvalidCommandError();
     return {
       kind: "plan",
-      projectId: options["--project"],
-      commitSha: options["--commit"],
+      projectId,
+      commitSha,
+      environment: deploymentEnvironment(options["--environment"]),
       credentialStore,
     };
   }
   if (first === "deploy") {
     if (!yes || follow || stdin) throw new InvalidCommandError();
-    const options = parseOptions(values, ["--project", "--plan-id", "--idempotency-key"]);
+    const options = parseOptionalOptions(values, [
+      "--project",
+      "--plan-id",
+      "--commit",
+      "--environment",
+      "--idempotency-key",
+    ]);
+    const projectId = options["--project"];
+    const idempotencyKey = options["--idempotency-key"];
+    const planId = options["--plan-id"] ?? null;
+    const commitSha = options["--commit"] ?? null;
+    // A plan already names its environment, so --environment only accompanies --commit.
+    if (
+      projectId === undefined ||
+      idempotencyKey === undefined ||
+      (planId === null) === (commitSha === null) ||
+      (planId !== null && options["--environment"] !== undefined)
+    )
+      throw new InvalidCommandError();
     return {
       kind: "deploy",
-      projectId: options["--project"],
-      planId: options["--plan-id"],
-      idempotencyKey: options["--idempotency-key"],
+      projectId,
+      planId,
+      commitSha,
+      environment: deploymentEnvironment(options["--environment"]),
+      idempotencyKey,
       yes,
       wait,
       credentialStore,
@@ -1752,10 +1882,12 @@ export const parseProductCliCommand = (argv: readonly string[]): ProductCliComma
     throw new InvalidCommandError();
   }
   if (first === "mail") {
-    if (yes || wait || follow || stdin) throw new InvalidCommandError();
     const area = values.shift();
     const sub =
       area === "webhook" || area === "messages" || area === "domain" ? values.shift() : undefined;
+    // Only retiring the mail domain is destructive, and it requires --yes.
+    const retiring = area === "domain" && sub === "delete";
+    if (yes !== retiring || wait || follow || stdin) throw new InvalidCommandError();
     const options = parseOptionalOptions(values, [
       "--project",
       "--environment",
@@ -1792,6 +1924,13 @@ export const parseProductCliCommand = (argv: readonly string[]): ProductCliComma
     } else if (area === "status" || (area === "domain" && sub === "status")) {
       request = { ...scope, action: "status" };
       label = area === "domain" ? "mail domain status" : "mail status";
+    } else if (retiring) {
+      request = {
+        ...scope,
+        action: "domain_delete",
+        idempotencyKey: required("--idempotency-key"),
+      };
+      label = "mail domain delete";
     } else if (area === "webhook" && sub === "set") {
       request = {
         ...scope,
@@ -1857,6 +1996,12 @@ const parseOptions = <T extends string>(
   return result;
 };
 
+const deploymentEnvironment = (value: string | undefined): "dev" | "prod" => {
+  if (value === undefined || value === "dev") return "dev";
+  if (value === "prod") return "prod";
+  throw new InvalidCommandError();
+};
+
 const parseOptionalOptions = <T extends string>(
   values: readonly string[],
   allowed: readonly T[],