@xano/cli 1.0.5 → 1.0.6-beta.0

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

@@ -0,0 +1,112 @@
+import { Args, Flags } from '@oclif/core';
+import open from 'open';
+import BaseCommand from '../../../base-command.js';
+export default class EphemeralImpersonate extends BaseCommand {
+    static args = {
+        tenant_name: Args.string({
+            description: 'Ephemeral tenant name to impersonate',
+            required: true,
+        }),
+    };
+    static description = 'Impersonate an ephemeral tenant and open it in the browser';
+    static examples = [
+        `$ xano ephemeral impersonate e4f2-9ab1-xyz1
+Opening browser...
+Impersonation successful!
+`,
+        `$ xano ephemeral impersonate e4f2-9ab1-xyz1 -o json`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        output: Flags.string({
+            char: 'o',
+            default: 'summary',
+            description: 'Output format',
+            options: ['summary', 'json'],
+            required: false,
+        }),
+        'url-only': Flags.boolean({
+            char: 'u',
+            default: false,
+            description: 'Print the URL without opening the browser',
+            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(EphemeralImpersonate);
+        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;
+        try {
+            const response = await this.getImpersonateResponse(profile, workspaceId, tenantName);
+            if (flags.output === 'json') {
+                this.log(JSON.stringify(response, null, 2));
+            }
+            else {
+                const frontendUrl = this.getFrontendUrl(profile.instance_origin);
+                const params = new URLSearchParams({
+                    _ti: response._ti,
+                });
+                const impersonateUrl = `${frontendUrl}/impersonate?${params.toString()}`;
+                if (flags['url-only']) {
+                    this.log(impersonateUrl);
+                }
+                else {
+                    this.log('Opening browser...');
+                    await open(impersonateUrl);
+                    this.log('Impersonation successful!');
+                }
+            }
+            process.exit(0);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.error(`Failed to impersonate tenant: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to impersonate tenant: ${String(error)}`);
+            }
+        }
+    }
+    async getImpersonateResponse(profile, workspaceId, tenantName) {
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${encodeURIComponent(tenantName)}/impersonate`;
+        const { verbose } = await this.parse(EphemeralImpersonate).then((r) => r.flags);
+        const response = await this.verboseFetch(apiUrl, {
+            headers: {
+                Authorization: `Bearer ${profile.access_token}`,
+                accept: 'application/json',
+            },
+            method: 'GET',
+        }, verbose, profile.access_token);
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+        }
+        const result = (await response.json());
+        if (!result._ti) {
+            throw new Error('No one-time token returned from impersonate API');
+        }
+        return result;
+    }
+    getFrontendUrl(instanceOrigin) {
+        try {
+            const url = new URL(instanceOrigin);
+            if (url.hostname === 'localhost' || url.hostname === '127.0.0.1') {
+                url.port = '4200';
+                return url.origin;
+            }
+        }
+        catch {
+            // fall through
+        }
+        return instanceOrigin;
+    }
+}

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

@@ -0,0 +1,19 @@
+import BaseCommand from '../../../base-command.js';
+export default class EphemeralList extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        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>;
+    /**
+     * Render a unix-epoch-seconds expiration as a human-readable "in Xh Ym" string,
+     * falling back to an ISO timestamp if the value has already passed or is malformed.
+     */
+    private formatExpiration;
+}

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

@@ -0,0 +1,122 @@
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../../base-command.js';
+export default class EphemeralList extends BaseCommand {
+    static description = 'List ephemeral tenants in a workspace, or across the whole instance with --global';
+    static examples = [
+        `$ xano ephemeral list
+Ephemeral tenants in workspace 5:
+  - PR preview (e4f2-9ab1-...) [ok] - expires in 1h 0m
+  - Demo (e7a3-2c10-...) [ok] - expires in 23h 12m
+`,
+        `$ xano ephemeral list --global
+Ephemeral tenants (all workspaces):
+  - PR preview (e4f2-9ab1-...) [ok] - expires in 1h 0m
+`,
+        `$ xano ephemeral list -w 5 -o json`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        global: Flags.boolean({
+            default: false,
+            description: 'List ephemeral tenants across the whole instance (all workspaces)',
+            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 { flags } = await this.parse(EphemeralList);
+        const { profile } = this.resolveProfile(flags);
+        let workspaceId;
+        let apiUrl;
+        if (flags.global) {
+            apiUrl = `${profile.instance_origin}/api:meta/ephemeral`;
+        }
+        else {
+            workspaceId = flags.workspace || profile.workspace;
+            if (!workspaceId) {
+                this.error('No workspace ID provided. Use --workspace flag or set one in your profile.');
+            }
+            apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/ephemeral`;
+        }
+        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 tenants;
+            if (Array.isArray(data)) {
+                tenants = data;
+            }
+            else if (data && typeof data === 'object' && Array.isArray(data.items)) {
+                tenants = data.items;
+            }
+            else {
+                this.error('Unexpected API response format');
+            }
+            if (flags.output === 'json') {
+                this.log(JSON.stringify(tenants, null, 2));
+            }
+            else if (tenants.length === 0) {
+                this.log('No ephemeral tenants found');
+            }
+            else {
+                this.log(flags.global ? 'Ephemeral tenants (all workspaces):' : `Ephemeral tenants in workspace ${workspaceId}:`);
+                for (const tenant of tenants) {
+                    const state = tenant.state ? ` [${tenant.state}]` : '';
+                    const expires = ` - expires ${this.formatExpiration(tenant.ephemeral_expires_at)}`;
+                    const workspaceLabel = flags.global && tenant.workspace_id ? ` (workspace ${tenant.workspace_id})` : '';
+                    this.log(`  - ${tenant.display || tenant.name} (${tenant.name})${state}${expires}${workspaceLabel}`);
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.error(`Failed to list ephemeral tenants: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to list ephemeral tenants: ${String(error)}`);
+            }
+        }
+    }
+    /**
+     * Render a unix-epoch-seconds expiration as a human-readable "in Xh Ym" string,
+     * falling back to an ISO timestamp if the value has already passed or is malformed.
+     */
+    formatExpiration(expiresAt) {
+        if (!expiresAt) {
+            return '-';
+        }
+        // The API serializes the timestamp field as a date string
+        // ("2026-07-24 19:49:15+0000"); tolerate a raw unix-epoch number too.
+        const expiresMs = typeof expiresAt === 'number' ? expiresAt * 1000 : Date.parse(String(expiresAt).replace(' ', 'T'));
+        if (Number.isNaN(expiresMs)) {
+            return String(expiresAt);
+        }
+        const diffSeconds = (expiresMs - Date.now()) / 1000;
+        if (diffSeconds <= 0) {
+            return `${new Date(expiresMs).toISOString()} (expired)`;
+        }
+        const hours = Math.floor(diffSeconds / 3600);
+        const minutes = Math.floor((diffSeconds % 3600) / 60);
+        return `in ${hours}h ${minutes}m`;
+    }
+}

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

