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

package/README.md

@@ -39,6 +39,38 @@ Destructive commands include imperative safety prefixes in their help text and f
 
 These warnings are layer 1 of broader push-safety work; ephemeral sandbox environments and push preview remain the structural safeguards.
 
+### Paging on list commands
+
+The Metadata API pages unevenly, so `list` commands differ in what they expose. Every command reports only what its endpoint actually returns — the CLI never guesses whether more results exist.
+
+| Commands | Flags | Footer |
+|---|---|---|
+| `function list`, `unit_test list`, `workflow_test list` (plus `sandbox` / `tenant` variants) | `--page`, `--per_page` | `Page 2 · 50 shown · next: --page 3` |
+| `static_host list`, `static_host build list` (plus `ephemeral` variants) | `--page` only | `Page 2 · 100 shown · 340 total` |
+| `branch list`, `workspace list`, `tenant snapshot list`, `sandbox env list`, `tenant env list` | none | `12 branches` |
+| `tenant list`, `release list`, `platform list`, `tenant cluster list`, `ephemeral list` | none | none |
+| `tenant backup list` | `--page` only (pre-existing) | none |
+
+Notes:
+
+- **`--per_page` is only offered where the endpoint accepts it.** Static-host endpoints hardcode 100 items per page server-side, so those commands take `--page` alone. `xano static_host list --per_page 10` previously parsed but did nothing; it is now rejected rather than silently ignored.
+- **All paged commands default `--per_page` to 50.** The test-list commands previously requested 10000 internally so nothing was ever cut off; now that the footer and the JSON envelope both report position, a page that stops at 50 is visible rather than silent. Raise it (up to 10000) when you want everything in one call.
+- **The last group has no CLI paging.** Those endpoints page server-side but return a plain array with no page or total metadata, so the CLI cannot tell you where you are. Rather than show a page number with no context — or infer "more available" from a full page, which is wrong exactly when the result count is a multiple of the page size — these commands are left as-is. **They return at most 25–50 items** (50 for tenants and ephemerals, 25 for releases, platforms, and tenant backups). If you have more than that, query the Metadata API directly until those endpoints return paging metadata.
+- **`--output json` returns an envelope, not a bare array.** Every list command emits `{items, ...}` using the Metadata API's own field names — `curPage`, `nextPage`, `prevPage`, `itemsTotal` — each included only when the endpoint actually reports it. `perPage` is the one field the CLI adds, since the API never echoes it back and it is otherwise invisible at its default. This is a **breaking change** for scripts that parsed the previous bare array — read `.items` instead.
+
+  ```jsonc
+  // xano function list -o json
+  {
+    "curPage": 2,
+    "perPage": 50,      // injected by the CLI; everything else mirrors the API
+    "nextPage": 3,      // absent on the last page — never inferred
+    "prevPage": 1,
+    "items": [ /* ... */ ]
+  }
+  ```
+
+  The point of the envelope is that a script gets the same honest stop condition a human gets from the footer, in the same shape the raw Metadata API returns. Without it the only signal available is `items.length < perPage`, which is wrong exactly when the result count is a multiple of the page size. Absence of `nextPage` means the server said there is no next page; it is never omitted as a guess.
+
 ### Authentication
 
 ```bash
@@ -197,6 +229,35 @@ xano workspace git pull -r https://github.com/owner/private-repo -t ghp_xxx
 xano workspace git pull -r https://github.com/owner/repo --path subdir
 ```
 
+### Knowledge
+
+Knowledge items are user-authored docs and skills (e.g. `CLAUDE.md`, `AGENTS.md`, runbooks)
+attached to a workspace. Each knowledge item's **name is a path** (e.g. `some/thing/CLAUDE.md`):
+`pull` writes its content to that path under the output directory, and `push` turns each local
+file into a knowledge item named by its relative path.
+
+Push matches local files to remote items by name. Existing items are updated (content only —
+description, mode, tags, and other metadata are preserved); new files are created. The
+knowledge type for new items is inferred from the filename: `AGENTS.md` → `agents.md`,
+`SKILL.md` → `skill`, everything else → `doc`. Hidden files (dotfiles) and `node_modules`
+are skipped.
+
+```bash
+# Pull knowledge files to local paths (defaults to current directory)
+xano knowledge pull
+xano knowledge pull -d ./knowledge                       # Specify output directory
+xano knowledge pull -b dev                               # Specific branch
+
+# Push local files as knowledge (defaults to current directory, only changed files)
+xano knowledge push
+xano knowledge push -d ./knowledge                       # Push from a specific directory
+xano knowledge push --dry-run                            # Preview changes without pushing
+xano knowledge push --sync --delete                      # Full push + delete remote knowledge not included
+xano knowledge push --force                              # Skip preview and confirmation (for CI/CD)
+xano knowledge push -i "guides/*"                        # Push only matching files
+xano knowledge push -e "**/README.md"                    # Push all files except READMEs
+```
+
 ### Branches
 
 All branch commands use **branch labels** (e.g., `v1`, `dev`), not IDs.
