@xano/cli 1.0.6-beta.0 → 1.0.6-beta.10

package/dist/commands/ephemeral/push/index.js

@@ -1,31 +1,38 @@
-import { Flags } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 import * as fs from 'node:fs';
 import { resolve } from 'node:path';
 import BaseCommand from '../../../base-command.js';
+import { isAwaited, waitForMicroservices, } from '../../../utils/microservice-wait.js';
 import { executePush } from '../../../utils/multidoc-push.js';
 export default class EphemeralPush extends BaseCommand {
+    static args = {
+        tenant_name: Args.string({
+            description: 'Ephemeral tenant name to push to',
+            required: true,
+        }),
+    };
     static description = '[IMPORTANT] ALWAYS run --dry-run first and show the user the output before pushing. Push local documents to an ephemeral tenant via multidoc import. By default, only changed files are pushed (partial mode). Use --sync to push all files. Shows a preview of changes before pushing unless --force is specified. Use --dry-run to preview only.';
     static examples = [
-        `$ xano ephemeral push -t e4f2-9ab1-xyz1
+        `$ xano ephemeral push e4f2-9ab1-xyz1
 Push from current directory (default partial mode)
 `,
-        `$ xano ephemeral push -t e4f2-9ab1-xyz1 -d ./my-workspace
+        `$ xano ephemeral push e4f2-9ab1-xyz1 -d ./my-workspace
 Push from a specific directory
 `,
-        `$ xano ephemeral push -t e4f2-9ab1-xyz1 --sync
+        `$ xano ephemeral push e4f2-9ab1-xyz1 --sync
 Push all files to the ephemeral tenant
 `,
-        `$ xano ephemeral push -t e4f2-9ab1-xyz1 --sync --delete
+        `$ xano ephemeral push e4f2-9ab1-xyz1 --sync --delete
 Push all files and delete remote objects not included
 `,
-        `$ xano ephemeral push -t e4f2-9ab1-xyz1 --dry-run
+        `$ xano ephemeral push e4f2-9ab1-xyz1 --dry-run
 Preview changes without pushing
 `,
-        `$ xano ephemeral push -t e4f2-9ab1-xyz1 --force
+        `$ xano ephemeral push e4f2-9ab1-xyz1 --force
 Skip preview and push immediately
 `,
-        `$ xano ephemeral push -t e4f2-9ab1-xyz1 --records --env`,
-        `$ xano ephemeral push -t e4f2-9ab1-xyz1 --truncate`,
+        `$ xano ephemeral push e4f2-9ab1-xyz1 --records --env`,
+        `$ xano ephemeral push e4f2-9ab1-xyz1 --truncate`,
     ];
     static flags = {
         ...BaseCommand.baseFlags,
@@ -71,11 +78,6 @@ Skip preview and push immediately
             description: 'Full push — send all files, not just changed ones. Required for --delete.',
             required: false,
         }),
-        tenant: Flags.string({
-            char: 't',
-            description: 'Ephemeral tenant name to push to',
-            required: true,
-        }),
         transaction: Flags.boolean({
             allowNo: true,
             default: true,
@@ -87,6 +89,17 @@ Skip preview and push immediately
             description: '[CRITICAL] STOP and confirm with the user; this truncates live tables before importing.',
             required: false,
         }),
