ninepm 0.85.0 → 0.92.0

package/README.md

@@ -163,7 +163,7 @@ Delete an app, its managed database, managed container app, and retained image:
 
 The app's address goes with it: creating an app again under the same slug gives it a new address, so printed links and QR codes stop working. `9pm delete` prints this warning before it deletes anything.
 
-For a static or Worker app with no custom domain, `9pm delete` also prints `Its address stops serving the app within about a minute.` It prints nothing about timing for a container app or an app with a custom domain: how long those keep serving after a delete has not been measured, so check the address yourself.
+`9pm delete` also prints `Its address stops serving the app within about a minute.` when the delete went the way whose timing has been measured: a static or Worker app, or a container app on the default (non-persistent) placement, with no custom domain. Not every such container app qualifies, so go by the line, not the app type. When the line is missing (an app with a custom domain, a container app with a volume, always-on or custom CPU/memory, some other container apps, or a cleanup step that reported an error), how long the address keeps serving has not been measured, so check the address yourself.
 
 ## Access Modes
 
@@ -240,9 +240,9 @@ tls, provider, providerId, nameservers, zone, records, advisories, error, expire
 the DNS host (where the nameservers point, not necessarily where the domain was bought), `reason` says why
 (`reason.providerMessage` carries the provider's own words when it reported any, with `source`
 saying whether they are the certificate authority's),
-`next` says who acts next and what to do, and `state` is `live`,
+`next` says who acts next and what to do, and `state` is `live`, `ready_to_switch`,
 `waiting_for_dns`, `dns_unverified` (routing is active but the records could not be checked),
-`issuing_certificate`, `failed` or `expired`. Each record's `ok` is `null` when the check cannot
+`issuing_certificate`, `points_elsewhere`, `failed` or `expired`. Each record's `ok` is `null` when the check cannot
 say, and its `check` says why (`not_checked`, or `apex_addresses`). A record whose value was found
 at the name with the domain typed twice (`_acme-challenge.www.example.com.example.com`) has
 `check: "doubled"` and `doubledAt`: enter only the short name shown. Since 0.79.0, against a server
@@ -252,7 +252,14 @@ name (the wildcard can stay; a TXT value is always added beside the values alrea
 `resolvers` lists what each public resolver answered when two were asked, and when one shows the
 expected value and another does not, the record is `check: "resolvers_disagree"` with `ok: null`:
 neither cache proves which answer is current, so confirm the record at your DNS host and check again.
-A record that does not match carries `ttlSeconds`, how long that answer may stay cached. A root
+A record that does not match carries `ttlSeconds`, how long that answer may stay cached. Since
+0.92.0, against a server that sends it, a record whose DNS host is GoDaddy, Namecheap, Google Cloud
+DNS or NS1 can carry `authoritative`: what the host's own nameserver answered when asked directly
+(`outcome: "answered"` with `nameserver`, `current` and `matches`, or `outcome: "unverified"` when
+that read failed). The row then says "your DNS host publishes …", or "your DNS host: unable to
+verify directly"; a failed read never means the record is missing. It only explains the row: `ok`,
+`check` and the state stay the public resolvers' verdict either way. Other hosts get no such
+field. A root
 answering with addresses while routing is pending asks you to confirm the ALIAS or ANAME target,
 since a parking page answers with addresses too. With every record found, the text names the
 platform's next automatic check from `next.nextCheckAt`. `advisories` lists hints that
@@ -263,6 +270,24 @@ field empty) and `valueAtProvider`: the record as a recognised DNS host's editor
 the text output then suggests connecting `www` instead. `list`, `status` and `wait`
 only read; `add`, `check`, `restart`, `remove` and `move` need permission to configure the app.
 
+Since 0.89.0, against a server that sends them, two states cover moving a domain between hosts.
+`ready_to_switch`: routing and the certificate are active, so the platform could serve the domain,
+but its routing record still leads to another host and visitors still reach that host. The text
+names the record and the value to change it to, `next` is `replace_record`, and `wait` keeps
+waiting until it is `live`. `points_elsewhere`: the domain was live and its DNS now leads to another
+host, so the provider stopped routing it. `next` is `remove`: remove the domain here once visitors
+reach the new host. If the move was a mistake, change the record back and run `9pm domains restart`:
+the provider keeps a moved hostname moved until its validation is restarted, so `check` alone does
+not recover it. Once the record points back, the state is `failed` with `reason.code`
+`moved_needs_restart` and `next.action` `start_over`, and the text prints the `restart` and `wait`
+commands; a blocked or deleted hostname never gets this step. Publish any new TXT values `restart` prints, then `wait`. The provider deletes a
+hostname left moved for 7 days. `wait` stops at once with `10` on this state. Either state's routing record carries `elsewhere`, the host it leads to. The platform reports
+these only on strong evidence: two public resolvers agree on a record of the name's own that leads,
+through its whole CNAME chain, to a host outside both your zone and the platform. A root answering
+with addresses, a wildcard's answer, resolvers that disagree, or a check that could not run leave
+the domain in the state it had (`live`, or `failed` for one the provider stopped routing). An older
+CLI prints these state names as they are.
+
 `9pm domains remove` prints only the records the API says the domain used, each to delete only if
 its value is unchanged: a name that now holds a different value (the domain points somewhere new, or
 another service's certificate check uses `_acme-challenge`) is not ours, so leave it. Against a server
@@ -272,6 +297,21 @@ prints the `9pm domains list` command: once the domain is no longer listed, it h
 from 9pm. Such a domain shows as `removing` in `list` and `status` (`"removing": true` in `--json`),
 and `wait` on it exits `20`. Since 0.80.0.
 
+Since 0.86.0, a removal that finished (from `remove` or `9pm delete`) also says that after removal,
+visitors may see a TLS or routing error while the domain's DNS still points at 9pm. It names no
+record and adds no deletion advice of its own: what may be deleted is only the cleanup list printed
+above it, each record only if its value still matches. A removal still finishing gets no such line,
+since it is told to leave its records in place. A server that sends no cleanup list still gets it.
+
+Since 0.87.0, that line is followed by the order the staging rehearsal (#2182) demonstrated for a
+move to another host: point 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, and once DNS points away 9pm shows the domain as pointing elsewhere (before 0.89.0, or
+against an older server, as failed), which is expected. It links the
+custom-domain guide's "Moving a domain off 9pm" section on the site beside the control plane it
+talked to (staging's guide for `--api-url https://api-staging.9pm.ai`). A move to your own Cloudflare
+DNS zone was not rehearsed, so no order is printed for it; the guide says to contact support first.
+
 Since 0.84.0, `9pm domains removed [--owner <organisation>]` lists the DNS records you may delete
 after a removal that finished in the background: a `remove` that answered `releasing`, or a domain of
 a deleted app, finished later by the platform. It is the same list `remove` prints when it finishes

package/dist/cli-config.d.ts

@@ -1,5 +1,5 @@
 export declare const DEFAULT_API_URL = "https://api.9pm.ai";
 export declare const CLI_CLIENT_ID = "ninepm";
 export declare const API_URL_HELP = "Control plane API URL";
-export declare const API_KEY_HELP = "API key from 9pm.ai; overrides stored login";
+export declare const API_KEY_HELP = "API key from 9pm api-key create (or Settings > API keys); overrides stored login";
 export declare function reportCliError(error: unknown): void;

package/dist/cli-config.js

@@ -10,7 +10,7 @@ export const DEFAULT_API_URL = "https://api.9pm.ai";
 export const CLI_CLIENT_ID = "ninepm";
 // Help text for the NINEPM_API_URL / NINEPM_API_KEY environment variables.
 export const API_URL_HELP = "Control plane API URL";
-export const API_KEY_HELP = "API key from 9pm.ai; overrides stored login";
+export const API_KEY_HELP = "API key from 9pm api-key create (or Settings > API keys); overrides stored login";
 // Render an error to stderr.
 export function reportCliError(error) {
     console.error(error instanceof Error ? error.message : error);

package/dist/domain-state.d.ts

@@ -54,6 +54,28 @@ export interface DomainStateDnsRecord {
     ttlSeconds?: number;
     /** Each public resolver's answer, when a second one was asked. `matches` above is the first resolver's, so a disagreement is never a match. */
     resolvers?: DomainStateResolverAnswer[];
+    /**
+     * #2238: where a routing record leads instead of the platform - the last name of its CNAME
+     * chain, outside both the owner's zone and the platform's. The server sets it only on strong
+     * evidence: the answer is a name of the record's own (not addresses, not a wildcard's), two
+     * public resolvers both answered without the expected value, and every link of the chain was
+     * looked up. Absent from older servers, and whenever any of that is not so.
+     */
+    elsewhere?: string;
+    /** #2241: what the DNS host's own nameserver answered when asked directly. Absent from older servers and for hosts not read directly. */
+    authoritative?: DomainStateAuthoritativeAnswer;
+}
+/**
+ * A direct read from the DNS host's own nameserver (#2241), done only for the hosts it was
+ * measured on. It never decides anything: every verdict here (check, ok, state, reason, next) is
+ * the public resolvers', and this is shown beside it as "your DNS host publishes X". "unverified"
+ * means the read failed, and reads "unable to verify", never "nothing published".
+ */
+export interface DomainStateAuthoritativeAnswer {
+    outcome: "answered" | "unverified";
+    nameserver?: string;
+    current?: string[];
+    matches?: boolean;
 }
 /** What the derivation reads: a domain as any of the domain endpoints returns it. */
 export interface DomainStateInput {
@@ -67,8 +89,9 @@ export interface DomainStateInput {
     providerMessage?: string | null;
     providerMessageAt?: string | null;
     providerMessageSource?: string | null;
+    routingFailure?: string | null;
 }
-export type DomainState = "live" | "waiting_for_dns" | "dns_unverified" | "issuing_certificate" | "failed" | "expired";
+export type DomainState = "live" | "ready_to_switch" | "waiting_for_dns" | "dns_unverified" | "issuing_certificate" | "points_elsewhere" | "failed" | "expired";
 export type DomainRecordCheck = "found" | "missing" | "different" | "doubled" | "wildcard" | "resolvers_disagree" | "not_checked" | "apex_addresses";
 export interface DomainRecordStatus {
     type: string;
@@ -82,6 +105,8 @@ export interface DomainRecordStatus {
     wildcard?: string;
     ttlSeconds?: number;
     resolvers?: DomainStateResolverAnswer[];
+    elsewhere?: string;
+    authoritative?: DomainStateAuthoritativeAnswer;
     apex: boolean;
     optional: boolean;
 }
@@ -92,6 +117,20 @@ export declare function domainRecordCheck(seen: DomainStateDnsRecord | undefined
  * neither breaks a row nor counts towards a disagreement.
  */
 export declare function resolverAnswers(seen: DomainStateDnsRecord | undefined): DomainStateResolverAnswer[];
+/**
+ * The direct read as the server reported it, or null when there was none. Only a complete
+ * answer (an "answered" outcome with its nameserver, values and match) reads as one; anything
+ * else that is present, an outcome this copy does not know included, reads as "unverified", so a
+ * malformed or newer entry can only ever say "unable to verify", never "nothing published".
+ */
+export declare function authoritativeAnswer(seen: DomainStateDnsRecord | undefined): DomainStateAuthoritativeAnswer | null;
+/**
+ * Whether a row shows its direct read. Shown wherever the resolvers did not find the record, so
+ * the owner sees what their host publishes beside what the caches still say; on a found record
+ * only when the host now publishes something else, since agreement and a failed read there would
+ * add nothing to "found".
+ */
+export declare function showsAuthoritativeAnswer(record: Pick<DomainRecordStatus, "check" | "authoritative">): boolean;
 /** Whether one resolver shows the expected value while another shows something else. */
 export declare function resolversDisagree(seen: DomainStateDnsRecord | undefined): boolean;
 /** A cache's time left in whole minutes, at least one: "up to N min". */
@@ -113,8 +152,14 @@ export declare function rootUnsupportedWwwHostname(domain: DomainStateInput): st
 export declare function showsUseWww(next: {
     action?: string;
 } | null | undefined): boolean;
+/**
+ * Where the routing record leads instead of the platform (#2238), or null. Every required
+ * routing record has to say so, so one record that is found, unread or ambiguous keeps the
+ * domain where it was. TXT records never route, so they are not asked.
+ */
+export declare function routingLeadsElsewhere(records: DomainRecordStatus[]): string | null;
 export declare function deriveDomainState(domain: DomainStateInput, records?: DomainRecordStatus[]): DomainState;
-export type DomainReasonCode = "records_missing" | "record_points_elsewhere" | "dns_changed_after_live" | "dns_not_checked" | "apex_unverifiable" | "dns_resolvers_disagree" | "dns_host_cannot_point_root" | "caa_blocks" | "certificate_pending" | "certificate_failed" | "hostname_failed" | "service_mode" | "claimed_elsewhere" | "platform_not_configured" | "provider_error" | "expired";
+export type DomainReasonCode = "records_missing" | "record_points_elsewhere" | "dns_changed_after_live" | "dns_not_checked" | "apex_unverifiable" | "dns_resolvers_disagree" | "dns_host_cannot_point_root" | "caa_blocks" | "certificate_pending" | "certificate_failed" | "hostname_failed" | "service_mode" | "claimed_elsewhere" | "platform_not_configured" | "provider_error" | "moved_needs_restart" | "domain_points_elsewhere" | "expired";
 export interface DomainReason {
     code: DomainReasonCode;
     /**
@@ -128,7 +173,7 @@ export interface DomainReason {
         source: "certificate_authority" | "hostname";
     };
 }
-export type DomainNextAction = "none" | "add_records" | "replace_record" | "confirm_records" | "use_www" | "allow_ca_in_your_zone" | "ask_caa_controller" | "check_caa" | "wait" | "start_over" | "change_access_mode" | "add_again" | "recheck" | "contact_support";
+export type DomainNextAction = "none" | "add_records" | "replace_record" | "confirm_records" | "use_www" | "allow_ca_in_your_zone" | "ask_caa_controller" | "check_caa" | "wait" | "start_over" | "change_access_mode" | "add_again" | "recheck" | "remove" | "contact_support";
 export interface DomainNextRecord {
     type: string;
     host: string;
@@ -169,7 +214,9 @@ export interface DomainStatus {
  * The state, why, and the one next step. `state` is exactly deriveDomainState's; `reason` and
  * `next` only refine it. Two rules hold throughout: a record nobody looked at is never called
  * missing (it gets confirm_records, never add), and nothing here restarts validation or
- * suggests that a restart speeds things up - Start over is named only for a failed certificate.
+ * suggests that a restart speeds things up - Start over is named only for a failed certificate,
+ * and for a hostname the provider reports moved (points_elsewhere, or moved_needs_restart once
+ * its DNS no longer leads elsewhere), which stays moved until its validation is restarted (#2238).
  */
 export declare function deriveDomainStatus(domain: DomainStateInput, options?: {
     nextCheckAt?: string | null;

package/dist/domain-state.js

@@ -1,6 +1,6 @@
 // AUTO-GENERATED by scripts/generate-cli-package.mjs from the in-repo CLI source -- do not edit.
 // Edit src/cli or src/shared instead; this is regenerated on typecheck/test/build/pack.
-// One plain-language status for a custom domain (#1994): which of six states it is in, why,
+// One plain-language status for a custom domain (#1994): which of eight states it is in, why,
 // and the one thing that happens next. The control plane computes it after its DNS check and
 // sends it on every domain; the CLI and the dashboard derive it from this same file when they
 // meet a server that predates the field, so the two paths cannot disagree. Copied into the CLI
@@ -50,6 +50,7 @@ export function domainRecordStatuses(domain) {
         const atApex = type === "CNAME" && fqdn === apex;
         const check = domainRecordCheck(seen, atApex);
         const resolvers = resolverAnswers(seen);
+        const direct = authoritativeAnswer(seen);
         const ttl = seen?.ttlSeconds;
         return {
             type,
@@ -61,8 +62,10 @@ export function domainRecordStatuses(domain) {
             check,
             ...(check === "doubled" && seen?.doubledAt ? { doubledAt: seen.doubledAt } : {}),
             ...(check === "wildcard" && seen?.wildcard ? { wildcard: seen.wildcard } : {}),
+            ...(check === "different" && type !== "TXT" && typeof seen?.elsewhere === "string" && seen.elsewhere !== "" ? { elsewhere: seen.elsewhere } : {}),
             ...(check !== "found" && typeof ttl === "number" && Number.isFinite(ttl) && ttl >= 0 ? { ttlSeconds: ttl } : {}),
             ...(resolvers.length > 0 ? { resolvers } : {}),
+            ...(direct ? { authoritative: direct } : {}),
             apex: atApex,
             optional: instruction.optional === true,
         };
@@ -110,6 +113,43 @@ export function resolverAnswers(seen) {
         return [{ resolver: entry.resolver, current, matches: entry.matches, ...(typeof ttl === "number" && Number.isFinite(ttl) && ttl >= 0 ? { ttlSeconds: ttl } : {}) }];
     });
 }
+/**
+ * The direct read as the server reported it, or null when there was none. Only a complete
+ * answer (an "answered" outcome with its nameserver, values and match) reads as one; anything
+ * else that is present, an outcome this copy does not know included, reads as "unverified", so a
+ * malformed or newer entry can only ever say "unable to verify", never "nothing published".
+ */
+export function authoritativeAnswer(seen) {
+    const raw = seen?.authoritative;
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== "object")
+        return { outcome: "unverified" };
+    const entry = raw;
+    if (entry.outcome === "answered" &&
+        typeof entry.nameserver === "string" &&
+        entry.nameserver !== "" &&
+        Array.isArray(entry.current) &&
+        entry.current.every((value) => typeof value === "string") &&
+        typeof entry.matches === "boolean") {
+        return { outcome: "answered", nameserver: entry.nameserver, current: [...entry.current], matches: entry.matches };
+    }
+    return { outcome: "unverified" };
+}
+/**
+ * Whether a row shows its direct read. Shown wherever the resolvers did not find the record, so
+ * the owner sees what their host publishes beside what the caches still say; on a found record
+ * only when the host now publishes something else, since agreement and a failed read there would
+ * add nothing to "found".
+ */
+export function showsAuthoritativeAnswer(record) {
+    const direct = record.authoritative;
+    if (!direct)
+        return false;
+    if (record.check !== "found")
+        return true;
+    return direct.outcome === "answered" && direct.matches === false;
+}
 /** Whether one resolver shows the expected value while another shows something else. */
 export function resolversDisagree(seen) {
     const answers = resolverAnswers(seen);
@@ -152,13 +192,33 @@ export function rootUnsupportedWwwHostname(domain) {
 export function showsUseWww(next) {
     return next?.action === "use_www";
 }
+/**
+ * Where the routing record leads instead of the platform (#2238), or null. Every required
+ * routing record has to say so, so one record that is found, unread or ambiguous keeps the
+ * domain where it was. TXT records never route, so they are not asked.
+ */
+export function routingLeadsElsewhere(records) {
+    const routing = records.filter((record) => !record.optional && record.type !== "TXT");
+    if (routing.length === 0)
+        return null;
+    // `elsewhere` is set only on a record checked `different` (domainRecordStatuses), so a found,
+    // wildcard, doubled or disagreeing record never carries it.
+    if (!routing.every((record) => typeof record.elsewhere === "string" && record.elsewhere !== ""))
+        return null;
+    return routing[0].elsewhere ?? null;
+}
 export function deriveDomainState(domain, records = domainRecordStatuses(domain)) {
     if (domain.provisioningError === CUSTOM_DOMAIN_EXPIRED_MESSAGE)
         return "expired";
+    const elsewhere = routingLeadsElsewhere(records);
+    // Keyed on the provider's own "moved", not on routing failed alone: a blocked or deleted
+    // hostname, or routing failed while the record still leads here, is a real failure.
+    if (elsewhere && domain.routingStatus === "failed" && domain.routingFailure === "moved" && !domain.provisioningError)
+        return "points_elsewhere";
     if (domain.routingStatus === "failed" || domain.tlsStatus === "failed" || domain.provisioningError)
         return "failed";
     if (domain.routingStatus === "active" && domain.tlsStatus === "active")
-        return "live";
+        return elsewhere ? "ready_to_switch" : "live";
     // No record the owner can publish will finish this domain: it waits on the owner choosing www.
     if (rootUnsupportedWwwHostname(domain))
         return "waiting_for_dns";
@@ -205,7 +265,9 @@ function caaNext(caa) {
  * The state, why, and the one next step. `state` is exactly deriveDomainState's; `reason` and
  * `next` only refine it. Two rules hold throughout: a record nobody looked at is never called
  * missing (it gets confirm_records, never add), and nothing here restarts validation or
- * suggests that a restart speeds things up - Start over is named only for a failed certificate.
+ * suggests that a restart speeds things up - Start over is named only for a failed certificate,
+ * and for a hostname the provider reports moved (points_elsewhere, or moved_needs_restart once
+ * its DNS no longer leads elsewhere), which stays moved until its validation is restarted (#2238).
  */
 export function deriveDomainStatus(domain, options = {}) {
     const records = domainRecordStatuses(domain);
@@ -221,6 +283,14 @@ export function deriveDomainStatus(domain, options = {}) {
         return { state, reason: withMessage("expired"), next: { who: "owner", action: "add_again" } };
     if (state === "live")
         return { state, reason: null, next: { action: "none" } };
+    if (state === "points_elsewhere")
+        return { state, reason: withMessage("domain_points_elsewhere"), next: { who: "owner", action: "remove" } };
+    if (state === "ready_to_switch") {
+        // The same reason and action a pending domain with a record pointing elsewhere gets, so a
+        // client that does not know this state still says which record to change, and to what.
+        const routing = required.filter((record) => record.type !== "TXT" && record.check === "different").map(nextRecord);
+        return { state, reason: withMessage("record_points_elsewhere"), next: { who: "owner", action: "replace_record", records: routing } };
+    }
     if (state === "failed") {
         const error = domain.provisioningError;
         if (isServiceModeProvisioningError(error)) {
@@ -232,6 +302,12 @@ export function deriveDomainStatus(domain, options = {}) {
         if (error === CUSTOM_DOMAIN_ROUTE_CONFLICT_MESSAGE) {
             return { state, reason: withMessage("claimed_elsewhere"), next: { who: "platform", action: "contact_support" } };
         }
+        // Cloudflare keeps a moved hostname moved, whatever its DNS says now, until a PATCH restarts
+        // its validation; that PATCH is what Start over sends. Keyed on the provider's own "moved",
+        // so blocked, deleted and platform failures never get it.
+        if (!error && domain.routingFailure === "moved") {
+            return { state, reason: withMessage("moved_needs_restart"), next: { who: "owner", action: "start_over" } };
+        }
         if (!error && domain.tlsStatus === "failed") {
             const fix = required.filter((record) => record.ok === false).map(nextRecord);
             return {

package/dist/index.d.ts

@@ -123,7 +123,7 @@ export interface DeletedSiteResult {
     metadata: boolean;
     errors?: string[];
 }
-export declare function deletedDomainLines(deleted: Pick<DeletedSiteResult, "customDomainCleanup" | "customDomainsReleasing">, options?: DomainFormatOptions): string[];
+export declare function deletedDomainLines(deleted: Pick<DeletedSiteResult, "customDomainCleanup" | "customDomainsReleasing" | "customDomainNames">, options?: DomainFormatOptions): string[];
 export interface CreatedRuntimeToken {
     token: string;
     appAccessToken: AppAccessToken;
@@ -133,7 +133,7 @@ export interface CreatedServiceToken {
     clientSecret: string;
 }
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
-export declare const CLI_VERSION = "0.85.0";
+export declare const CLI_VERSION = "0.92.0";
 type CredentialBackend = "macos-keychain" | "windows-dpapi" | "linux-secret-service" | "file-plaintext" | "none";
 export interface StoredCredentialEntry {
     token: string;
@@ -162,7 +162,9 @@ export interface WhoamiResult {
         id?: string;
         prefix: string;
         expiresAt: string | null;
+        preset?: string | null;
     };
+    restricted?: boolean;
     account?: {
         org?: string;
         plan?: string;
@@ -180,6 +182,11 @@ export interface PublicWhoamiResult {
         email: string;
         role?: string;
     };
+    restricted?: boolean;
+    preset?: string;
+    apiKey?: {
+        prefix: string;
+    };
     account?: {
         org?: string;
         plan?: string;
@@ -220,7 +227,7 @@ export declare function isOpenNextInstalled(directory: string): boolean;
 export declare class DeployError extends Error {
     readonly slug: string | undefined;
     readonly deliberate: boolean;
-    constructor(message: string, slug: string | undefined, deliberate?: boolean);
+    constructor(message: string, slug: string | undefined, deliberate?: boolean, cause?: unknown);
 }
 /**
  * A refusal the platform MEANT — an operator paused deploys, a queue is full —
@@ -254,6 +261,8 @@ export declare function checkDeployDirectory(options: DeployOptions): Promise<De
 export declare function deployCheckSummary(check: DeployCheckResult, publicAssets: string | undefined): string;
 export declare function whoami(options: ApiOptions): Promise<WhoamiResult>;
 export declare function publicWhoamiResult(result: WhoamiResult): PublicWhoamiResult;
+export declare const SCOPED_WHOAMI_NOTE = "Plan, apps and storage are shown to a full-access login only.";
+export declare function whoamiLines(me: PublicWhoamiResult): string[];
 export type CredentialRevocation = {
     kind: "revoked";
 } | {
@@ -280,6 +289,7 @@ export type LogoutSummary = {
     kind: "already_invalid";
 };
 export declare function summarizeRevocations(attempts: RevocationAttempt[]): LogoutSummary;
+export declare function doctorAccountLines(account: PublicWhoamiResult): string[];
 export declare function getSiteAccess(options: SiteAccessOptions): Promise<AccessState>;
 export declare const ACCESS_MODE_CHANGE_UNCONFIRMED = "access_mode_change_unconfirmed";
 export interface AccessModeChangeOptions extends SiteAccessOptions {
@@ -495,6 +505,18 @@ export interface DeviceAuthProgressReporter {
 export declare function createDeviceAuthProgressReporter(stream?: NodeJS.WriteStream, options?: {
     hint?: string;
 }): DeviceAuthProgressReporter;
+/**
+ * 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 declare class ApiResponseError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    readonly serverMessage: string | null;
+    readonly details: unknown;
+    constructor(message: string, status: number, code: string | null, serverMessage: string | null, details?: unknown);
+}
 export declare function noteCliOutdatedAdvisory(response: Response, log?: (line: string) => void): void;
 export declare function resetCliOutdatedAdvisoryForTests(): void;
 export declare function dashboardUrlForApiUrl(apiUrl: string): string;
@@ -560,16 +582,47 @@ type CliCommand = {
     token: string;
 } | {
     kind: "api-key";
+    action: ApiKeyCreateAction | {
+        kind: "ls";
+        json: boolean;
+    } | {
+        kind: "revoke";
+        keyId: string;
+    };
+    apiUrl: string;
+    token: string;
+} | {
+    kind: "automation";
     action: {
         kind: "create";
-        name?: string;
+        name: string;
         json: boolean;
     } | {
         kind: "ls";
         json: boolean;
     } | {
-        kind: "revoke";
-        keyId: string;
+        kind: "rename";
+        automationId: string;
+        name: string;
+        json: boolean;
+    } | {
+        kind: "rm";
+        automationId: string;
+        json: boolean;
+    } | {
+        kind: "attach";
+        automationId: string;
+        app: string;
+        json: boolean;
+    } | {
+        kind: "detach";
+        automationId: string;
+        app: string;
+        json: boolean;
+    } | {
+        kind: "apps";
+        automationId: string;
+        json: boolean;
     };
     apiUrl: string;
     token: string;
@@ -829,6 +882,7 @@ export declare function domainStatusJson(domain: CliDomain, app: string, checked
 export declare function domainStateLabel(state: string): string;
 export declare function domainWaitExitCode(status: Pick<DomainStatusJson, "state" | "next">): number;
 export declare function nextCheckText(nextCheckAt: unknown): string | null;
+export declare function authoritativeText(record: Pick<DomainRecordStatus, "check" | "authoritative">): string | null;
 export interface DomainFormatOptions {
     owner?: string;
     target?: AccessApiTarget;
@@ -897,6 +951,8 @@ export declare function getDomainSetupCleanup(options: DomainCommandOptions & {
 }): Promise<unknown>;
 export declare function domainSetupCleanupLines(body: unknown, hostname: string): string[];
 export declare function setupCleanupLines(hostname: string, records: DomainCleanupRecord[]): string[];
+export declare function customDomainMoveOffGuideUrl(options?: DomainFormatOptions): string;
+export declare function domainRemovedConsequenceLines(hostnames: string[], options?: DomainFormatOptions): string[];
 export declare function domainRemovalPendingLines(hostname: string, app: string, options: DomainFormatOptions): string[];
 export declare const FINISHED_REMOVAL_PAGES_PER_COMMAND = 20;
 export declare function getFinishedDomainRemovals(options: ApiOptions & {
@@ -969,6 +1025,24 @@ export declare function qrCustomDomainNote(hostname: string): string;
 export declare function pickQrAddress(addresses: readonly ProjectQrAddress[], requested: string | undefined): ProjectQrAddress;
 /** An 8-bit greyscale PNG of a module matrix (quiet zone included), black on white. */
 export declare function encodeQrPng(modules: readonly (readonly boolean[])[], scale?: number): Buffer;
+export type ApiKeyPresetName = "monitor" | "deploy" | "provision" | "full";
+export interface ApiKeyCreateAction {
+    kind: "create";
+    name?: string;
+    preset?: ApiKeyPresetName;
+    projects: string[];
+    automation?: string;
+    expires?: string;
+    json: boolean;
+}
+export declare 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 declare function resolveApiKeyExpiry(value: string, now: Date): string;
+export declare 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.";
 export type ApiUrlSource = "flag" | "env" | "default";
 export declare function workerPublicFiles(paths: readonly string[], serverEntry: string, selection: string | null): Array<{
     path: string;
@@ -1002,9 +1076,78 @@ export declare function classifyBrowserOpen(input: {
 }): BrowserOpenResult;
 export declare function hasNoGraphicalDisplay(platform: string, env: Record<string, string | undefined>): boolean;
 export declare function formatAppUserFilesUsageLine(slug: string, usage: AppUserFilesUsage): string;
+export type UsageTopic = "api-key" | "automation";
 export declare class UsageError extends Error {
+    readonly topic: UsageTopic | undefined;
+    constructor(topic?: UsageTopic);
 }
 export declare function missingPagesLine(deployment: Deployment): string | null;
+export interface ApiKeySummary {
+    id: string;
+    name: string;
+    prefix: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+    expiresAt: string | null;
+    revokedAt: string | null;
+    inactivityExpiresAt?: string | null;
+    scope?: {
+        preset: string;
+        permissions: readonly string[] | null;
+        automationId: string | null;
+        projectIds?: string[];
+    } | null;
+}
+export interface CommandIo {
+    fetchFn?: FetchLike;
+    log?: (line: string) => void;
+    now?: () => Date;
+}
+export declare function apiKeyPresetLabel(key: Pick<ApiKeySummary, "scope">): string;
+export declare function apiKeyListLine(key: ApiKeySummary): string;
+export declare 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.";
+export interface ApiKeyCreateRequest {
+    name?: string;
+    preset?: string;
+    projectIds?: string[];
+    automationId?: string;
+    expiresAt?: string;
+}
+/**
+ * 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 declare function scopedKeyMismatch(requested: ApiKeyCreateRequest, created: ApiKeySummary): string | null;
+export declare function runApiKeyCommand(command: Extract<CliCommand, {
+    kind: "api-key";
+}>, io?: CommandIo): Promise<void>;
+export interface AutomationSummary {
+    id: string;
+    name: string;
+    createdAt: string;
+    updatedAt: string;
+    apps?: Array<{
+        id: string;
+        slug: string;
+        name: string;
+    }>;
+    activeKeys?: number;
+}
+export declare function runAutomationCommand(command: Extract<CliCommand, {
+    kind: "automation";
+}>, io?: CommandIo): Promise<void>;
+export declare const SCOPED_KEY_PREFIX = "9pm_sk_";
+/**
+ * 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 declare function scopedKeyGuidance(error: unknown, context: {
+    token?: string | undefined;
+    apiUrl?: string | undefined;
+}): string[];
 type AccessModeChangeAction = Extract<Extract<CliCommand, {
     kind: "access";
 }>["action"], {
@@ -1016,3 +1159,6 @@ export interface AccessApiTarget {
 }
 export declare function apiUrlFlagFor(target?: AccessApiTarget): string;
 export declare function accessSwitchModeCommand(action: AccessModeChangeAction, target?: AccessApiTarget): string;
+export declare const API_KEY_USAGE = "Usage:\n  9pm api-key create [--name <name>] [--preset <preset>] [--project <app>]... [--automation <id>] [--expires <when>] [--json]\n  9pm api-key ls [--json]\n  9pm api-key revoke <key-id>\n\nAn API key lets CI or an unattended worker act without a browser login. Pass it as\nNINEPM_API_KEY or --token. The token is printed once, when the key is created.\n\nPresets:\n  monitor     read app status and deployment history          apps: --project <app> (repeat it)\n  deploy      monitor, plus deploy, set env vars, add a db    apps: --project <app> (repeat it)\n  provision   deploy, plus create apps                        apps: those in --automation <id>\n  full        everything, on every app (the default)\n\nA scoped key (monitor, deploy, provision) cannot delete apps, change access, manage\ndomains or files, mint keys or manage automations; those need a full-access login.\nDeploying to an app is effectively access to that app's secrets and data: a key that\ncan replace an app's code can read anything the app can.\n\nExpiry:\n  --expires <when> sets a fixed deadline, at most a year ahead. <when> is an ISO 8601\n  date-time with its zone (2026-12-31T00:00:00Z) or a relative <N>d or <N>h (30d, 12h).\n  An explicit expiry does not replace the 90-day inactivity rule: every key also lapses\n  after 90 days without use, and a key with --expires lapses at whichever comes first.\n  To recover, mint a replacement from a full-access login with the same preset and apps\n  (or the same --automation, whose apps stay attached), then revoke the old key.\n\nA scoped key needs a control plane that supports it. If the server answers with a\nfull-access key instead, the CLI revokes that key at once and prints no token.\n\nCreating, listing and revoking keys needs a full-access login.";
+export declare const AUTOMATION_USAGE = "Usage:\n  9pm automation create <name> [--json]\n  9pm automation ls [--json]\n  9pm automation rename <automation-id> <new-name> [--json]\n  9pm automation rm <automation-id> --yes [--json]\n  9pm automation attach <automation-id> <app> [--json]\n  9pm automation detach <automation-id> <app> [--json]\n  9pm automation apps <automation-id> [--json]\n\nAn automation groups the apps a provision key reaches. The apps stay your account's\nown; the automation only decides which provision keys reach them. An app belongs to at\nmost one automation: detach it before attaching it elsewhere.\n\nMint a key for one: 9pm api-key create --preset provision --automation <automation-id>\n\nrm revokes every key minted for the automation at once, and keeps its apps as ordinary\napps of your account. It needs --yes.\n\nEvery automation command needs a full-access login.";
+export declare function usageForTopic(topic: UsageTopic): string;