@@ -372,9 +433,10 @@ xano platform get <platform_id>
 #### Unit Tests
 
 ```bash
-# List unit tests
+# List unit tests (returns all tests by default; --per_page narrows the page)
 xano unit_test list
 xano unit_test list --branch dev --obj-type function
+xano unit_test list --page 2 --per_page 25
 
 # Run a single unit test
 xano unit_test run <unit_test_id>
@@ -388,9 +450,10 @@ xano unit_test run_all --branch dev --obj-type function
 #### Workflow Tests
 
 ```bash
-# List workflow tests
+# List workflow tests (returns all tests by default; --per_page narrows the page)
 xano workflow_test list
 xano workflow_test list --branch dev
+xano workflow_test list --page 2 --per_page 25
 
 # Get workflow test details
 xano workflow_test get <workflow_test_id>
@@ -404,10 +467,35 @@ xano workflow_test run <workflow_test_id>
 xano workflow_test run_all
 xano workflow_test run_all --branch dev
 
+# Run tests in parallel (default is 1 — sequential)
+xano unit_test run_all --concurrency 4
+xano workflow_test run_all --concurrency 4
+
+# Sandbox and tenant variants take the same paging flags
+xano sandbox unit_test list --page 2 --per_page 25
+xano sandbox workflow_test list --page 2 --per_page 25
+xano tenant unit_test list my-tenant --page 2 --per_page 25
+xano tenant workflow_test list my-tenant --page 2 --per_page 25
+
 # Delete a workflow test
 xano workflow_test delete <workflow_test_id>
 ```
 
+#### Running tests in parallel
+
+Every `run_all` command takes `--concurrency` (default `1`):
+
+```bash
+xano unit_test run_all --concurrency 4
+xano tenant unit_test run_all my-tenant --concurrency 8
+```
+
+Output stays in test order regardless of concurrency, so a parallel run is still diffable against a sequential one, and the JSON `results` array keeps a stable order.
+
+`run_all` discovers the test list by paging at 100 per request rather than asking for the whole suite in one response, and stops when the API reports no next page.
+
+**The default is 1 on purpose.** These tests execute against a shared workspace database, so tests that touch the same tables or records can interfere with each other when run at the same time — producing failures that look like flakiness rather than a real regression. Raise `--concurrency` once you know your tests are independent.
+
 ### Tenants
 
 Manage tenants, their environment variables, backups, deployments, and clusters.
@@ -587,15 +675,41 @@ xano ephemeral edit <tenant_name> --display "New Name" -d "New description"
 xano ephemeral delete <tenant_name> --force
 
 # Pull to / push from local files (multidoc)
-xano ephemeral pull -t <tenant_name> -d ./my-ephemeral
-xano ephemeral push -t <tenant_name> -d ./my-ephemeral --dry-run   # preview first
-xano ephemeral push -t <tenant_name> -d ./my-ephemeral
+xano ephemeral pull <tenant_name> -d ./my-ephemeral
+xano ephemeral push <tenant_name> -d ./my-ephemeral --dry-run   # preview first
+xano ephemeral push <tenant_name> -d ./my-ephemeral
 
 # Open in the browser (or print the URL)
 xano ephemeral impersonate <tenant_name>
 xano ephemeral impersonate <tenant_name> --url-only
+xano ephemeral impersonate <tenant_name> --guest       # read-only session (browse only)
 ```
 