+        wait: Flags.boolean({
+            default: false,
+            description: 'After pushing, wait for auto-deployed microservices (tenant_deploy="auto") to become ready. Exits non-zero if any fails to deploy or the wait times out. Ignored with --dry-run.',
+            required: false,
+        }),
+        'wait-timeout': Flags.integer({
+            default: 300,
+            description: 'Seconds to wait for microservices to become ready when --wait is set (default 300).',
+            min: 1,
+            required: false,
+        }),
         workspace: Flags.string({
             char: 'w',
             description: 'Workspace ID (uses profile workspace if not provided)',
@@ -94,7 +107,7 @@ Skip preview and push immediately
         }),
     };
     async run() {
-        const { flags } = await this.parse(EphemeralPush);
+        const { args, flags } = await this.parse(EphemeralPush);
         const { profile } = this.resolveProfile(flags);
         const workspaceId = flags.workspace || profile.workspace;
         if (!workspaceId) {
@@ -107,7 +120,7 @@ Skip preview and push immediately
         if (!fs.statSync(inputDir).isDirectory()) {
             this.error(`Not a directory: ${inputDir}`);
         }
-        const tenantName = flags.tenant;
+        const tenantName = args.tenant_name;
         const baseUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${tenantName}`;
         const target = {
             buildDryRunUrl: (params) => `${baseUrl}/multidoc/dry-run?${params.toString()}`,
@@ -139,5 +152,70 @@ Skip preview and push immediately
             inputDir,
             verboseFetch: this.verboseFetch.bind(this),
         }, target, pushFlags);
+        // --wait: after a real push, poll the tenant's live microservice status until
+        // every auto-deployed microservice (tenant_deploy="auto") is ready or the
+        // wait times out. Skipped on --dry-run (nothing was deployed).
+        if (flags.wait && !flags['dry-run']) {
+            await this.waitForDeploy(baseUrl, profile.access_token, tenantName, flags['wait-timeout'], flags.verbose);
+        }
+    }
+    /**
+     * Poll GET .../tenant/{name}/microservice until auto microservices settle.
+     * Renders a one-line-per-microservice progress view that updates in place, then
+     * exits non-zero if any auto microservice failed or the wait timed out.
+     */
+    async waitForDeploy(baseUrl, accessToken, tenantName, timeoutSeconds, verbose) {
+        this.log('');
+        this.log(`Waiting for microservices to deploy (timeout ${timeoutSeconds}s)…`);
+        const icon = (e) => {
+            if (!isAwaited(e))
+                return '➖';
+            switch (e.status) {
+                case 'error': {
+                    return '❌';
+                }
+                case 'ok': {
+                    return '✅';
+                }
+                default: {
+                    return '⏳';
+                }
+            }
+        };
+        const line = (e) => {
+            const detail = isAwaited(e) ? e.detail || e.status : `skipped (${e.tenant_deploy ?? 'manual'})`;
+            return `  ${icon(e)} ${e.name.padEnd(24)} ${detail}`;
+        };
+        const result = await waitForMicroservices({
+            accessToken,
+            onPoll: (entries) => {
+                // Re-render the block: move the cursor up over the previous render (if any)
+                // and rewrite. Falls back to plain appends when not a TTY.
+                if (process.stdout.isTTY && this.lastRenderLines > 0) {
+                    process.stdout.write(`[${this.lastRenderLines}A`);
+                }
+                const lines = entries.map((e) => line(e));
+                for (const l of lines)
+                    this.log(l);
+                this.lastRenderLines = process.stdout.isTTY ? lines.length : 0;
+            },
+            statusUrl: `${baseUrl}/microservice`,
+            timeoutMs: timeoutSeconds * 1000,
+            verbose,
+            verboseFetch: this.verboseFetch.bind(this),
+        });
+        const awaited = result.entries.filter((e) => isAwaited(e));
+        const ready = awaited.filter((e) => e.status === 'ok').length;
+        if (result.timedOut) {
+            this.error(`Timed out after ${timeoutSeconds}s waiting for microservices (${ready}/${awaited.length} ready). ` +
+                `Check status with the Xano dashboard or re-run with a larger --wait-timeout.`);
+        }
+        if (result.hadError) {
+            const failed = awaited.filter((e) => e.status === 'error').map((e) => `${e.name} (${e.detail || 'error'})`);
+            this.error(`Microservice deploy failed: ${failed.join(', ')}`);
+        }
+        this.log(`All microservices ready (${ready}/${awaited.length}).`);
     }
+    /** Number of lines the last progress render wrote (for in-place TTY updates). */
+    lastRenderLines = 0;
 }

package/dist/commands/ephemeral/static_host/build/delete/index.d.ts

@@ -0,0 +1,20 @@
+import BaseCommand from '../../../../../base-command.js';
+export default class EphemeralStaticHostBuildDelete extends BaseCommand {
+    static args: {
+        tenant_name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        build_id: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'static-host': 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/ephemeral/static_host/build/delete/index.js

@@ -0,0 +1,121 @@
+import { Args, Flags } from '@oclif/core';
+import BaseCommand from '../../../../../base-command.js';
+export default class EphemeralStaticHostBuildDelete extends BaseCommand {
+    static args = {
+        tenant_name: Args.string({
+            description: 'Ephemeral tenant name',
+            required: true,
+        }),
+    };
+    static description = 'Delete a static host build for an ephemeral tenant permanently. This action cannot be undone.';
+    static examples = [
+        `$ xano ephemeral static_host build delete e4f2-9ab1-xyz1 --static-host default --build_id 52
+Are you sure you want to delete build 52 from static host 'default'? This action cannot be undone. (y/N) y
+Deleted build 52 from static host 'default'
+`,
+        `$ xano ephemeral static_host build delete e4f2-9ab1-xyz1 -H default --build_id 52 --force
+Deleted build 52 from static host 'default'
+`,
+        `$ xano ephemeral static_host build delete e4f2-9ab1-xyz1 -H myhost --build_id 123 -w 40 -f
+Deleted build 123 from static host 'myhost'
+`,
+        `$ xano ephemeral static_host build delete e4f2-9ab1-xyz1 -H default --build_id 52 -f -o json`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        build_id: Flags.string({
+            description: 'Build ID to delete',
+            required: true,
+        }),
+        force: Flags.boolean({
+            char: 'f',
+            default: false,
+            description: '[CRITICAL] NEVER run without explicit user confirmation. Skips the confirmation prompt.',
+            required: false,
+        }),
+        output: Flags.string({
+            char: 'o',
+            default: 'summary',
+            description: 'Output format',
+            options: ['summary', 'json'],
+            required: false,
+        }),
+        'static-host': Flags.string({
+            char: 'H',
+            description: 'Static host name',
+            required: true,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (optional if set in profile)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(EphemeralStaticHostBuildDelete);
+        const { profile, profileName } = this.resolveProfile(flags);
+        const tenantName = args.tenant_name;
+        const staticHost = flags['static-host'];
+        // Determine workspace_id from flag or profile
+        let workspaceId;
+        if (flags.workspace) {
+            workspaceId = flags.workspace;
+        }
+        else if (profile.workspace) {
+            workspaceId = profile.workspace;
+        }
+        else {
+            this.error(`Workspace ID is required. Either:\n` +
+                `  1. Provide it as a flag: xano ephemeral static_host build delete <tenant_name> --static-host <static_host> --build_id <id> -w <workspace_id>\n` +
+                `  2. Set it in your profile using: xano profile edit ${profileName} -w <workspace_id>`);
+        }
+        if (!flags.force) {
+            const confirmed = await this.confirm(`Are you sure you want to delete build ${flags.build_id} from static host '${staticHost}'? This action cannot be undone.`);
+            if (!confirmed) {
+                this.log('Deletion cancelled.');
+                return;
+            }
+        }
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${tenantName}/static_host/${staticHost}/build/${flags.build_id}`;
+        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({ build_id: flags.build_id, deleted: true, static_host: staticHost }, null, 2));
+            }
+            else {
+                this.log(`Deleted build ${flags.build_id} from static host '${staticHost}'`);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.error(`Failed to delete build: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to delete build: ${String(error)}`);
+            }
+        }
+    }
+    async confirm(message) {
+        const readline = await import('node:readline');
+        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/ephemeral/static_host/build/get/index.d.ts

@@ -0,0 +1,18 @@
+import BaseCommand from '../../../../../base-command.js';
+export default class EphemeralStaticHostBuildGet extends BaseCommand {
+    static args: {
+        tenant_name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        build_id: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'static-host': 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/ephemeral/static_host/build/get/index.js

@@ -0,0 +1,137 @@
+import { Args, Flags } from '@oclif/core';
+import BaseCommand from '../../../../../base-command.js';
+export default class EphemeralStaticHostBuildGet extends BaseCommand {
+    static args = {
+        tenant_name: Args.string({
+            description: 'Ephemeral tenant name',
+            required: true,
+        }),
+    };
+    static description = 'Get details of a specific build for a static host of an ephemeral tenant';
+    static examples = [
+        `$ xano ephemeral static_host build get e4f2-9ab1-xyz1 --static-host default --build_id 52
+Build Details:
+ID: 52
+Name: v1.0.0
+Status: completed
+`,
+        `$ xano ephemeral static_host build get e4f2-9ab1-xyz1 -H default --build_id 52 -w 40
+Build Details:
+ID: 52
+Name: v1.0.0
+Status: completed
+`,
+        `$ xano ephemeral static_host build get e4f2-9ab1-xyz1 -H myhost --build_id 123 --profile production
+Build Details:
+ID: 123
+Name: production-build
+`,
+        `$ xano ephemeral static_host build get e4f2-9ab1-xyz1 -H default --build_id 52 -o json
+{
+  "id": 52,
+  "name": "v1.0.0",
+  "status": "completed"
+}
+`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        build_id: Flags.string({
+            description: 'Build ID',
+            required: true,
+        }),
+        output: Flags.string({
+            char: 'o',
+            default: 'summary',
+            description: 'Output format',
+            options: ['summary', 'json'],
+            required: false,
+        }),
+        'static-host': Flags.string({
+            char: 'H',
+            description: 'Static host name',
+            required: true,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (optional if set in profile)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(EphemeralStaticHostBuildGet);
+        const { profile, profileName } = this.resolveProfile(flags);
+        const tenantName = args.tenant_name;
+        const staticHost = flags['static-host'];
+        // Determine workspace_id from flag or profile
+        let workspaceId;
+        if (flags.workspace) {
+            workspaceId = flags.workspace;
+        }
+        else if (profile.workspace) {
+            workspaceId = profile.workspace;
+        }
+        else {
+            this.error(`Workspace ID is required. Either:\n` +
+                `  1. Provide it as a flag: xano ephemeral static_host build get <tenant_name> --static-host <static_host> --build_id <id> -w <workspace_id>\n` +
+                `  2. Set it in your profile using: xano profile:edit ${profileName} -w <workspace_id>`);
+        }
+        // Construct the API URL
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${tenantName}/static_host/${staticHost}/build/${flags.build_id}`;
+        // Fetch build from the API
+        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 build = await response.json();
+            // Validate response
+            if (!build || typeof build !== 'object') {
+                this.error('Unexpected API response format');
+            }
+            // Output results
+            if (flags.output === 'json') {
+                this.log(JSON.stringify(build, null, 2));
+            }
+            else {
+                // summary format
+                this.log('Build Details:');
+                this.log(`ID: ${build.id}`);
+                this.log(`Name: ${build.name}`);
+                if (build.description) {
+                    this.log(`Description: ${build.description}`);
+                }
+                if (build.status) {
+                    this.log(`Status: ${build.status}`);
+                }
+                if (typeof build.file_count === 'number') {
+                    this.log(`Files: ${build.file_count}`);
+                }
+                if (typeof build.file_bytes === 'number') {
+                    this.log(`Size: ${build.file_bytes} bytes`);
+                }
+                if (build.created_at) {
+                    this.log(`Created: ${build.created_at}`);
+                }
+                if (build.updated_at) {
+                    this.log(`Updated: ${build.updated_at}`);
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.error(`Failed to fetch build: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to fetch build: ${String(error)}`);
+            }
+        }
+    }
+}

package/dist/commands/ephemeral/static_host/build/list/index.d.ts

@@ -0,0 +1,18 @@
+import BaseCommand from '../../../../../base-command.js';
+export default class EphemeralStaticHostBuildList extends BaseCommand {
+    static args: {
+        tenant_name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'static-host': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        page: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, 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/ephemeral/static_host/build/list/index.js

@@ -0,0 +1,137 @@
+import { Args, Flags } from '@oclif/core';
+import BaseCommand from '../../../../../base-command.js';
+import { buildPagingJson, buildPagingParams, formatPagingFooter, normalizeListResponse, pagingFlags } from '../../../../../utils/paging.js';
+export default class EphemeralStaticHostBuildList extends BaseCommand {
+    static args = {
+        tenant_name: Args.string({
+            description: 'Ephemeral tenant name',
+            required: true,
+        }),
+    };
+    static description = 'List all builds for a static host of an ephemeral tenant';
+    static examples = [
+        `$ xano ephemeral static_host build list e4f2-9ab1-xyz1 --static-host default -w 40
+Available builds:
+  - v1.0.0 (ID: 1) - Status: completed
+  - v1.0.1 (ID: 2) - Status: pending
+`,
+        `$ xano ephemeral static_host build list e4f2-9ab1-xyz1 -H myhost --profile production
+Available builds:
+  - production (ID: 1) - Status: completed
+  - staging (ID: 2) - Status: completed
+`,
+        `$ xano ephemeral static_host build list e4f2-9ab1-xyz1 -H default -w 40 --output json
+{
+  "count": 1,
+  "page": 1,
+  "total": 12,
+  "items": [
+    {
+      "id": 52
+    }
+  ]
+}
+`,
+        `$ xano ephemeral static_host build list e4f2-9ab1-xyz1 -H default -p staging -o json --page 2
+[
+  {
+    "id": 3,
+    "name": "v1.0.2"
+  }
+]
+`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        output: Flags.string({
+            char: 'o',
+            default: 'summary',
+            description: 'Output format',
+            options: ['summary', 'json'],
+            required: false,
+        }),
+        ...pagingFlags('page-only-envelope', { fixedPerPage: 100 }),
+        'static-host': Flags.string({
+            char: 'H',
+            description: 'Static host name',
+            required: true,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (optional if set in profile)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(EphemeralStaticHostBuildList);
+        const { profile, profileName } = this.resolveProfile(flags);
+        const tenantName = args.tenant_name;
+        const staticHost = flags['static-host'];
+        // Determine workspace_id from flag or profile
+        let workspaceId;
+        if (flags.workspace) {
+            workspaceId = flags.workspace;
+        }
+        else if (profile.workspace) {
+            workspaceId = profile.workspace;
+        }
+        else {
+            this.error(`Workspace ID is required. Either:\n` +
+                `  1. Provide it as a flag: xano ephemeral static_host build list <tenant_name> --static-host <static_host> -w <workspace_id>\n` +
+                `  2. Set it in your profile using: xano profile:edit ${profileName} -w <workspace_id>`);
+        }
+        // Build query parameters
+        const queryParams = new URLSearchParams(buildPagingParams(flags, 'page-only-envelope'));
+        // Construct the API URL
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${tenantName}/static_host/${staticHost}/build?${queryParams.toString()}`;
+        // Fetch builds from the API
+        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 list = normalizeListResponse(await response.json(), ['builds']);
+            const builds = list.items;
+            // Output results
+            if (flags.output === 'json') {
+                this.log(JSON.stringify(buildPagingJson(list, { page: flags.page, tier: 'page-only-envelope' }), null, 2));
+            }
+            else {
+                // summary format
+                if (builds.length === 0) {
+                    this.log('No builds found');
+                }
+                else {
+                    this.log('Available builds:');
+                    for (const build of builds) {
+                        if (build.id === undefined) {
+                            this.log(`  - ${build.name}`);
+                        }
+                        else {
+                            const statusInfo = build.status ? ` - Status: ${build.status}` : '';
+                            this.log(`  - ${build.name} (ID: ${build.id})${statusInfo}`);
+                        }
+                    }
+                }
+                const footer = formatPagingFooter(list, { noun: 'build', page: flags.page, tier: 'page-only-envelope' });
+                if (footer)
+                    this.log(footer);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.error(`Failed to fetch builds: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to fetch builds: ${String(error)}`);
+            }
+        }
+    }
+}

package/dist/commands/ephemeral/static_host/build/pull/index.d.ts

@@ -0,0 +1,53 @@
+import BaseCommand from '../../../../../base-command.js';
+export interface StaticHostEnv {
+    canonical?: null | string;
+}
+export interface StaticHostSummary {
+    [k: string]: unknown;
+    dev?: StaticHostEnv;
+    name: string;
+    prod?: StaticHostEnv;
+}
+export interface BuildSummary {
+    canonical?: string;
+    id: number;
+}
+/**
+ * Find the deployed `canonical` for a static host's env from a list of hosts.
+ * Returns null when the host isn't present or nothing is deployed to that env.
+ */
+export declare function extractEnvCanonical(hosts: StaticHostSummary[], staticHost: string, env: string): null | string;
+/** Find the build whose unique `canonical` matches, or null if none do. */
+export declare function findBuildByCanonical(builds: BuildSummary[], canonical: string): BuildSummary | null;
+export default class EphemeralStaticHostBuildPull extends BaseCommand {
+    static args: {
+        tenant_name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        build_id: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        directory: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        env: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        latest: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        source: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'static-host': 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 parseFileDocument;
+    /**
+     * Resolve the build ID currently deployed to a static host's dev/prod env.
+     *
+     * The deployed env stores the `canonical` of the build it was created from
+     * (static_host.{env}.canonical). Each build carries that same unique
+     * `canonical`, so we match the env's canonical against the build list to
+     * recover the build ID — a shortcut for "list builds, find the deployed one,
+     * then pull it".
+     */
+    private resolveEnvBuild;
+    private resolveLatestBuild;
+}