ninepm 0.87.0 → 0.92.0

package/dist/index.js

@@ -16,7 +16,7 @@ import { managedHostnamesIn, siblingCallWarning, siblingsOf } from "./sibling-ho
 import { MAX_STATIC_ASSET_FILE_BYTES, MAX_WORKER_ENTRY_COMPRESSED_BYTES, MAX_WORKER_SCRIPT_COMPRESSED_BYTES, WORKER_ENTRY_COMPRESSED_WARN_BYTES, assetFileTooLargeMessage, formatMebibytes, formatMegabytes, oversizedAssets, workerBundleNearLimitMessage, workerBundleTooLargeMessage, workerEntryNearLimitMessage, workerEntryTooLargeMessage, } from "./deploy-limits.js";
 import { guessZoneApex, relativeRecordName, zoneApexFor } from "./dns-host.js";
 import { dnsProviderProfile, parkingRecordFor, recordAtProvider } from "./dns-providers.js";
-import { cacheMinutes, deriveDomainStatus, domainRecordStatuses, showsUseWww, } from "./domain-state.js";
+import { cacheMinutes, deriveDomainStatus, domainRecordStatuses, showsAuthoritativeAnswer, showsUseWww, } from "./domain-state.js";
 import { buildFileManifest, readManifestFile } from "./manifest.js";
 import { NO_PUBLIC_ASSETS, normalizeAssetsDirectory, privateLookingPaths, publicAssetPath } from "./public-assets.js";
 import { API_KEY_HELP, API_URL_HELP, CLI_CLIENT_ID, DEFAULT_API_URL, reportCliError } from "./cli-config.js";
@@ -90,7 +90,7 @@ export function deletedDomainLines(deleted, options = {}) {
     }
     return lines;
 }
-export const CLI_VERSION = "0.87.0";
+export const CLI_VERSION = "0.92.0";
 const PUBLIC_DASHBOARD_URL = "https://9pm.ai/dashboard";
 const TOKEN_SERVICE = "9pm";
 const TOKEN_ACCOUNT = "default";