@@ -0,0 +1,23 @@
+import BaseCommand from '../../../base-command.js';
+export default class EphemeralPull extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        directory: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        draft: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        env: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        records: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        tenant: 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>;
+    /**
+     * Sanitize a document name for use as a filename.
+     * Strips quotes, replaces spaces with underscores, and removes
+     * characters that are unsafe in filenames.
+     */
+    private sanitizeFilename;
+}

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

@@ -0,0 +1,248 @@
+import { Flags } from '@oclif/core';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import snakeCase from 'lodash.snakecase';
+import BaseCommand from '../../../base-command.js';
+import { buildApiGroupFolderResolver, parseDocument } from '../../../utils/document-parser.js';
+export default class EphemeralPull extends BaseCommand {
+    static description = 'Pull an ephemeral tenant multidoc from the Xano Metadata API and split into individual files';
+    static examples = [
+        `$ xano ephemeral pull -t e4f2-9ab1-xyz1
+Pulled 42 documents from tenant e4f2-9ab1-xyz1 to current directory
+`,
+        `$ xano ephemeral pull -d ./my-tenant -t e4f2-9ab1-xyz1
+Pulled 42 documents from tenant e4f2-9ab1-xyz1 to ./my-tenant
+`,
+        `$ xano ephemeral pull -d ./output -t e4f2-9ab1-xyz1 -w 40
+Pulled 15 documents from tenant e4f2-9ab1-xyz1 to ./output
+`,
+        `$ xano ephemeral pull -t e4f2-9ab1-xyz1 --profile production --env --records
+Pulled 58 documents from tenant e4f2-9ab1-xyz1
+`,
+        `$ xano ephemeral pull -t e4f2-9ab1-xyz1 --draft`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        directory: Flags.string({
+            char: 'd',
+            default: '.',
+            description: 'Output directory for pulled documents (defaults to current directory)',
+            required: false,
+        }),
+        draft: Flags.boolean({
+            default: false,
+            description: 'Include draft versions',
+            required: false,
+        }),
+        env: Flags.boolean({
+            default: false,
+            description: 'Include environment variables',
+            required: false,
+        }),
+        records: Flags.boolean({
+            default: false,
+            description: 'Include records',
+            required: false,
+        }),
+        tenant: Flags.string({
+            char: 't',
+            description: 'Ephemeral tenant name to pull from',
+            required: true,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (optional if set in profile)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(EphemeralPull);
+        const { profileName, profile } = this.resolveProfile(flags);
+        // 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 pull -t <tenant_name> -w <workspace_id>\n` +
+                `  2. Set it in your profile using: xano profile:edit ${profileName} -w <workspace_id>`);
+        }
+        const tenantName = flags.tenant;
+        // Build query parameters
+        const queryParams = new URLSearchParams({
+            env: flags.env.toString(),
+            include_draft: flags.draft.toString(),
+            records: flags.records.toString(),
+        });
+        // Construct the API URL
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${tenantName}/multidoc?${queryParams.toString()}`;
+        // Fetch multidoc from the API
+        let responseText;
+        const requestHeaders = {
+            accept: 'application/json',
+            Authorization: `Bearer ${profile.access_token}`,
+        };
+        try {
+            const response = await this.verboseFetch(apiUrl, {
+                headers: requestHeaders,
+                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}`);
+            }
+            responseText = await response.text();
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.error(`Failed to fetch multidoc: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to fetch multidoc: ${String(error)}`);
+            }
+        }
+        // Split the response into individual documents
+        const rawDocuments = responseText.split('\n---\n');
+        // Parse each document
+        const documents = [];
+        for (const raw of rawDocuments) {
+            const trimmed = raw.trim();
+            if (!trimmed) {
+                continue;
+            }
+            const parsed = parseDocument(trimmed);
+            if (parsed) {
+                documents.push(parsed);
+            }
+        }
+        if (documents.length === 0) {
+            this.log('No documents found in response');
+            return;
+        }
+        // Resolve the output directory
+        const outputDir = path.resolve(flags.directory);
+        // Create the output directory if it doesn't exist
+        fs.mkdirSync(outputDir, { recursive: true });
+        // Resolve api_group names to unique folder names, disambiguating collisions
+        const getApiGroupFolder = buildApiGroupFolderResolver(documents, snakeCase);
+        // Track filenames per type to handle duplicates
+        const filenameCounters = new Map();
+        let writtenCount = 0;
+        for (const doc of documents) {
+            let typeDir;
+            let baseName;
+            if (doc.type === 'workspace') {
+                // workspace → workspace/{name}.xs
+                typeDir = path.join(outputDir, 'workspace');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'workspace_trigger') {
+                // workspace_trigger → workspace/trigger/{name}.xs
+                typeDir = path.join(outputDir, 'workspace', 'trigger');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'error_trigger') {
+                // error_trigger → workspace/trigger/{name}.xs (singleton, colocated with workspace triggers)
+                typeDir = path.join(outputDir, 'workspace', 'trigger');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'agent') {
+                // agent → ai/agent/{name}.xs
+                typeDir = path.join(outputDir, 'ai', 'agent');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'mcp_server') {
+                // mcp_server → ai/mcp_server/{name}.xs
+                typeDir = path.join(outputDir, 'ai', 'mcp_server');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'tool') {
+                // tool → ai/tool/{name}.xs
+                typeDir = path.join(outputDir, 'ai', 'tool');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'agent_trigger') {
+                // agent_trigger → ai/agent/trigger/{name}.xs
+                typeDir = path.join(outputDir, 'ai', 'agent', 'trigger');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'mcp_server_trigger') {
+                // mcp_server_trigger → ai/mcp_server/trigger/{name}.xs
+                typeDir = path.join(outputDir, 'ai', 'mcp_server', 'trigger');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'table_trigger') {
+                // table_trigger → table/trigger/{name}.xs
+                typeDir = path.join(outputDir, 'table', 'trigger');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'realtime_channel') {
+                // realtime_channel → realtime/channel/{name}.xs
+                typeDir = path.join(outputDir, 'realtime', 'channel');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'realtime_trigger') {
+                // realtime_trigger → realtime/trigger/{name}.xs
+                typeDir = path.join(outputDir, 'realtime', 'trigger');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'api_group') {
+                // api_group "test" → api/{resolved_folder}/{name}.xs
+                const groupFolder = getApiGroupFolder(doc.name);
+                typeDir = path.join(outputDir, 'api', groupFolder);
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'query' && doc.apiGroup) {
+                // query in group "test" → api/{resolved_folder}/{query_name}.xs
+                const groupFolder = getApiGroupFolder(doc.apiGroup);
+                const nameParts = doc.name.split('/');
+                const leafName = nameParts.pop();
+                const folderParts = nameParts.map((part) => snakeCase(part));
+                typeDir = path.join(outputDir, 'api', groupFolder, ...folderParts);
+                baseName = this.sanitizeFilename(leafName);
+                if (doc.verb) {
+                    baseName = `${baseName}_${doc.verb}`;
+                }
+            }
+            else {
+                // Default: split folder path from name
+                const nameParts = doc.name.split('/');
+                const leafName = nameParts.pop();
+                const folderParts = nameParts.map((part) => snakeCase(part));
+                typeDir = path.join(outputDir, doc.type, ...folderParts);
+                baseName = this.sanitizeFilename(leafName);
+                if (doc.verb) {
+                    baseName = `${baseName}_${doc.verb}`;
+                }
+            }
+            fs.mkdirSync(typeDir, { recursive: true });
+            // Track duplicates per directory
+            const dirKey = path.relative(outputDir, typeDir);
+            if (!filenameCounters.has(dirKey)) {
+                filenameCounters.set(dirKey, new Map());
+            }
+            const typeCounters = filenameCounters.get(dirKey);
+            const count = typeCounters.get(baseName) || 0;
+            typeCounters.set(baseName, count + 1);
+            // Append numeric suffix for duplicates
+            let filename;
+            filename = count === 0 ? `${baseName}.xs` : `${baseName}_${count + 1}.xs`;
+            const filePath = path.join(typeDir, filename);
+            fs.writeFileSync(filePath, doc.content, 'utf8');
+            writtenCount++;
+        }
+        this.log(`Pulled ${writtenCount} documents from tenant ${tenantName} to ${flags.directory}`);
+    }
+    /**
+     * Sanitize a document name for use as a filename.
+     * Strips quotes, replaces spaces with underscores, and removes
+     * characters that are unsafe in filenames.
+     */
+    sanitizeFilename(name) {
+        return snakeCase(name.replaceAll('"', ''));
+    }
+}

package/dist/commands/ephemeral/push/index.d.ts

@@ -0,0 +1,23 @@
+import BaseCommand from '../../../base-command.js';
+export default class EphemeralPush extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        directory: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        delete: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        env: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        guids: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        records: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        sync: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        tenant: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        transaction: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        truncate: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        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>;
+}