@xano/cli 1.0.3-beta.9 → 1.0.4-beta.1

package/dist/base-command.js

@@ -3,11 +3,46 @@ import * as yaml from 'js-yaml';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { Agent } from 'undici';
 import { checkForUpdate } from './update-check.js';
 import { applyLocalOverrides, findLocalProfilePath, formatLocalProfileBanner, parseLocalProfile, resolveProfileSelection, } from './utils/local-config.js';
 export function buildUserAgent(version) {
     return `xano-cli/${version} (${process.platform}; ${process.arch}) node/${process.version}`;
 }
+/**
+ * Default per-request timeout for Metadata API calls, in milliseconds (15 min).
+ *
+ * Node's built-in fetch (undici) defaults to a 300s `headersTimeout` and throws
+ * UND_ERR_HEADERS_TIMEOUT when a slow endpoint (e.g. a large multidoc push) takes
+ * longer than that to produce response headers — even when the server, ingress
+ * (3600s), and load balancer would happily wait. We replace that hidden 300s
+ * ceiling with a single, generous bound applied to every request. Override with
+ * the XANO_CLI_REQUEST_TIMEOUT_MS env var; set it to 0 to disable the timeout.
+ */
+const DEFAULT_REQUEST_TIMEOUT_MS = 15 * 60 * 1000;
+function resolveRequestTimeoutMs(env = process.env) {
+    const raw = env.XANO_CLI_REQUEST_TIMEOUT_MS;
+    if (raw === undefined || raw === '')
+        return DEFAULT_REQUEST_TIMEOUT_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return DEFAULT_REQUEST_TIMEOUT_MS;
+    return parsed;
+}
+/**
+ * Lazily-built undici dispatcher whose header/body inactivity timeouts match our
+ * request timeout, so undici's internal 300s default never fires first. Built
+ * once and reused across requests. `timeout === 0` means "no bound".
+ */
+let sharedDispatcher;
+function getRequestDispatcher(timeoutMs) {
+    if (timeoutMs === 0) {
+        sharedDispatcher ??= new Agent({ bodyTimeout: 0, headersTimeout: 0 });
+        return sharedDispatcher;
+    }
+    sharedDispatcher ??= new Agent({ bodyTimeout: timeoutMs, headersTimeout: timeoutMs });
+    return sharedDispatcher;
+}
 /**
  * Resolve the credentials file path from flag, env var, or default.
  * Checks (in order): explicit configPath arg, XANO_CONFIG env var, ~/.xano/credentials.yaml
@@ -288,7 +323,16 @@ export default class BaseCommand extends Command {
             'User-Agent': buildUserAgent(this.config.version),
             ...options.headers,
         };
-        const fetchOptions = { ...options, headers };
+        const timeoutMs = resolveRequestTimeoutMs();
+        const fetchOptions = {
+            ...options,
+            // undici dispatcher: lifts the hidden 300s headers/body timeout to our bound
+            dispatcher: getRequestDispatcher(timeoutMs),
+            headers,
+            // belt-and-suspenders hard ceiling that also covers DNS/connect stalls;
+            // surfaces as a clean AbortError (see describeNetworkError). 0 = no bound.
+            ...(timeoutMs > 0 && !options.signal ? { signal: AbortSignal.timeout(timeoutMs) } : {}),
+        };
         const contentType = headers['Content-Type'] || 'application/json';
         if (verbose) {
             this.log('');

package/dist/commands/tenant/snapshot/create/index.d.ts

@@ -0,0 +1,17 @@
+import BaseCommand from '../../../../base-command.js';
+export default class TenantSnapshotCreate extends BaseCommand {
+    static args: {
+        tenant_name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        label: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/tenant/snapshot/create/index.js

@@ -0,0 +1,78 @@
+import { Args, Flags } from '@oclif/core';
+import BaseCommand from '../../../../base-command.js';
+export default class TenantSnapshotCreate extends BaseCommand {
+    static args = {
+        tenant_name: Args.string({
+            description: 'Tenant name to snapshot',
+            required: true,
+        }),
+    };
+    static description = "Create a database snapshot for a tenant (an instant clone of the tenant's database)";
+    static examples = [
+        `$ xano tenant snapshot create t1234-abcd-xyz1 --label before-v2
+Created snapshot t1234-abcd-xyz1_bk_20260603_203614 for tenant t1234-abcd-xyz1
+`,
+        `$ xano tenant snapshot create t1234-abcd-xyz1 -l before-v2 -o json`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        label: Flags.string({
+            char: 'l',
+            default: '',
+            description: 'Optional label appended to the snapshot description (alphanumeric)',
+            required: false,
+        }),
+        output: Flags.string({
+            char: 'o',
+            default: 'summary',
+            description: 'Output format',
+            options: ['summary', 'json'],
+            required: false,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (uses profile workspace if not provided)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(TenantSnapshotCreate);
+        const { profile } = this.resolveProfile(flags);
+        const workspaceId = flags.workspace || profile.workspace;
+        if (!workspaceId) {
+            this.error('No workspace ID provided. Use --workspace flag or set one in your profile.');
+        }
+        const tenantName = args.tenant_name;
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${tenantName}/snapshot`;
+        try {
+            const response = await this.verboseFetch(apiUrl, {
+                body: JSON.stringify({ label: flags.label }),
+                headers: {
+                    'accept': 'application/json',
+                    'Authorization': `Bearer ${profile.access_token}`,
+                    'Content-Type': 'application/json',
+                },
+                method: 'POST',
+            }, flags.verbose, profile.access_token);
+            if (!response.ok) {
+                const errorText = await response.text();
+                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+            }
+            const result = (await response.json());
+            if (flags.output === 'json') {
+                this.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                this.log(`Created snapshot ${result.backup} for tenant ${tenantName}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.error(`Failed to create snapshot: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to create snapshot: ${String(error)}`);
+            }
+        }
+    }
+}

package/dist/commands/tenant/snapshot/delete/index.d.ts

@@ -0,0 +1,19 @@
+import BaseCommand from '../../../../base-command.js';
+export default class TenantSnapshotDelete extends BaseCommand {
+    static args: {
+        tenant_name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        snapshot: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private confirm;
+}

package/dist/commands/tenant/snapshot/delete/index.js

@@ -0,0 +1,102 @@
+import { Args, Flags } from '@oclif/core';
+import * as readline from 'node:readline';
+import BaseCommand from '../../../../base-command.js';
+export default class TenantSnapshotDelete extends BaseCommand {
+    static args = {
+        tenant_name: Args.string({
+            description: 'Tenant name that owns the snapshot',
+            required: true,
+        }),
+    };
+    static description = '[CRITICAL] NEVER delete a snapshot without explicit user confirmation; this permanently drops the snapshot database. The live and original databases cannot be deleted.';
+    static examples = [
+        `$ xano tenant snapshot delete t1234-abcd-xyz1 --snapshot t1234-abcd-xyz1_bk_20260603_203614
+Are you sure you want to delete snapshot "t1234-abcd-xyz1_bk_20260603_203614"? This action cannot be undone. (y/N) y
+Deleted snapshot t1234-abcd-xyz1_bk_20260603_203614
+`,
+        `$ xano tenant snapshot delete t1234-abcd-xyz1 --snapshot t1234-abcd-xyz1_bk_20260603_203614 --force`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        force: Flags.boolean({
+            char: 'f',
+            default: false,
+            description: '[CRITICAL] Skips the confirmation prompt.',
+            required: false,
+        }),
+        output: Flags.string({
+            char: 'o',
+            default: 'summary',
+            description: 'Output format',
+            options: ['summary', 'json'],
+            required: false,
+        }),
+        snapshot: Flags.string({
+            description: 'Snapshot database name to delete',
+            required: true,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (uses profile workspace if not provided)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(TenantSnapshotDelete);
+        const { profile } = this.resolveProfile(flags);
+        const workspaceId = flags.workspace || profile.workspace;
+        if (!workspaceId) {
+            this.error('No workspace ID provided. Use --workspace flag or set one in your profile.');
+        }
+        const tenantName = args.tenant_name;
+        const { snapshot } = flags;
+        if (!flags.force) {
+            const confirmed = await this.confirm(`Are you sure you want to delete snapshot "${snapshot}"? This action cannot be undone.`);
+            if (!confirmed) {
+                this.log('Deletion cancelled.');
+                return;
+            }
+        }
+        const queryParams = new URLSearchParams({ snapshot });
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${tenantName}/snapshot?${queryParams.toString()}`;
+        try {
+            const response = await this.verboseFetch(apiUrl, {
+                headers: {
+                    accept: 'application/json',
+                    Authorization: `Bearer ${profile.access_token}`,
+                },
+                method: 'DELETE',
+            }, flags.verbose, profile.access_token);
+            if (!response.ok) {
+                const errorText = await response.text();
+                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+            }
+            if (flags.output === 'json') {
+                this.log(JSON.stringify({ deleted: true, snapshot, tenant_name: tenantName }, null, 2));
+            }
+            else {
+                this.log(`Deleted snapshot ${snapshot}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.error(`Failed to delete snapshot: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to delete snapshot: ${String(error)}`);
+            }
+        }
+    }
+    async confirm(message) {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        return new Promise((resolve) => {
+            rl.question(`${message} (y/N) `, (answer) => {
+                rl.close();
+                resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+            });
+        });
+    }
+}

package/dist/commands/tenant/snapshot/list/index.d.ts

@@ -0,0 +1,16 @@
+import BaseCommand from '../../../../base-command.js';
+export default class TenantSnapshotList extends BaseCommand {
+    static args: {
+        tenant_name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/tenant/snapshot/list/index.js

@@ -0,0 +1,96 @@
+import { Args, Flags } from '@oclif/core';
+import BaseCommand from '../../../../base-command.js';
+export default class TenantSnapshotList extends BaseCommand {
+    static args = {
+        tenant_name: Args.string({
+            description: 'Tenant name to list snapshots for',
+            required: true,
+        }),
+    };
+    static description = 'List database snapshots for a tenant';
+    static examples = [
+        `$ xano tenant snapshot list t1234-abcd-xyz1
+Snapshots for tenant t1234-abcd-xyz1:
+  - t1234-abcd-xyz1 (25 MB) [ORIGINAL]
+  - t1234-abcd-xyz1_bk_20260603_203614 (25 MB, 2026-06-03 20:36:14) [LIVE]
+`,
+        `$ xano tenant snapshot list t1234-abcd-xyz1 -o json`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        output: Flags.string({
+            char: 'o',
+            default: 'summary',
+            description: 'Output format',
+            options: ['summary', 'json'],
+            required: false,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (uses profile workspace if not provided)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(TenantSnapshotList);
+        const { profile } = this.resolveProfile(flags);
+        const workspaceId = flags.workspace || profile.workspace;
+        if (!workspaceId) {
+            this.error('No workspace ID provided. Use --workspace flag or set one in your profile.');
+        }
+        const tenantName = args.tenant_name;
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${tenantName}/snapshot`;
+        try {
+            const response = await this.verboseFetch(apiUrl, {
+                headers: {
+                    'accept': 'application/json',
+                    'Authorization': `Bearer ${profile.access_token}`,
+                },
+                method: 'GET',
+            }, flags.verbose, profile.access_token);
+            if (!response.ok) {
+                const errorText = await response.text();
+                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+            }
+            const data = (await response.json());
+            let snapshots;
+            if (Array.isArray(data)) {
+                snapshots = data;
+            }
+            else if (data && typeof data === 'object' && 'items' in data && Array.isArray(data.items)) {
+                snapshots = data.items;
+            }
+            else {
+                this.error('Unexpected API response format');
+            }
+            if (flags.output === 'json') {
+                this.log(JSON.stringify(snapshots, null, 2));
+            }
+            else if (snapshots.length === 0) {
+                this.log(`No snapshots found for tenant ${tenantName}`);
+            }
+            else {
+                this.log(`Snapshots for tenant ${tenantName}:`);
+                for (const snapshot of snapshots) {
+                    const size = snapshot.size_pretty || (snapshot.size_bytes ? `${snapshot.size_bytes} bytes` : 'unknown');
+                    const meta = snapshot.created ? `${size}, ${snapshot.created}` : size;
+                    const tags = [];
+                    if (snapshot.is_original)
+                        tags.push('ORIGINAL');
+                    if (snapshot.is_live)
+                        tags.push('LIVE');
+                    const tagStr = tags.length > 0 ? ` [${tags.join(', ')}]` : '';
+                    this.log(`  - ${snapshot.name} (${meta})${tagStr}`);
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.error(`Failed to list snapshots: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to list snapshots: ${String(error)}`);
+            }
+        }
+    }
+}

package/dist/commands/tenant/snapshot/swap/index.d.ts

@@ -0,0 +1,19 @@
+import BaseCommand from '../../../../base-command.js';
+export default class TenantSnapshotSwap extends BaseCommand {
+    static args: {
+        tenant_name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        snapshot: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private confirm;
+}

package/dist/commands/tenant/snapshot/swap/index.js

@@ -0,0 +1,103 @@
+import { Args, Flags } from '@oclif/core';
+import * as readline from 'node:readline';
+import BaseCommand from '../../../../base-command.js';
+export default class TenantSnapshotSwap extends BaseCommand {
+    static args = {
+        tenant_name: Args.string({
+            description: 'Tenant name to swap',
+            required: true,
+        }),
+    };
+    static description = "Swap a tenant's live database to a snapshot. This repoints the tenant; the current live database is left untouched, so you can swap back. To roll back, swap to the original database name.";
+    static examples = [
+        `$ xano tenant snapshot swap t1234-abcd-xyz1 --snapshot t1234-abcd-xyz1_bk_20260603_203614
+Swapped tenant t1234-abcd-xyz1 from t1234-abcd-xyz1 to t1234-abcd-xyz1_bk_20260603_203614
+`,
+        `$ xano tenant snapshot swap t1234-abcd-xyz1 --snapshot t1234-abcd-xyz1 --force`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        force: Flags.boolean({
+            char: 'f',
+            default: false,
+            description: 'Skips the confirmation prompt.',
+            required: false,
+        }),
+        output: Flags.string({
+            char: 'o',
+            default: 'summary',
+            description: 'Output format',
+            options: ['summary', 'json'],
+            required: false,
+        }),
+        snapshot: Flags.string({
+            description: 'Snapshot database name to swap to (use the original tenant name to roll back)',
+            required: true,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (uses profile workspace if not provided)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(TenantSnapshotSwap);
+        const { profile } = this.resolveProfile(flags);
+        const workspaceId = flags.workspace || profile.workspace;
+        if (!workspaceId) {
+            this.error('No workspace ID provided. Use --workspace flag or set one in your profile.');
+        }
+        const tenantName = args.tenant_name;
+        const { snapshot } = flags;
+        if (!flags.force) {
+            const confirmed = await this.confirm(`Swap tenant ${tenantName} to "${snapshot}"? This repoints the tenant's live database.`);
+            if (!confirmed) {
+                this.log('Swap cancelled.');
+                return;
+            }
+        }
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${tenantName}/snapshot/swap`;
+        try {
+            const response = await this.verboseFetch(apiUrl, {
+                body: JSON.stringify({ snapshot }),
+                headers: {
+                    'accept': 'application/json',
+                    'Authorization': `Bearer ${profile.access_token}`,
+                    'Content-Type': 'application/json',
+                },
+                method: 'POST',
+            }, flags.verbose, profile.access_token);
+            if (!response.ok) {
+                const errorText = await response.text();
+                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+            }
+            const result = (await response.json());
+            if (flags.output === 'json') {
+                this.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                this.log(`Swapped tenant ${tenantName} from ${result.from ?? 'unknown'} to ${result.to ?? snapshot}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.error(`Failed to swap snapshot: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to swap snapshot: ${String(error)}`);
+            }
+        }
+    }
+    async confirm(message) {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        return new Promise((resolve) => {
+            rl.question(`${message} (y/N) `, (answer) => {
+                rl.close();
+                resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+            });
+        });
+    }
+}

package/dist/utils/multidoc-push.js

@@ -645,18 +645,89 @@ export async function executePush(ctx, target, flags) {
     catch (error) {
         if (error instanceof Error && 'oclif' in error)
             throw error;
-        if (error instanceof Error) {
-            command.error(`Failed to push multidoc: ${error.message}`);
-        }
-        else {
-            command.error(`Failed to push multidoc: ${String(error)}`);
-        }
+        const elapsedMs = Date.now() - startTime;
+        command.error(`Failed to push multidoc: ${describeNetworkError(error, apiUrl, elapsedMs)}`);
     }
     const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
     const pushedCount = multidoc.split('\n---\n').length;
     log(`Pushed ${pushedCount} documents to ${target.label} from ${relative(process.cwd(), inputDir) || inputDir} in ${elapsed}s`);
 }
 // ── Error Handlers ──────────────────────────────────────────────────────────
+/**
+ * Turn a thrown fetch/network error into an actionable message.
+ *
+ * Node's native fetch throws a TypeError with the unhelpful message "fetch
+ * failed" for all transport-level failures (DNS, connection refused, TLS,
+ * resets, timeouts). The real reason lives in `error.cause` as a system error
+ * with a `code` (ECONNREFUSED, ENOTFOUND, ETIMEDOUT, etc.). This unwraps it so
+ * the user sees what actually went wrong and where.
+ *
+ * `elapsedMs` is appended so the user can see how long the request ran before
+ * failing — a failure landing near a round boundary (e.g. ~300s) is a strong
+ * signal of a server-side or proxy timeout rather than a local network blip.
+ */
+function describeNetworkError(error, url, elapsedMs) {
+    if (!(error instanceof Error))
+        return String(error);
+    let host = url;
+    try {
+        host = new URL(url).host;
+    }
+    catch { }
+    // AbortSignal.timeout() fires our explicit request-timeout ceiling.
+    if (error.name === 'TimeoutError' || error.name === 'AbortError') {
+        return `request to ${host} exceeded the CLI timeout. Raise it with XANO_CLI_REQUEST_TIMEOUT_MS (ms; 0 disables), or split the push into smaller batches.${formatFailureDuration(elapsedMs)}`;
+    }
+    const { cause } = error;
+    const code = cause && typeof cause === 'object' && 'code' in cause ? String(cause.code) : undefined;
+    const causeMessage = cause instanceof Error ? cause.message : undefined;
+    const hints = {
+        ECONNREFUSED: `Connection refused by ${host}. The instance may be down or starting up.`,
+        ECONNRESET: `Connection to ${host} was reset. The request may have been too large or the server restarted mid-push.`,
+        ENOTFOUND: `Could not resolve host "${host}". Check the instance origin and your network/DNS.`,
+        ETIMEDOUT: `Connection to ${host} timed out. Check your network or VPN, then retry.`,
+        UND_ERR_CONNECT_TIMEOUT: `Connection to ${host} timed out. Check your network or VPN, then retry.`,
+        UND_ERR_HEADERS_TIMEOUT: `${host} accepted the connection but did not respond in time. The push may be too large; try splitting it or retrying.`,
+    };
+    let base;
+    if (code && hints[code]) {
+        base = `${hints[code]} (${code})`;
+    }
+    else if (code?.startsWith('ERR_TLS') || code?.startsWith('CERT_') || /certificate|tls|ssl/i.test(error.message)) {
+        // TLS/cert failures surface their reason on the cause message.
+        base = `TLS/certificate error connecting to ${host}: ${causeMessage ?? error.message}`;
+    }
+    else if (error.message === 'fetch failed') {
+        // "fetch failed" with no recognized code — surface the underlying cause if any.
+        base = causeMessage
+            ? `network error connecting to ${host}: ${causeMessage}${code ? ` (${code})` : ''}`
+            : `network error connecting to ${host}${code ? ` (${code})` : ''}. Run with --verbose for more detail.`;
+    }
+    else {
+        base = error.message;
+    }
+    return base + formatFailureDuration(elapsedMs);
+}
+/**
+ * Render how long the request ran before failing, e.g. " (after 5m 0s)".
+ * Flags durations sitting near a common timeout boundary (30/60/120/300/600s),
+ * which usually points at a server-side or proxy/load-balancer timeout rather
+ * than a local network problem.
+ */
+function formatFailureDuration(elapsedMs) {
+    if (elapsedMs === undefined || elapsedMs < 0)
+        return '';
+    const totalSeconds = elapsedMs / 1000;
+    const human = totalSeconds < 60
+        ? `${totalSeconds.toFixed(1)}s`
+        : `${Math.floor(totalSeconds / 60)}m ${Math.round(totalSeconds % 60)}s`;
+    // Within 5% of a common timeout boundary → likely a hard cutoff, not a blip.
+    const boundaries = [30, 60, 120, 300, 600];
+    const nearTimeout = boundaries.some((b) => Math.abs(totalSeconds - b) <= b * 0.05);
+    return nearTimeout
+        ? ` (failed after ~${human}, near a common ${boundaries.find((b) => Math.abs(totalSeconds - b) <= b * 0.05)}s timeout — likely a server or proxy cutoff)`
+        : ` (failed after ${human})`;
+}
 async function handleDryRunError(response, command, flags, target) {
     const log = command.log.bind(command);
     if (response.status === 404) {