@@ -265,8 +265,8 @@ export class DeployError extends Error {
     // DeployError, which would otherwise erase the distinction before the command
     // that needs it ever sees the error.
     deliberate;
-    constructor(message, slug, deliberate = false) {
-        super(message);
+    constructor(message, slug, deliberate = false, cause) {
+        super(message, cause === undefined ? undefined : { cause });
         this.name = "DeployError";
         this.slug = slug;
         this.deliberate = deliberate;
@@ -360,7 +360,7 @@ export async function deployDirectory(initialOptions) {
         }
         if (error instanceof DeployError)
             throw error;
-        throw new DeployError(error instanceof Error ? error.message : String(error), slugHolder.slug, isDeliberateRefusal(error));
+        throw new DeployError(error instanceof Error ? error.message : String(error), slugHolder.slug, isDeliberateRefusal(error), error);
     }
 }
 // Cheap unauthenticated probe of the control-plane API before a deploy. The
@@ -961,8 +961,19 @@ export async function whoami(options) {
     return apiRequest(options, "/v1/me", { method: "GET" });
 }
 export function publicWhoamiResult(result) {
+    if (result.restricted === true) {
+        return {
+            user: result.user,
+            restricted: true,
+            preset: result.apiKey?.preset ?? "unknown",
+            ...(result.apiKey?.prefix ? { apiKey: { prefix: result.apiKey.prefix } } : {}),
+            account: { credentialExpiresAt: result.account?.tokenExpiresAt ?? result.apiKey?.expiresAt ?? null },
+        };
+    }
     return {
         user: result.user,
+        restricted: false,
+        preset: "full",
         account: {
             ...(result.account?.org ? { org: result.account.org } : {}),
             ...(result.account?.plan ? { plan: result.account.plan } : {}),
@@ -972,10 +983,31 @@ export function publicWhoamiResult(result) {
             ...(typeof result.account?.storageQuotaBytes === "number" ? { storageQuotaBytes: result.account.storageQuotaBytes } : {}),
             ...(typeof result.account?.fileStorageUsedBytes === "number" ? { fileStorageUsedBytes: result.account.fileStorageUsedBytes } : {}),
             ...(typeof result.account?.fileStorageQuotaBytes === "number" ? { fileStorageQuotaBytes: result.account.fileStorageQuotaBytes } : {}),
-            credentialExpiresAt: result.account?.tokenExpiresAt ?? result.apiKey.expiresAt ?? null,
+            credentialExpiresAt: result.account?.tokenExpiresAt ?? result.apiKey?.expiresAt ?? null,
         },
     };
 }
+function credentialExpiryLine(me) {
+    return `Credential: ${me.account?.credentialExpiresAt ? `expires ${me.account.credentialExpiresAt}` : "active"}`;
+}
+// A scoped key is not shown the account's plan or usage, so it gets its own identity
+// lines instead of "Plan: unknown" and an empty storage meter.
+function scopedIdentityLine(me) {
+    return `Key: scoped API key ${me.apiKey?.prefix ? `${me.apiKey.prefix}... ` : ""}(${me.preset ?? "unknown"} preset)`;
+}
+export const SCOPED_WHOAMI_NOTE = "Plan, apps and storage are shown to a full-access login only.";
+export function whoamiLines(me) {
+    if (me.restricted) {
+        return [`User: ${me.user.email}`, scopedIdentityLine(me), credentialExpiryLine(me), SCOPED_WHOAMI_NOTE];
+    }
+    return [
+        `User: ${me.user.email}`,
+        `Plan: ${me.account?.plan ?? "unknown"}`,
+        `Sites: ${me.account?.sitesUsed ?? "unknown"} / ${me.account?.sitesQuota ?? "unknown"}`,
+        `Storage: ${formatBytesForCli(me.account?.storageUsedBytes ?? me.account?.fileStorageUsedBytes ?? 0)} / ${formatBytesForCli(me.account?.storageQuotaBytes ?? me.account?.fileStorageQuotaBytes ?? 0)}`,
+        credentialExpiryLine(me),
+    ];
+}
 // How long each revocation request may take before logout gives up and reports
 // the honest failure instead of hanging (a black-holed connection accepts TCP
 // and never answers). Longer than the 5s reachability probe because this
@@ -1112,6 +1144,12 @@ async function responseErrorCode(response) {
         return "";
     }
 }
+export function doctorAccountLines(account) {
+    if (account.restricted) {
+        return [`Account: ${account.user.email}`, scopedIdentityLine(account), credentialExpiryLine(account)];
+    }
+    return [`Account: ${account.user.email}`, `Plan: ${account.account?.plan ?? "unknown"}`];
+}
 async function doctor(options) {
     const credentials = credentialDiagnostics();
     const token = process.env.NINEPM_API_KEY ?? readStoredCredential();
@@ -1153,8 +1191,8 @@ async function doctor(options) {
         console.log(`Warning: ${warning}`);
     }
     if (account) {
-        console.log(`Account: ${account.user.email}`);
-        console.log(`Plan: ${account.account?.plan ?? "unknown"}`);
+        for (const line of doctorAccountLines(account))
+            console.log(line);
     }
     else if (accountError) {
         console.log(`Account: unavailable (${accountError})`);
@@ -1453,28 +1491,47 @@ export function deleteWarningLines(slug) {
         "Its deployments, files and managed database (if it has one) are deleted with it and cannot be recovered.",
     ];
 }
-// Printed after a delete of the one shape that was measured (#1969): an app whose namespace
-// script was replaced with the deleted-app Worker, with no container and no custom domain.
-// Measured from outside on 2026-10-14 (staging) and 2026-10-15 (production) for a static
-// app: the old content stopped within ~20 s of starting the delete and did not come back
-// over ~15 min. "About a minute" leaves margin for a single location's measurement;
-// re-measure before tightening it, and measure a shape before adding it below.
+// Printed after a delete of a shape that was measured, and only those (#1969, #2120):
+// - a static app whose namespace script was replaced with the deleted-app Worker, with no
+//   container and no custom domain: old content stopped within ~20 s of starting the delete
+//   on 2026-10-14/15 (staging/production, from MAD), and within ~10 s on 2026-10-21 from
+//   outside Madrid (staging and production, answered by ZRH, CDG, CPH, MRS, DUS, TXL, DUB);
+// - a Cloudflare-placed container app published into the namespace, whose namespace script
+//   was deleted (no tombstone - its Durable Object class forbids one) and whose container
+//   application teardown was queued: old content stopped within ~13 s and ~12 s on two runs on
+//   2026-10-22 (staging), and did not come back over 30 and 20 min while the queue ran.
+// Every run watched for 15 min or more afterwards. "About a minute" leaves margin; re-measure
+// before tightening it, and measure a shape before adding it below.
 export const DELETE_SERVING_BOUND_LINE = "Its address stops serving the app within about a minute.";
 // Whether DELETE_SERVING_BOUND_LINE is true of this delete. Read from what the server says it
-// did, not from what the app was: the tombstone is the mechanism the measurement covers. A
-// container app's teardown is queued and gets no tombstone, a custom domain stops through the
-// fallback Worker, and a failed cleanup step may have left something serving - none of those
-// were measured, so they get no promise. An older server sends no `workerScripts`, so neither.
+// did, not from what the app was, because the mechanisms are what the measurements cover: a
+// tombstoned namespace script for a static app, and a deleted namespace script for a
+// Cloudflare container. An untombstoned static app is NOT covered - #1969 saw such a script
+// keep serving for 45 min - which is why the untombstoned branch needs a queued container
+// teardown. Unmeasured, so promised nothing: a container on the legacy path (an account-level
+// script that was actually there to remove), a Fly container, a custom domain (it stops through
+// the fallback Worker), and any failed or skipped cleanup step. An older server sends no
+// `workerScripts`, so neither.
 export function deletedAppStopsServingQuickly(deleted) {
-    const scripts = Array.isArray(deleted.workerScripts) ? deleted.workerScripts : [];
-    const tombstoned = scripts.some((script) => typeof script === "object" && script !== null && script.tombstoned === true);
+    const scripts = (Array.isArray(deleted.workerScripts) ? deleted.workerScripts : []).map((script) => typeof script === "object" && script !== null
+        ? script
+        : {});
     const releasing = Array.isArray(deleted.customDomainsReleasing) && deleted.customDomainsReleasing.length > 0;
-    return (tombstoned &&
-        (deleted.containerApplications ?? 0) === 0 &&
-        (deleted.flyTeardownsQueued ?? 0) === 0 &&
+    const nothingUnmeasured = (deleted.flyTeardownsQueued ?? 0) === 0 &&
         deleted.customDomains === 0 &&
         !releasing &&
-        (deleted.errors ?? []).length === 0);
+        (deleted.errors ?? []).length === 0;
+    if (!nothingUnmeasured) {
+        return false;
+    }
+    const containers = deleted.containerApplications ?? 0;
+    if (containers === 0) {
+        return scripts.some((script) => script.tombstoned === true);
+    }
+    const inNamespace = (script) => typeof script.dispatchNamespace === "string" && script.dispatchNamespace !== "";
+    return (scripts.some((script) => inNamespace(script) && script.outcome === "removed") &&
+        scripts.every((script) => script.outcome === "removed" || script.outcome === "absent") &&
+        !scripts.some((script) => !inNamespace(script) && script.outcome === "removed"));
 }
 export async function deleteSite(options) {
     const route = `/v1/sites/${encodeURIComponent(options.site)}${options.owner ? `?owner=${encodeURIComponent(options.owner)}` : ""}`;
@@ -1812,7 +1869,7 @@ export async function retireReplacedCredentials(before, after, newToken, fetchFn
 /** The lines a login prints about what it retired, for stderr. Silent when nothing needs saying. */
 export function replacedCredentialMessages(result, loginApiUrl) {
     const lines = [];
-    const manual = "revoke it from Settings > API keys in the dashboard, or it stays valid until 90 days pass without use.";
+    const manual = "log it out from Settings > CLI logins in the dashboard, or it stays valid until 90 days pass without use.";
     for (const outcome of result.replaced) {
         if (outcome.kind === "revoked") {
             const elsewhere = outcome.apiUrl !== normalizeApiUrl(loginApiUrl) ? ` (issued by ${outcome.apiUrl})` : "";
@@ -2523,7 +2580,27 @@ async function expectOk(response, action) {
     if (code && message && DELIBERATE_REFUSAL_CODES.has(code)) {
         throw new DeliberateRefusalError(message, code);
     }
-    throw new Error(`Failed to ${action}: ${response.status} ${text}`);
+    throw new ApiResponseError(`Failed to ${action}: ${response.status} ${text}`, response.status, code || null, message || null, envelope?.details);
+}
+/**
+ * A non-2xx answer from the control plane, with the parts of its envelope a caller may
+ * act on. The message keeps the raw form expectOk always printed; `serverMessage` is the
+ * sentence the server wrote, for commands that print that alone.
+ */
+export class ApiResponseError extends Error {
+    status;
+    code;
+    serverMessage;
+    details;
+    constructor(message, status, code, serverMessage, details) {
+        // No `name` of its own: anything that renders an error as `String(error)` keeps
+        // reading "Error: Failed to ..." exactly as before this class existed.
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.serverMessage = serverMessage;
+        this.details = details;
+    }
 }
 // Takes the already-consumed body text rather than the Response: a body can only
 // be read once, and expectOk needs the code and the message from the same read.
@@ -2781,6 +2858,9 @@ export function parseArgs(argv) {
     if (command === "api-key" || command === "api-keys") {
         return parseApiKeyArgs(argv.slice(1));
     }
+    if (command === "automation" || command === "automations") {
+        return parseAutomationArgs(argv.slice(1));
+    }
     if (command !== "deploy") {
         throw new Error(`Unknown command: ${command}`);
     }
@@ -3339,9 +3419,11 @@ function isRemoving(domain) {
 }
 const DOMAIN_STATE_LABELS = {
     live: "live",
+    ready_to_switch: "ready to switch: the platform can serve it, but its DNS still points elsewhere",
     waiting_for_dns: "waiting for DNS records",
     dns_unverified: "couldn't check the DNS records just now",
     issuing_certificate: "DNS records found, waiting for the platform to issue the certificate",
+    points_elsewhere: "points elsewhere: its DNS now leads to another host",
     failed: "failed",
     expired: "expired",
 };
@@ -3461,6 +3543,24 @@ function recordStateText(record, routing, parking = null) {
     const also = others.map((answer) => `; ${answer.resolver} answers ${answerText(answer.current)}`).join("");
     return `currently ${shown}${also}${recent}: point it at the value shown${parkingText(parking)}`;
 }
+// #2241: what the DNS host's own nameserver answered, beside the resolvers' state and never in
+// place of it: the state text above is unchanged whatever this says. A failed read is "unable to
+// verify", never "nothing published".
+export function authoritativeText(record) {
+    if (!showsAuthoritativeAnswer(record))
+        return null;
+    const direct = record.authoritative;
+    if (direct.outcome !== "answered")
+        return "your DNS host: unable to verify directly";
+    const from = ` (read directly from ${direct.nameserver})`;
+    if (direct.matches)
+        return `your DNS host already publishes the value shown${from}; the public resolvers have not caught up yet, so check again later`;
+    return `your DNS host publishes ${answerText(direct.current ?? [])}${from}`;
+}
+function withAuthoritativeText(record, state) {
+    const direct = authoritativeText(record);
+    return direct ? `${state}. ${direct.charAt(0).toUpperCase()}${direct.slice(1)}` : state;
+}
 // Said only when the check saw the host's documented parking value (parkingRecordFor), and
 // conditionally even then: the record may have been changed since the check.
 function parkingText(parking) {
@@ -3537,6 +3637,12 @@ export function formatDomainStatus(status, options = {}) {
         lines.push(`Add it again: ${domainCommand("add", status.app, status.hostname, options)}`);
         return lines;
     }
+    if (status.state === "ready_to_switch" || status.state === "points_elsewhere") {
+        return [...lines, ...domainMoveLines(status, options)];
+    }
+    if (status.state === "failed" && status.reason?.code === "moved_needs_restart") {
+        return [...lines, ...movedRestartLines(status, options)];
+    }
     if (status.state === "failed" && status.error) {
         lines.push(status.error);
     }
@@ -3573,7 +3679,7 @@ export function formatDomainStatus(status, options = {}) {
                     record.apex && !profile && record.typeAtProvider === "ALIAS" ? "ALIAS / ANAME" : (record.typeAtProvider ?? "-"),
                     record.nameAtProvider === "" ? "(leave empty)" : record.nameAtProvider,
                     record.valueAtProvider,
-                    recordStateText(record, status.routing, profile ? parkingRecordFor(status.providerId, record) : null),
+                    withAuthoritativeText(record, recordStateText(record, status.routing, profile ? parkingRecordFor(status.providerId, record) : null)),
                 ]),
             ];
             lines.push(...renderColumns(rows).map((line) => `  ${line}`));
@@ -3642,10 +3748,63 @@ export function formatDomainStatus(status, options = {}) {
     lines.push(`Then run: ${domainCommand("wait", status.app, status.hostname, options)}`);
     return lines;
 }
+// The two ends of a move between hosts (#2238). Only the routing record is named: every other
+// record was what got routing and the certificate this far, and is not what is in the way.
+function domainMoveLines(status, options) {
+    const routing = status.records.find((record) => !record.optional && record.type !== "TXT" && record.check === "different");
+    const name = routing ? (routing.nameAtProvider === "" ? "the root" : (routing.nameAtProvider ?? routing.name)) : status.hostname;
+    const type = routing ? (routing.typeAtProvider ?? routing.type) : "CNAME";
+    const value = routing ? routing.valueAtProvider : null;
+    const leadsTo = routing?.elsewhere ?? routing?.current?.join(", ") ?? null;
+    const at = status.provider ? ` at ${status.provider}` : " at your DNS host";
+    if (status.state === "ready_to_switch") {
+        const lines = [
+            `The platform is ready to serve ${status.hostname}: routing and the certificate are active. But visitors still reach another host, because the ${type} record ${name}${leadsTo ? ` leads to ${leadsTo}` : " points elsewhere"}.`,
+        ];
+        if (value)
+            lines.push(`To serve it from here, change ${type} ${name} to ${value}${at}.`);
+        if (typeof routing?.ttlSeconds === "number") {
+            lines.push(`Public caches may keep sending visitors to the other host${forUpTo(routing.ttlSeconds)} after you change it.`);
+        }
+        lines.push(`Then run: ${domainCommand("wait", status.app, status.hostname, options)}`);
+        return lines;
+    }
+    const lines = [
+        `${status.hostname} now points elsewhere${leadsTo ? `: the ${type} record ${name} leads to ${leadsTo}` : ""}, so the platform has stopped serving it here.`,
+        `If you moved it to another host on purpose, remove it here once visitors reach the new host: ${domainCommand("remove", status.app, status.hostname, options)}`,
+    ];
+    // Pointing the record back is not enough on its own: Cloudflare keeps a moved hostname moved
+    // until its validation is restarted, which is what `restart` sends (a PATCH of the hostname).
+    // A Re-check only reads it again, so it is not offered here.
+    if (value) {
+        lines.push(`If you didn't mean to move it: change ${type} ${name} back to ${value}${at}, then start validation over: ${domainCommand("restart", status.app, status.hostname, options)}`);
+        lines.push(`That may print new TXT values: publish them as shown, then run: ${domainCommand("wait", status.app, status.hostname, options)}. The provider deletes a hostname that stays moved for 7 days.`);
+    }
+    return lines;
+}
+// A hostname the provider reports moved whose DNS no longer provably leads elsewhere (#2238):
+// pointed back, or not readable. Cloudflare keeps it moved until a restart's PATCH, so the restart
+// is the step, and a Re-check (a read) is not offered.
+function movedRestartLines(status, options) {
+    const routing = status.records.find((record) => !record.optional && record.type !== "TXT");
+    const name = routing ? (routing.nameAtProvider === "" ? "the root" : (routing.nameAtProvider ?? routing.name)) : status.hostname;
+    const type = routing ? (routing.typeAtProvider ?? routing.type) : "CNAME";
+    const first = routing?.ok === true
+        ? `${status.hostname}'s DNS points back at the platform, but the provider still has it disconnected after the move. Restart validation to reconnect it:`
+        : `The provider stopped routing ${status.hostname} because its DNS moved away. Make sure ${type} ${name} points to ${routing?.valueAtProvider ?? "the value shown"}, then restart validation to reconnect it:`;
+    return [
+        first,
+        `  ${domainCommand("restart", status.app, status.hostname, options)}`,
+        `That may print new TXT values: publish them as shown, then run: ${domainCommand("wait", status.app, status.hostname, options)}. The provider deletes a hostname that stays moved for 7 days.`,
+    ];
+}
 // What a timed-out wait says. "Missing" is claimed only for a record the check actually saw
 // absent or different; a record nobody could read is reported as unchecked, whatever the
 // routing status, because telling the owner to publish what may already be there misleads.
 export function domainWaitTimeoutMessage(status) {
+    if (status.state === "ready_to_switch") {
+        return "Timed out: the platform is ready, but the routing record above still leads to another host. Change it as shown above, then wait again.";
+    }
     if (status.next?.action === "use_www") {
         return `Stopped waiting: no record at the root can finish ${status.hostname} at its DNS host. Connect ${status.next.hostname ?? `www.${status.hostname}`} as shown above, then wait on that instead.`;
     }
@@ -3902,7 +4061,7 @@ export function domainRemovedConsequenceLines(hostnames, options = {}) {
     const subject = hostnames.length === 1 ? hostnames[0] : hostnames.join(", ");
     return [
         `After removal, visitors may see a TLS or routing error while DNS for ${subject} still points at 9pm.`,
-        `Moving a domain to another host? Point its DNS at the new host, wait for the DNS TTL to pass, then remove the domain from 9pm. While caches update, some visitors may still reach 9pm, or briefly see an error from the new host until it is set up for the name. Once DNS points away, 9pm may show the domain as failed; that is expected, so remove it. Guide: ${customDomainMoveOffGuideUrl(options)}`,
+        `Moving a domain to another host? Point its DNS at the new host, wait for the DNS TTL to pass, then remove the domain from 9pm. While caches update, some visitors may still reach 9pm, or briefly see an error from the new host until it is set up for the name. Once DNS points away, 9pm shows the domain as pointing elsewhere (or, before an update, as failed); that is expected, so remove it. Guide: ${customDomainMoveOffGuideUrl(options)}`,
     ];
 }
 // The command that lists what a removal finished in the background frees (#2068), aimed at the
@@ -4193,7 +4352,7 @@ export function deployCustomDomainLines(statuses, slug, owner, target) {
             return `Custom domain ${status.hostname} is being removed.`;
         if (status.state === "live")
             return `Also serving at https://${status.hostname}`;
-        const notLive = status.state === "failed" || status.state === "expired" ? "is not live" : "is not live yet";
+        const notLive = status.state === "failed" || status.state === "expired" || status.state === "points_elsewhere" ? "is not live" : "is not live yet";
         return `Custom domain ${status.hostname} ${notLive} (${domainStateLabel(status.state)}). Check it: ${domainCommand("status", slug, status.hostname, { ...(owner ? { owner } : {}), ...(target ? { target } : {}) })}`;
     });
 }
@@ -4220,6 +4379,9 @@ export async function waitForDomain(options) {
             // Nothing the owner can publish finishes this hostname, so polling until the timeout would only delay saying so.
             if (status.next?.action === "use_www")
                 return { status, exitCode: DOMAIN_WAIT_EXIT.ownerAction, timedOut: false };
+            // Its DNS leads to another host (#2238): the owner decides whether to remove it or point it back.
+            if (status.state === "points_elsewhere")
+                return { status, exitCode: DOMAIN_WAIT_EXIT.ownerAction, timedOut: false };
         }
         catch (error) {
             const transient = !(error instanceof DomainsApiError) || error.status >= 500;
@@ -4985,29 +5147,173 @@ function readBaseApiOptions(flags) {
 function readApiToken(flags) {
     return readStringFlag(flags, "token") ?? process.env.NINEPM_API_KEY ?? readStoredCredential();
 }
+const API_KEY_PRESETS = ["monitor", "deploy", "provision", "full"];
+function isHelpToken(value) {
+    return value === "help" || value === "--help" || value === "-h";
+}
+// Refuses here only what has one reading whatever the account holds: a preset that does
+// not exist, a scope flag the chosen preset cannot carry, an expiry that is not a date.
+// Whether the apps or the automation exist, and whether provision keys are issued yet,
+// is the server's to answer, and its message is printed as it is.
+function parseApiKeyCreate(argv, flags) {
+    const json = flags.has("json");
+    const name = readStringFlag(flags, "name");
+    const presetFlag = flags.get("preset");
+    if (presetFlag === true) {
+        throw new Error(`Missing --preset value. Use one of: ${API_KEY_PRESETS.join(", ")}.`);
+    }
+    if (typeof presetFlag === "string" && !API_KEY_PRESETS.includes(presetFlag)) {
+        throw new Error(`Unknown preset "${presetFlag}". Use one of: ${API_KEY_PRESETS.join(", ")}.`);
+    }
+    const preset = presetFlag;
+    if (flags.get("project") === true) {
+        throw new Error("Missing --project value. Name an app by its slug or id.");
+    }
+    if (flags.get("automation") === true) {
+        throw new Error("Missing --automation value. Name the automation by its id (9pm automation ls).");
+    }
+    const projects = readRepeatedStringFlag(argv, "project");
+    const automation = readStringFlag(flags, "automation");
+    if (projects.length > 0 && preset !== "monitor" && preset !== "deploy") {
+        throw new Error(preset === "provision"
+            ? "A provision key reaches the apps of one automation: pass --automation <id>, not --project."
+            : "--project belongs to a scoped key: add --preset monitor or --preset deploy. A full-access key reaches every app.");
+    }
+    if (automation && preset !== "provision") {
+        throw new Error(preset === "monitor" || preset === "deploy"
+            ? `A ${preset} key lists its apps with --project, not an automation. Use --preset provision for an automation.`
+            : "--automation belongs to a provision key: add --preset provision. A full-access key reaches every app.");
+    }
+    const expiresFlag = flags.get("expires");
+    if (expiresFlag === true) {
+        throw new Error(`Missing --expires value. ${API_KEY_EXPIRES_FORMS}`);
+    }
+    if (typeof expiresFlag === "string") {
+        resolveApiKeyExpiry(expiresFlag, new Date());
+    }
+    return {
+        kind: "create",
+        ...(name ? { name } : {}),
+        ...(preset ? { preset } : {}),
+        projects,
+        ...(automation ? { automation } : {}),
+        ...(typeof expiresFlag === "string" ? { expires: expiresFlag } : {}),
+        json,
+    };
+}
+// A full date-time with its zone. A bare date or a zoneless time is refused rather than
+// read in some default zone, so the deadline is the one the person meant.
+const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})$/;
+export const API_KEY_EXPIRES_FORMS = "Use an ISO 8601 date-time with its zone, such as 2026-12-31T00:00:00Z, or a relative <N>d or <N>h, such as 30d or 12h (N a positive integer).";
+/**
+ * `--expires` as the ISO instant the server takes: an ISO 8601 date-time as given, or
+ * `<N>d` / `<N>h` counted from `now`. How far ahead is allowed is the server's rule (a
+ * year today), so only the shape is checked here.
+ */
+export function resolveApiKeyExpiry(value, now) {
+    const relative = /^(\d+)([dh])$/.exec(value);
+    if (relative) {
+        const count = Number(relative[1]);
+        if (!Number.isSafeInteger(count) || count < 1) {
+            throw new Error(`--expires ${value} is not a positive duration. ${API_KEY_EXPIRES_FORMS}`);
+        }
+        const unitMs = relative[2] === "d" ? 24 * 60 * 60 * 1000 : 60 * 60 * 1000;
+        return new Date(now.getTime() + count * unitMs).toISOString();
+    }
+    const at = ISO_DATE_TIME.test(value) ? Date.parse(value) : Number.NaN;
+    if (!Number.isFinite(at)) {
+        throw new Error(`--expires ${value} is not an expiry this CLI reads. ${API_KEY_EXPIRES_FORMS}`);
+    }
+    return new Date(at).toISOString();
+}
 function parseApiKeyArgs(argv) {
     const subcommand = argv[0];
-    if (!subcommand || subcommand === "help" || subcommand === "--help") {
-        throw new UsageError();
+    if (!subcommand || isHelpToken(subcommand) || isHelpToken(argv[1])) {
+        throw new UsageError("api-key");
     }
     const flags = parseFlags(argv);
-    const base = readBaseApiOptions(flags);
     const json = flags.has("json");
     if (subcommand === "create") {
-        const name = readStringFlag(flags, "name");
-        return { kind: "api-key", ...base, action: { kind: "create", ...(name ? { name } : {}), json } };
+        const action = parseApiKeyCreate(argv, flags);
+        return { kind: "api-key", ...readBaseApiOptions(flags), action };
     }
     if (subcommand === "ls" || subcommand === "list") {
-        return { kind: "api-key", ...base, action: { kind: "ls", json } };
+        return { kind: "api-key", ...readBaseApiOptions(flags), action: { kind: "ls", json } };
     }
     if (subcommand === "revoke") {
         const keyId = argv[1];
         if (!keyId || keyId.startsWith("--")) {
             throw new Error("Usage: 9pm api-key revoke <key-id>");
         }
-        return { kind: "api-key", ...base, action: { kind: "revoke", keyId } };
+        return { kind: "api-key", ...readBaseApiOptions(flags), action: { kind: "revoke", keyId } };
+    }
+    throw new Error(`Unknown api-key subcommand: ${subcommand}. Run 9pm api-key --help.`);
+}
+// Positional arguments after the subcommand, skipping every --flag and the value it takes.
+function positionalArgs(argv, booleanFlags) {
+    const values = [];
+    for (let index = 1; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === undefined)
+            continue;
+        if (arg.startsWith("--")) {
+            const next = argv[index + 1];
+            if (!booleanFlags.includes(arg.slice(2)) && next !== undefined && !next.startsWith("--"))
+                index += 1;
+            continue;
+        }
+        values.push(arg);
     }
-    throw new Error(`Unknown api-key subcommand: ${subcommand}`);
+    return values;
+}
+export const AUTOMATION_RM_WARNING = "Deleting an automation revokes every API key minted for it at once. Its apps stay in your account as ordinary apps, unchanged.";
+function parseAutomationArgs(argv) {
+    const subcommand = argv[0];
+    if (!subcommand || isHelpToken(subcommand) || isHelpToken(argv[1])) {
+        throw new UsageError("automation");
+    }
+    const flags = parseFlags(argv);
+    const json = flags.has("json");
+    const args = positionalArgs(argv, ["json", "yes"]);
+    const need = (count, usage) => {
+        if (args.length < count)
+            throw new Error(`Usage: 9pm automation ${usage}`);
+        return args;
+    };
+    const command = (action) => ({
+        kind: "automation",
+        ...readBaseApiOptions(flags),
+        action,
+    });
+    if (subcommand === "create") {
+        const [name] = need(1, "create <name>");
+        return command({ kind: "create", name: name, json });
+    }
+    if (subcommand === "ls" || subcommand === "list") {
+        return command({ kind: "ls", json });
+    }
+    if (subcommand === "rename") {
+        const [automationId, name] = need(2, "rename <automation-id> <new-name>");
+        return command({ kind: "rename", automationId: automationId, name: name, json });
+    }
+    if (subcommand === "rm" || subcommand === "delete") {
+        const [automationId] = need(1, "rm <automation-id> --yes");
+        // Like `9pm delete --confirm`, the consent is a flag rather than a prompt: agents run
+        // this non-interactively, and a prompt they cannot answer would hang them.
+        if (!flags.has("yes")) {
+            throw new Error(`${AUTOMATION_RM_WARNING}\nRe-run with --yes to delete it: 9pm automation rm ${quoteSiteArg(automationId)} --yes`);
+        }
+        return command({ kind: "rm", automationId: automationId, json });
+    }
+    if (subcommand === "attach" || subcommand === "detach") {
+        const [automationId, app] = need(2, `${subcommand} <automation-id> <app>`);
+        return command({ kind: subcommand, automationId: automationId, app: app, json });
+    }
+    if (subcommand === "apps") {
+        const [automationId] = need(1, "apps <automation-id>");
+        return command({ kind: "apps", automationId: automationId, json });
+    }
+    throw new Error(`Unknown automation subcommand: ${subcommand}. Run 9pm automation --help.`);
 }
 function parseSupportArgs(argv) {
     // Normalize the -m short flag so parseFlags (which only handles --flags) sees it.
@@ -6039,6 +6345,11 @@ function formatRemainingForCli(value) {
     return `${Math.floor(totalSeconds / 60)}m ${totalSeconds % 60}s`;
 }
 export class UsageError extends Error {
+    topic;
+    constructor(topic) {
+        super();
+        this.topic = topic;
+    }
 }
 // #1856: which missing-pages mode the deployment was published with, read from the
 // deployment the platform returned rather than from the flags, because a deploy without a
@@ -6056,9 +6367,23 @@ export function missingPagesLine(deployment) {
             return null;
     }
 }
+// The credential and control plane a parsed command talks to, for the guidance printed
+// under its error. Undefined for commands that carry no token of their own.
+function commandCredential(command) {
+    if (!command)
+        return {};
+    if (command.kind === "deploy")
+        return { token: command.options.token, apiUrl: command.options.apiUrl };
+    if ("token" in command && typeof command.token === "string") {
+        return { token: command.token, ...("apiUrl" in command && typeof command.apiUrl === "string" ? { apiUrl: command.apiUrl } : {}) };
+    }
+    return {};
+}
 async function main() {
+    let parsed;
     try {
         const command = parseArgs(process.argv.slice(2));
+        parsed = command;
         if (command.kind === "version") {
             console.log(CLI_VERSION);
             return;
@@ -6127,7 +6452,7 @@ async function main() {
                 }
                 const slug = error instanceof DeployError ? error.slug : command.options.slug;
                 const siteFlag = slug ? ` --site ${quoteSiteArg(slug)}` : "";
-                throw new Error(`${base}\n\nStuck? Report it with context: 9pm support${siteFlag} -m "<what happened>"`);
+                throw new Error(`${base}\n\nStuck? Report it with context: 9pm support${siteFlag} -m "<what happened>"`, { cause: error });
             }
             const databaseClause = deployDatabaseClause(result.databases);
             const queued = result.deployment.status === "queued" || result.deployment.status === "publishing";
@@ -6284,7 +6609,7 @@ async function main() {
                 // path, where a pre-0.42 credential really was issued by the default
                 // plane and really is dead — but it cannot be called confirmed.
                 console.error(`Removed the local credential, but could not confirm it was revoked: ${summary.apiUrl} does not recognise it.`);
-                console.error("An older CLI stored it without recording which control plane issued it. If you used another control plane, revoke it under Connected devices there.");
+                console.error("An older CLI stored it without recording which control plane issued it. If you used another control plane, log it out under CLI logins in its dashboard settings.");
                 if (removalWarning) {
                     console.warn(removalWarning);
                 }
@@ -6312,8 +6637,8 @@ async function main() {
                 // it; a staging or self-hosted key cannot be revoked there, and a
                 // rejected URL leaves the origin unknown.
                 const settingsHint = !command.apiUrlError && targets.every((target) => target.apiUrl === DEFAULT_API_URL)
-                    ? `Revoke it under Connected devices: ${PUBLIC_DASHBOARD_URL}/settings`
-                    : "Revoke it under Connected devices in its control plane's dashboard settings.";
+                    ? `Log it out under CLI logins: ${PUBLIC_DASHBOARD_URL}/settings`
+                    : "Log it out under CLI logins in its control plane's dashboard settings.";
                 console.error(`It can still authenticate. ${settingsHint}`);
                 process.exitCode = 1;
             }
@@ -6333,11 +6658,8 @@ async function main() {
                 console.log(JSON.stringify(publicMe, null, 2));
             }
             else {
-                console.log(`User: ${publicMe.user.email}`);
-                console.log(`Plan: ${publicMe.account?.plan ?? "unknown"}`);
-                console.log(`Sites: ${publicMe.account?.sitesUsed ?? "unknown"} / ${publicMe.account?.sitesQuota ?? "unknown"}`);
-                console.log(`Storage: ${formatBytesForCli(publicMe.account?.storageUsedBytes ?? publicMe.account?.fileStorageUsedBytes ?? 0)} / ${formatBytesForCli(publicMe.account?.storageQuotaBytes ?? publicMe.account?.fileStorageQuotaBytes ?? 0)}`);
-                console.log(`Credential: ${publicMe.account?.credentialExpiresAt ? `expires ${publicMe.account.credentialExpiresAt}` : "active"}`);
+                for (const line of whoamiLines(publicMe))
+                    console.log(line);
             }
             return;
         }
@@ -6425,11 +6747,20 @@ async function main() {
             await runApiKeyCommand(command);
             return;
         }
+        if (command.kind === "automation") {
+            await runAutomationCommand(command);
+            return;
+        }
         await runAccessCommand(command);
     }
     catch (error) {
         if (error instanceof UsageError) {
-            printUsage();
+            if (error.topic) {
+                console.log(usageForTopic(error.topic));
+            }
+            else {
+                printUsage();
+            }
             process.exitCode = 0;
             return;
         }
@@ -6441,44 +6772,371 @@ async function main() {
             return;
         }
         reportCliError(error);
+        for (const line of scopedKeyGuidance(error, commandCredential(parsed))) {
+            console.error(line);
+        }
         process.exitCode = 1;
     }
 }
-async function runApiKeyCommand(command) {
-    const base = { apiUrl: command.apiUrl, token: command.token };
+// The new account commands print the server's own sentence on a refusal, not the raw
+// envelope: their refusals (a taken name, an app in another automation, provision keys
+// not issued yet) are written for the person and are the whole answer.
+async function accountRequest(options, route, init) {
+    try {
+        return await apiRequest(options, route, init);
+    }
+    catch (error) {
+        if (error instanceof ApiResponseError && error.serverMessage) {
+            throw new ApiResponseError(error.serverMessage, error.status, error.code, error.serverMessage, error.details);
+        }
+        throw error;
+    }
+}
+export function apiKeyPresetLabel(key) {
+    return key.scope ? key.scope.preset : "full";
+}
+function apiKeyReach(key) {
+    const scope = key.scope;
+    if (!scope)
+        return "all apps";
+    if (scope.automationId)
+        return `automation ${scope.automationId}`;
+    if (scope.projectIds && scope.projectIds.length > 0)
+        return `apps ${scope.projectIds.join(",")}`;
+    // A control plane from before key lists named a key's apps leaves them out; Settings shows them.
+    return "selected apps (see Settings)";
+}
+// The sooner of a key's two deadlines: a fixed expiry it was minted with, and the
+// sliding 90-days-without-use one.
+function apiKeyExpiryLabel(key) {
+    const fixed = key.expiresAt ? Date.parse(key.expiresAt) : Number.NaN;
+    const idle = key.inactivityExpiresAt ? Date.parse(key.inactivityExpiresAt) : Number.NaN;
+    if (Number.isFinite(fixed) && (!Number.isFinite(idle) || fixed <= idle))
+        return `expires ${key.expiresAt.slice(0, 10)}`;
+    if (Number.isFinite(idle))
+        return `lapses ${key.inactivityExpiresAt.slice(0, 10)} unless used`;
+    return "lapses after 90 days without use";
+}
+export function apiKeyListLine(key) {
+    return [
+        key.id,
+        key.name,
+        `${key.prefix}...`,
+        apiKeyPresetLabel(key),
+        apiKeyReach(key),
+        apiKeyExpiryLabel(key),
+        `created ${key.createdAt.slice(0, 10)}`,
+        `last used ${key.lastUsedAt ? key.lastUsedAt.slice(0, 10) : "never"}`,
+    ].join("\t");
+}
+export const DEPLOY_KEY_SECRETS_WARNING = "A key that can deploy to an app can replace its code, so it can read that app's secrets and data. Scoping protects your other apps, not the ones it may deploy to.";
+function apiKeyCreateBody(action, projectIds, now) {
+    return {
+        ...(action.name ? { name: action.name } : {}),
+        ...(action.preset ? { preset: action.preset } : {}),
+        ...(projectIds.length > 0 ? { projectIds } : {}),
+        ...(action.automation ? { automationId: action.automation } : {}),
+        ...(action.expires ? { expiresAt: resolveApiKeyExpiry(action.expires, now) } : {}),
+    };
+}
+/**
+ * The ids of the apps named by --project, each matched exactly by id or slug against the
+ * caller's own apps. The server also accepts slugs, but answers with ids, and the minted
+ * key can only be checked against what was asked for when both sides name apps the same
+ * way. A name that matches nothing stops here, before any key exists.
+ */
+async function resolveKeyProjectIds(base, projects) {
+    if (projects.length === 0)
+        return [];
+    const { projects: own } = await listSites(base);
+    return projects.map((name) => {
+        const match = own.find((project) => project.id === name || project.slug === name);
+        if (!match)
+            throw new Error(`No app of yours is called ${name}. Pass each --project as the slug or id that 9pm ls prints.`);
+        return match.id;
+    });
+}
+// What each preset grants, as the control plane defines it. Only used to check a minted key:
+// if a server ever widens a preset, its keys stop matching this and are refused, which errs
+// toward handing out nothing.
+const API_KEY_PRESET_PERMISSIONS = {
+    monitor: ["project.read"],
+    deploy: ["project.read", "deploy", "env.write", "database.create"],
+    provision: ["project.read", "project.create", "deploy", "env.write", "database.create"],
+};
+const sameSet = (a, b) => new Set(a).size === new Set(b).size && a.every((value) => b.includes(value));
+/**
+ * How a minted scoped key differs from the one asked for, or null when it is exactly that
+ * key: its preset, its permissions, its apps or automation, and its expiry. A field the
+ * answer leaves out counts as a difference, so a server that does not report one of them
+ * cannot hand over a key that might be broader than requested.
+ */
+export function scopedKeyMismatch(requested, created) {
+    const scope = created.scope;
+    if (!scope)
+        return "a full-access key";
+    if (scope.preset !== requested.preset)
+        return `a ${scope.preset} key`;
+    const expected = API_KEY_PRESET_PERMISSIONS[scope.preset];
+    if (!expected || !scope.permissions || !sameSet(scope.permissions, expected)) {
+        return `a ${scope.preset} key with permissions ${scope.permissions ? scope.permissions.join(",") || "(none)" : "(not reported)"}`;
+    }
+    if (requested.preset === "provision") {
+        if (scope.automationId !== requested.automationId)
+            return `a key for automation ${scope.automationId ?? "(none)"}`;
+        if (scope.projectIds && scope.projectIds.length > 0)
+            return `a key that also lists apps ${scope.projectIds.join(",")}`;
+    }
+    else {
+        if (scope.automationId)
+            return `a key for automation ${scope.automationId}`;
+        if (!scope.projectIds)
+            return "a key that does not say which apps it reaches";
+        if (!sameSet(scope.projectIds, requested.projectIds ?? []))
+            return `a key for apps ${scope.projectIds.join(",") || "(none)"}`;
+    }
+    const expiryMatches = requested.expiresAt
+        ? typeof created.expiresAt === "string" && Date.parse(created.expiresAt) === Date.parse(requested.expiresAt)
+        : created.expiresAt === null || created.expiresAt === undefined;
+    if (!expiryMatches)
+        return `a key expiring ${created.expiresAt ?? "never"}`;
+    return null;
+}
+/**
+ * A scoped key that is not exactly the one asked for - a full-access key from a control
+ * plane that predates scoped keys, or any field broader or missing - is revoked at once and
+ * its token never printed or emitted. Plain full-key creation is untouched: nothing was
+ * asked for that the answer could lack.
+ */
+async function refuseUnscopedKey(base, requested, created) {
+    if (!requested.preset || requested.preset === "full")
+        return;
+    const got = scopedKeyMismatch(requested, created);
+    if (!got)
+        return;
+    const unsupported = `This control plane did not create the key asked for: asked for a ${requested.preset} key, it answered with ${got} (${created.id}).`;
+    try {
+        await apiRequest(base, `/v1/me/api-keys/${encodeURIComponent(created.id)}/revoke`, { method: "POST" });
+    }
+    catch (error) {
+        const reason = error instanceof ApiResponseError && error.serverMessage ? error.serverMessage : error instanceof Error ? error.message : String(error);
+        throw new Error(`${unsupported} It could not be revoked (${reason}), and it still works: revoke key ${created.id} by hand with 9pm api-key revoke ${created.id}, or under API keys in Settings. Its token was not printed.`);
+    }
+    throw new Error(`${unsupported} That key was revoked and its token was not printed. No ${requested.preset} key was created.`);
+}
+export async function runApiKeyCommand(command, io = {}) {
+    const log = io.log ?? ((line) => console.log(line));
+    const base = { apiUrl: command.apiUrl, token: command.token, ...(io.fetchFn ? { fetchFn: io.fetchFn } : {}) };
     const action = command.action;
     if (action.kind === "create") {
-        const result = await apiRequest(base, "/v1/me/api-keys", {
+        const requested = apiKeyCreateBody(action, await resolveKeyProjectIds(base, action.projects), (io.now ?? (() => new Date()))());
+        const result = await accountRequest(base, "/v1/me/api-keys", {
             method: "POST",
-            body: JSON.stringify(action.name ? { name: action.name } : {}),
+            body: JSON.stringify(requested),
         });
+        await refuseUnscopedKey(base, requested, result.apiKey);
         if (action.json) {
-            console.log(JSON.stringify({ apiKey: result.apiKey, token: result.token }));
+            log(JSON.stringify({ apiKey: result.apiKey, token: result.token }));
             return;
         }
-        console.log(`Created API key ${result.apiKey.id} (${result.apiKey.name}). The token is shown once:`);
-        console.log(result.token);
-        console.log("Store it in your CI or server secret store under any name but NINEPM_*, and pass it as --token or NINEPM_API_KEY.");
+        const preset = action.preset ?? apiKeyPresetLabel(result.apiKey);
+        const reach = preset === "full"
+            ? "full access to every app"
+            : action.automation
+                ? `${preset} preset, apps of automation ${action.automation}`
+                : `${preset} preset, apps ${action.projects.join(", ")}`;
+        log(`Created API key ${result.apiKey.id} (${result.apiKey.name}): ${reach}. The token is shown once:`);
+        log(result.token);
+        log("Store it in your CI or server secret store under any name but NINEPM_*, and pass it as --token or NINEPM_API_KEY.");
+        log(result.apiKey.expiresAt
+            ? `It expires ${result.apiKey.expiresAt}, and sooner after 90 days without use.`
+            : "It lapses after 90 days without use.");
+        if (preset === "deploy" || preset === "provision") {
+            log(DEPLOY_KEY_SECRETS_WARNING);
+        }
+        if (preset !== "full") {
+            log(`If it lapses, mint a replacement here with the same ${action.automation ? "--automation" : "--project flags"}${action.automation ? " (the automation's apps stay attached)" : ""}, then run 9pm api-key revoke <old-key-id>.`);
+        }
         return;
     }
     if (action.kind === "ls") {
-        const result = await apiRequest(base, "/v1/me/api-keys", { method: "GET" });
+        const result = await accountRequest(base, "/v1/me/api-keys", { method: "GET" });
         const live = result.apiKeys.filter((key) => !key.revokedAt);
         if (action.json) {
-            console.log(JSON.stringify({ apiKeys: live }));
+            // Each key exactly as the server sent it, plus `preset` so a script need not know
+            // that a null scope means full access.
+            log(JSON.stringify({ apiKeys: live.map((key) => ({ ...key, preset: apiKeyPresetLabel(key) })) }));
             return;
         }
         if (live.length === 0) {
-            console.log("No active API keys.");
+            log("No active API keys.");
             return;
         }
         for (const key of live) {
-            console.log(`${key.id}\t${key.name}\t${key.prefix}...\tcreated ${key.createdAt.slice(0, 10)}\tlast used ${key.lastUsedAt ? key.lastUsedAt.slice(0, 10) : "never"}`);
+            log(apiKeyListLine(key));
         }
         return;
     }
-    const revoked = await apiRequest(base, `/v1/me/api-keys/${encodeURIComponent(action.keyId)}/revoke`, { method: "POST" });
-    console.log(`Revoked API key ${revoked.apiKey.id} (${revoked.apiKey.name}).`);
+    const revoked = await accountRequest(base, `/v1/me/api-keys/${encodeURIComponent(action.keyId)}/revoke`, {
+        method: "POST",
+    });
+    log(`Revoked API key ${revoked.apiKey.id} (${revoked.apiKey.name}).`);
+}
+export async function runAutomationCommand(command, io = {}) {
+    const log = io.log ?? ((line) => console.log(line));
+    const base = { apiUrl: command.apiUrl, token: command.token, ...(io.fetchFn ? { fetchFn: io.fetchFn } : {}) };
+    const action = command.action;
+    const route = (automationId) => `/v1/me/automations/${encodeURIComponent(automationId)}`;
+    if (action.kind === "create") {
+        const result = await accountRequest(base, "/v1/me/automations", {
+            method: "POST",
+            body: JSON.stringify({ name: action.name }),
+        });
+        if (action.json)
+            return log(JSON.stringify(result));
+        const id = result.automation.id;
+        log(`Created automation ${id} (${result.automation.name}).`);
+        log(`Attach apps: 9pm automation attach ${id} <app>`);
+        log(`Mint its key: 9pm api-key create --preset provision --automation ${id}`);
+        return;
+    }
+    if (action.kind === "ls") {
+        const result = await accountRequest(base, "/v1/me/automations", { method: "GET" });
+        if (action.json)
+            return log(JSON.stringify(result));
+        if (result.automations.length === 0) {
+            log("No automations. Create one: 9pm automation create <name>");
+            return;
+        }
+        for (const line of renderColumns([
+            ["ID", "NAME", "APPS", "ACTIVE KEYS"],
+            ...result.automations.map((automation) => [
+                automation.id,
+                automation.name,
+                String(automation.apps?.length ?? 0),
+                String(automation.activeKeys ?? 0),
+            ]),
+        ])) {
+            log(line);
+        }
+        return;
+    }
+    if (action.kind === "rename") {
+        const result = await accountRequest(base, route(action.automationId), {
+            method: "PATCH",
+            body: JSON.stringify({ name: action.name }),
+        });
+        if (action.json)
+            return log(JSON.stringify(result));
+        log(`Renamed automation ${result.automation.id} to "${result.automation.name}".`);
+        return;
+    }
+    if (action.kind === "rm") {
+        const result = await accountRequest(base, route(action.automationId), { method: "DELETE" });
+        if (action.json)
+            return log(JSON.stringify(result));
+        log(`Deleted automation ${action.automationId}. Revoked ${result.revokedKeys} API key(s).`);
+        log(result.releasedApps.length > 0
+            ? `Its ${result.releasedApps.length} app(s) stay in your account as ordinary apps: ${result.releasedApps.map((app) => app.slug).join(", ")}.`
+            : "It had no apps.");
+        return;
+    }
+    if (action.kind === "attach") {
+        const result = await accountRequest(base, `${route(action.automationId)}/apps`, {
+            method: "POST",
+            body: JSON.stringify({ project: action.app }),
+        });
+        if (action.json)
+            return log(JSON.stringify(result));
+        log(`Attached ${result.app.slug} to automation ${action.automationId}. Its provision keys now reach it.`);
+        return;
+    }
+    if (action.kind === "detach") {
+        const result = await accountRequest(base, `${route(action.automationId)}/apps/${encodeURIComponent(action.app)}`, { method: "DELETE" });
+        if (action.json)
+            return log(JSON.stringify(result));
+        log(`Detached ${result.app.slug} from automation ${action.automationId}. Its provision keys no longer reach it; the app stays in your account.`);
+        return;
+    }
+    const result = await accountRequest(base, route(action.automationId), { method: "GET" });
+    const apps = result.automation.apps ?? [];
+    if (action.json)
+        return log(JSON.stringify({ automationId: result.automation.id, apps }));
+    if (apps.length === 0) {
+        log(`Automation ${result.automation.id} (${result.automation.name}) has no apps. Attach one: 9pm automation attach ${result.automation.id} <app>`);
+        return;
+    }
+    for (const line of renderColumns([["SLUG", "NAME", "ID"], ...apps.map((app) => [app.slug, app.name, app.id])])) {
+        log(line);
+    }
+}
+// What each preset may do, as the server grants it. Used only to word a refusal: the
+// server decides, and a permission missing from this table is reported as needing a
+// full-access login rather than guessed at.
+const PRESET_PERMISSIONS_FOR_GUIDANCE = [
+    ["monitor", ["project.read"]],
+    ["deploy", ["project.read", "deploy", "env.write", "database.create"]],
+    ["provision", ["project.read", "project.create", "deploy", "env.write", "database.create"]],
+];
+export const SCOPED_KEY_PREFIX = "9pm_sk_";
+function apiFailureOf(error) {
+    let current = error;
+    for (let depth = 0; depth < 5 && current; depth += 1) {
+        if (current instanceof ApiResponseError)
+            return { status: current.status, code: current.code, details: current.details };
+        if (current instanceof DomainsApiError)
+            return { status: current.status, code: current.code, details: undefined };
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return null;
+}
+/**
+ * What to add under an error when the credential is a scoped key, so the reader learns
+ * the real cause. Never points a scoped key at `9pm api-key ls`: that needs a full-access
+ * login, and the key would be refused again.
+ */
+export function scopedKeyGuidance(error, context) {
+    const failure = apiFailureOf(error);
+    if (!failure)
+        return [];
+    const scoped = typeof context.token === "string" && context.token.startsWith(SCOPED_KEY_PREFIX);
+    if (failure.code === "permission_denied") {
+        const details = failure.details;
+        const permission = details && typeof details === "object" && typeof details.permission === "string"
+            ? details.permission
+            : null;
+        if (!permission) {
+            return ["This API key's preset does not allow this. It needs a full-access login (9pm login)."];
+        }
+        const presets = PRESET_PERMISSIONS_FOR_GUIDANCE.filter(([, permissions]) => permissions.includes(permission)).map(([preset]) => preset);
+        if (presets.length === 0) {
+            return [`This API key lacks the "${permission}" permission, and no key preset includes it. It needs a full-access login (9pm login).`];
+        }
+        const first = presets[0];
+        const scopeFlag = first === "provision" ? "--automation <id>" : "--project <app>";
+        const named = presets.length === 1 ? `${first} preset includes` : `${presets.slice(0, -1).join(", ")} and ${presets[presets.length - 1]} presets include`;
+        return [
+            `This API key lacks the "${permission}" permission. The ${named} it.`,
+            `From a full-access login, mint a key with it: 9pm api-key create --preset ${first} ${scopeFlag}`,
+        ];
+    }
+    if (!scoped)
+        return [];
+    const settings = `${dashboardUrlForApiUrl(context.apiUrl ?? DEFAULT_API_URL)}/settings`;
+    if (failure.code === "expired_api_key") {
+        return [
+            "This is a scoped API key, so 9pm login does not replace it.",
+            "From a full-access login, mint a replacement that reaches the same apps with the same permissions, give it to the worker, then revoke the old key.",
+            "For a provision key, mint the replacement for the same automation (--automation <id>): the automation's apps are still attached.",
+        ];
+    }
+    if (failure.status === 404) {
+        return [
+            "This is a scoped API key: the app was not found, or this key does not reach it.",
+            `Check which apps the key reaches under API keys in your account Settings (${settings}), or from a CLI signed in with your full-access login.`,
+        ];
+    }
+    return [];
 }
 async function runSupportCommand(command) {
     const subject = command.subject ?? (command.message.split("\n")[0] ?? command.message).slice(0, 200);
@@ -6730,6 +7388,59 @@ async function runFilesCommand(command) {
         }
     }
 }
+export const API_KEY_USAGE = `Usage:
+  9pm api-key create [--name <name>] [--preset <preset>] [--project <app>]... [--automation <id>] [--expires <when>] [--json]
+  9pm api-key ls [--json]
+  9pm api-key revoke <key-id>
+
+An API key lets CI or an unattended worker act without a browser login. Pass it as
+NINEPM_API_KEY or --token. The token is printed once, when the key is created.
+
+Presets:
+  monitor     read app status and deployment history          apps: --project <app> (repeat it)
+  deploy      monitor, plus deploy, set env vars, add a db    apps: --project <app> (repeat it)
+  provision   deploy, plus create apps                        apps: those in --automation <id>
+  full        everything, on every app (the default)
+
+A scoped key (monitor, deploy, provision) cannot delete apps, change access, manage
+domains or files, mint keys or manage automations; those need a full-access login.
+Deploying to an app is effectively access to that app's secrets and data: a key that
+can replace an app's code can read anything the app can.
+
+Expiry:
+  --expires <when> sets a fixed deadline, at most a year ahead. <when> is an ISO 8601
+  date-time with its zone (2026-12-31T00:00:00Z) or a relative <N>d or <N>h (30d, 12h).
+  An explicit expiry does not replace the 90-day inactivity rule: every key also lapses
+  after 90 days without use, and a key with --expires lapses at whichever comes first.
+  To recover, mint a replacement from a full-access login with the same preset and apps
+  (or the same --automation, whose apps stay attached), then revoke the old key.
+
+A scoped key needs a control plane that supports it. If the server answers with a
+full-access key instead, the CLI revokes that key at once and prints no token.
+
+Creating, listing and revoking keys needs a full-access login.`;
+export const AUTOMATION_USAGE = `Usage:
+  9pm automation create <name> [--json]
+  9pm automation ls [--json]
+  9pm automation rename <automation-id> <new-name> [--json]
+  9pm automation rm <automation-id> --yes [--json]
+  9pm automation attach <automation-id> <app> [--json]
+  9pm automation detach <automation-id> <app> [--json]
+  9pm automation apps <automation-id> [--json]
+
+An automation groups the apps a provision key reaches. The apps stay your account's
+own; the automation only decides which provision keys reach them. An app belongs to at
+most one automation: detach it before attaching it elsewhere.
+
+Mint a key for one: 9pm api-key create --preset provision --automation <automation-id>
+
+rm revokes every key minted for the automation at once, and keeps its apps as ordinary
+apps of your account. It needs --yes.
+
+Every automation command needs a full-access login.`;
+export function usageForTopic(topic) {
+    return topic === "api-key" ? API_KEY_USAGE : AUTOMATION_USAGE;
+}
 function printUsage() {
     console.log(`Usage:
   9pm --version
@@ -6782,9 +7493,11 @@ function printUsage() {
   9pm access service revoke <site> <service-token-id>
   9pm access token create <site> [--name <name>]
   9pm access token revoke <site> <token-id>
-  9pm api-key create [--name <name>] [--json]   mint a platform API key for CI or a server; the token is shown once
+  9pm api-key create [--name <name>] [--preset monitor|deploy|provision|full] [--project <app>]... [--automation <id>] [--expires 30d|12h|<iso-date-time>] [--json]
+                                                 mint an API key for CI or a worker; the token is shown once (9pm api-key --help)
   9pm api-key ls [--json]
   9pm api-key revoke <key-id>
+  9pm automation create|ls|rename|rm|attach|detach|apps   group the apps a provision key reaches (9pm automation --help)
 
 Environment:
   NINEPM_API_URL   ${API_URL_HELP}
@@ -6824,16 +7537,19 @@ Custom domains:
   Every domains command takes --owner <organisation> for an organisation's app. list, status and
   wait only read; add, check, restart, remove and move need the configure role on the app.
   --json prints {hostname, app, state, reason, next, routing, tls, provider, nameservers,
-  records[{type, name, fqdn, expected, current, ok, check, apex, optional}], error, expiresAt,
-  checkedAt, removing}. state is one of live, waiting_for_dns, dns_unverified (routing is active but the
-  records could not be checked), issuing_certificate (every required record checked and found),
-  failed, expired. reason says why (reason.providerMessage is the provider's own text, when it
+  records[{type, name, fqdn, expected, current, ok, check, elsewhere, apex, optional}], error, expiresAt,
+  checkedAt, removing}. state is one of live, ready_to_switch (routing and the certificate are active,
+  but the routing record still leads to another host: change it to the value shown), waiting_for_dns,
+  dns_unverified (routing is active but the records could not be checked), issuing_certificate (every
+  required record checked and found), points_elsewhere (the domain's DNS now leads to another host:
+  remove it here once the move is done, or point it back), failed, expired. reason says why (reason.providerMessage is the provider's own text, when it
   reported any, and its source: certificate_authority or hostname); next says who acts next (owner or platform) and what to do.
   A record's name is relative to the zone (www, _acme-challenge.www, @). ok is null when the
   check cannot say: check is not_checked, or apex_addresses for a root record answering with
   addresses (a correct ALIAS does), which defers to the routing status.
   wait exits 0 when live, 10 on timeout with something for the owner to do (records missing or
-  unverified, or a CAA record blocking the certificate), 11 on timeout with every record found and
+  unverified, a routing record still to switch, or a CAA record blocking the certificate), and at
+  once when the domain points elsewhere, 11 on timeout with every record found and
   nothing for the owner to do (the platform is still finishing), 20 when the domain failed or
   expired, and 1 on a usage, auth or API error. A domain whose removal is still finishing shows
   as removing ("removing": true in --json), and wait on it exits 20.