+#### Static hosting for an ephemeral tenant
+
+An ephemeral tenant can host static sites, scoped to that tenant. These commands mirror
+`xano static_host *` but take the tenant name as the first argument (the tenant's static
+hosting is isolated inside the tenant's own database).
+
+```bash
+# List / create / inspect a tenant's static hosts
+xano ephemeral static_host list <tenant_name>
+xano ephemeral static_host create <tenant_name> --name marketing --description "Marketing site"
+xano ephemeral static_host get <tenant_name> -H marketing
+xano ephemeral static_host edit <tenant_name> -H marketing --description "Updated"
+
+# Builds: push a directory, list, inspect, deploy to an env, pull, delete
+xano ephemeral static_host build push <tenant_name> -H default -f ./site
+xano ephemeral static_host build list <tenant_name> -H default
+xano ephemeral static_host build get <tenant_name> -H default --build_id 52
+xano ephemeral static_host deploy <tenant_name> -H default --build_id 52 --env prod
+xano ephemeral static_host build pull <tenant_name> -H default --latest
+xano ephemeral static_host build delete <tenant_name> -H default --build_id 52
+```
+
+> Static hosting is currently available for **local** tenants. Remote (tier2/tier3)
+> tenants are not yet supported and will return an error.
+
 ### Sandbox
 
 Manage your sandbox tenant. Each user has a single sandbox tenant that is auto-provisioned on first use.
@@ -638,16 +752,19 @@ xano sandbox reset --force
 ### Static Hosts
 
 ```bash
-# List static hosts
+# List static hosts. Page size is fixed at 100 by the API, so there is no
+# --per_page flag; the footer reports the true total.
 xano static_host list
+xano static_host list --page 2
 
 # Create / get / edit a static host
 xano static_host create marketing --description "Marketing site"
 xano static_host get marketing
 xano static_host edit marketing --name marketing-v2 --description "Updated"
 
-# List builds
+# List builds (--page only; page size is fixed at 100 by the API)
 xano static_host build list default
+xano static_host build list default --page 2
 
 # Get build details
 xano static_host build get default --build_id 52

package/dist/base-command.d.ts

@@ -117,6 +117,7 @@ export default abstract class BaseCommand extends Command {
     protected logStaticHostUrls(opts: {
         profile: ProfileConfig;
         staticHost: string;
+        tenantName?: string;
         verbose: boolean;
         workspaceId: string;
     }): Promise<void>;
@@ -126,6 +127,7 @@ export default abstract class BaseCommand extends Command {
         profile: ProfileConfig;
         quiet?: boolean;
         staticHost: string;
+        tenantName?: string;
         timeoutMs?: number;
         verbose: boolean;
         workspaceId: string;

package/dist/base-command.js

@@ -370,8 +370,11 @@ export default class BaseCommand extends Command {
      * Returns the final status. Resolves to the last-seen status on timeout.
      */
     async logStaticHostUrls(opts) {
-        const { profile, staticHost, verbose, workspaceId } = opts;
-        const url = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/static_host/${staticHost}`;
+        const { profile, staticHost, tenantName, verbose, workspaceId } = opts;
+        // When a tenant is scoped, target the tenant's static hosting; otherwise the
+        // workspace-level static host (default, unchanged behavior).
+        const scope = tenantName ? `/tenant/${tenantName}` : '';
+        const url = `${profile.instance_origin}/api:meta/workspace/${workspaceId}${scope}/static_host/${staticHost}`;
         try {
             const response = await this.verboseFetch(url, {
                 headers: { accept: 'application/json', Authorization: `Bearer ${profile.access_token}` },
@@ -394,11 +397,14 @@ export default class BaseCommand extends Command {
         }
     }
     async waitForBuild(opts) {
-        const { buildId, profile, quiet, staticHost, verbose, workspaceId } = opts;
+        const { buildId, profile, quiet, staticHost, tenantName, verbose, workspaceId } = opts;
         const intervalMs = opts.intervalMs ?? 2000;
         const timeoutMs = opts.timeoutMs ?? 600_000; // 10 min
         const terminal = new Set(['error', 'ok']);
-        const url = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/static_host/${staticHost}/build/${buildId}`;
+        // When a tenant is scoped, target the tenant's static hosting; otherwise the
+        // workspace-level static host (default, unchanged behavior).
+        const scope = tenantName ? `/tenant/${tenantName}` : '';
+        const url = `${profile.instance_origin}/api:meta/workspace/${workspaceId}${scope}/static_host/${staticHost}/build/${buildId}`;
         // Spinner only on an interactive TTY and when not emitting JSON. Verbose mode
         // also disables it (the spinner would interleave with request/response logs).
         const animate = Boolean(process.stdout.isTTY) && !quiet && !verbose;

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

@@ -1,5 +1,6 @@
 import { Flags } from '@oclif/core';
 import BaseCommand from '../../../base-command.js';
+import { buildPagingJson, formatPagingFooter } from '../../../utils/paging.js';
 export function filterBackups(branches, includeBackups) {
     return includeBackups ? branches : branches.filter((b) => !b.backup);
 }
@@ -82,7 +83,7 @@ Available branches:
             const branches = filterBackups(allBranches, flags.backups);
             // Output results
             if (flags.output === 'json') {
-                this.log(JSON.stringify(branches, null, 2));
+                this.log(JSON.stringify(buildPagingJson({ items: branches }, { tier: 'none' }), null, 2));
             }
             else {
                 // summary format
@@ -97,6 +98,9 @@ Available branches:
                         this.log(`  - ${branch.label}${liveIndicator}${backupIndicator}`);
                     }
                 }
+                const footer = formatPagingFooter({ items: branches }, { noun: 'branch', nounPlural: 'branches', tier: 'none' });
+                if (footer)
+                    this.log(footer);
             }
         }
         catch (error) {

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

@@ -6,6 +6,7 @@ export default class EphemeralImpersonate extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
+        guest: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'url-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

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

@@ -15,9 +15,16 @@ Opening browser...
 Impersonation successful!
 `,
         `$ xano ephemeral impersonate e4f2-9ab1-xyz1 -o json`,
+        `$ xano ephemeral impersonate e4f2-9ab1-xyz1 --guest --url-only`,
     ];
     static flags = {
         ...BaseCommand.baseFlags,
+        guest: Flags.boolean({
+            char: 'g',
+            default: false,
+            description: 'Mint a read-only guest session (browse only; no schema/data/config changes)',
+            required: false,
+        }),
         output: Flags.string({
             char: 'o',
             default: 'summary',
@@ -46,7 +53,7 @@ Impersonation successful!
         }
         const tenantName = args.tenant_name;
         try {
-            const response = await this.getImpersonateResponse(profile, workspaceId, tenantName);
+            const response = await this.getImpersonateResponse(profile, workspaceId, tenantName, flags.guest);
             if (flags.output === 'json') {
                 this.log(JSON.stringify(response, null, 2));
             }
@@ -76,8 +83,9 @@ Impersonation successful!
             }
         }
     }
-    async getImpersonateResponse(profile, workspaceId, tenantName) {
-        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${encodeURIComponent(tenantName)}/impersonate`;
+    async getImpersonateResponse(profile, workspaceId, tenantName, guest = false) {
+        const query = guest ? '?guest_read_only=true' : '';
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${encodeURIComponent(tenantName)}/impersonate${query}`;
         const { verbose } = await this.parse(EphemeralImpersonate).then((r) => r.flags);
         const response = await this.verboseFetch(apiUrl, {
             headers: {

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

@@ -1,5 +1,6 @@
 import { Flags } from '@oclif/core';
 import BaseCommand from '../../../base-command.js';
+import { buildPagingJson } from '../../../utils/paging.js';
 export default class EphemeralList extends BaseCommand {
     static description = 'List ephemeral tenants in a workspace, or across the whole instance with --global';
     static examples = [
@@ -73,7 +74,7 @@ Ephemeral tenants (all workspaces):
                 this.error('Unexpected API response format');
             }
             if (flags.output === 'json') {
-                this.log(JSON.stringify(tenants, null, 2));
+                this.log(JSON.stringify(buildPagingJson({ items: tenants }, { tier: 'none' }), null, 2));
             }
             else if (tenants.length === 0) {
                 this.log('No ephemeral tenants found');

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

@@ -1,5 +1,8 @@
 import BaseCommand from '../../../base-command.js';
 export default class EphemeralPull extends BaseCommand {
+    static args: {
+        tenant_name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
     static description: string;
     static examples: string[];
     static flags: {
@@ -7,17 +10,10 @@ export default class EphemeralPull extends BaseCommand {
         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

@@ -1,25 +1,31 @@
-import { Flags } from '@oclif/core';
+import { Args, 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';
+import { buildApiGroupFolderResolver, buildChannelServerResolver, parseDocument, resolveDocumentPath, } from '../../../utils/document-parser.js';
 export default class EphemeralPull extends BaseCommand {
+    static args = {
+        tenant_name: Args.string({
+            description: 'Ephemeral tenant name to pull from',
+            required: true,
+        }),
+    };
     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
+        `$ xano ephemeral pull e4f2-9ab1-xyz1
 Pulled 42 documents from tenant e4f2-9ab1-xyz1 to current directory
 `,
-        `$ xano ephemeral pull -d ./my-tenant -t e4f2-9ab1-xyz1
+        `$ xano ephemeral pull e4f2-9ab1-xyz1 -d ./my-tenant
 Pulled 42 documents from tenant e4f2-9ab1-xyz1 to ./my-tenant
 `,
-        `$ xano ephemeral pull -d ./output -t e4f2-9ab1-xyz1 -w 40
+        `$ xano ephemeral pull e4f2-9ab1-xyz1 -d ./output -w 40
 Pulled 15 documents from tenant e4f2-9ab1-xyz1 to ./output
 `,
-        `$ xano ephemeral pull -t e4f2-9ab1-xyz1 --profile production --env --records
+        `$ xano ephemeral pull e4f2-9ab1-xyz1 --profile production --env --records
 Pulled 58 documents from tenant e4f2-9ab1-xyz1
 `,
-        `$ xano ephemeral pull -t e4f2-9ab1-xyz1 --draft`,
+        `$ xano ephemeral pull e4f2-9ab1-xyz1 --draft`,
     ];
     static flags = {
         ...BaseCommand.baseFlags,
@@ -44,11 +50,6 @@ Pulled 58 documents from tenant e4f2-9ab1-xyz1
             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)',
@@ -56,7 +57,7 @@ Pulled 58 documents from tenant e4f2-9ab1-xyz1
         }),
     };
     async run() {
-        const { flags } = await this.parse(EphemeralPull);
+        const { args, flags } = await this.parse(EphemeralPull);
         const { profileName, profile } = this.resolveProfile(flags);
         // Determine workspace_id from flag or profile
         let workspaceId;
@@ -68,10 +69,10 @@ Pulled 58 documents from tenant e4f2-9ab1-xyz1
         }
         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` +
+                `  1. Provide it as a flag: xano ephemeral pull <tenant_name> -w <workspace_id>\n` +
                 `  2. Set it in your profile using: xano profile:edit ${profileName} -w <workspace_id>`);
         }
-        const tenantName = flags.tenant;
+        const tenantName = args.tenant_name;
         // Build query parameters
         const queryParams = new URLSearchParams({
             env: flags.env.toString(),
@@ -129,96 +130,19 @@ Pulled 58 documents from tenant e4f2-9ab1-xyz1
         fs.mkdirSync(outputDir, { recursive: true });
         // Resolve api_group names to unique folder names, disambiguating collisions
         const getApiGroupFolder = buildApiGroupFolderResolver(documents, snakeCase);
+        // Resolve a realtime v2 channel path -> owning realtime_server name, so
+        // messages can nest under their channel's server (see resolver docs).
+        const getChannelServer = buildChannelServerResolver(documents);
         // 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}`;
-                }
-            }
+            const { baseName, typeDir } = resolveDocumentPath(doc, outputDir, {
+                getApiGroupFolder,
+                getChannelServer,
+                join: path.join,
+                snakeCase,
+            });
             fs.mkdirSync(typeDir, { recursive: true });
             // Track duplicates per directory
             const dirKey = path.relative(outputDir, typeDir);
@@ -237,12 +161,4 @@ Pulled 58 documents from tenant e4f2-9ab1-xyz1
         }
         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

@@ -1,5 +1,8 @@
 import BaseCommand from '../../../base-command.js';
 export default class EphemeralPush extends BaseCommand {
+    static args: {
+        tenant_name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
     static description: string;
     static examples: string[];
     static flags: {
@@ -11,13 +14,22 @@ export default class EphemeralPush extends BaseCommand {
         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>;
+        wait: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'wait-timeout': import("@oclif/core/interfaces").OptionFlag<number, 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>;
+    /**
+     * 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.
+     */
+    private waitForDeploy;
+    /** Number of lines the last progress render wrote (for in-place TTY updates). */
+    private lastRenderLines;
 }