@xano/cli 1.0.4 → 1.0.6-beta.0

package/README.md

@@ -47,6 +47,13 @@ xano auth
 xano auth --origin https://custom.xano.com
 xano auth --insecure                         # Skip TLS verification (self-signed certs)
 xano auth --no-browser                       # Headless login (no local callback server)
+
+# Pre-select instance/workspace/branch and profile name (skips the pickers)
+xano auth -i my-instance -w 5 -b dev -p staging
+xano auth --instance my-instance --workspace "My Workspace" --branch dev --profile staging
+
+# Pass "" to take a picker's default: skip workspace, use live branch, default profile name
+xano auth -i my-instance -w 5 -b "" -p ""
 ```
 
 The default flow starts a temporary callback server on `127.0.0.1` and waits
@@ -55,12 +62,20 @@ containers, or locked-down networks where the browser can't reach the CLI's
 loopback address, use `--no-browser`: the CLI prints a login URL, you open it
 in any browser, and paste back the code it displays. No local server required.
 
+Each picker can be pre-answered with a flag: `-i/--instance` (instance name, or numeric instance ID),
+`-w/--workspace` (workspace ID or name), `-b/--branch` (branch label), and
+`-p/--profile` (profile name to save). An empty value (`""`) takes the
+picker's default answer: `-w ""` skips workspace selection, `-b ""` skips and
+uses the live branch, and `-p ""` uses the default profile name. With all four
+set alongside `--no-browser`, the only input is pasting the code from the
+browser — useful for scripted or remote setups.
+
 When stdin is piped (not a TTY), `--no-browser` reads the code directly from
 stdin instead of prompting, so scripts and AI agents can complete the flow
 without an interactive terminal:
 
 ```bash
-echo "$CODE" | xano auth --no-browser
+echo "$CODE" | xano auth --no-browser -i my-instance -w 5 -b dev -p staging
 ```
 
 If you can't run `xano auth` at all, you can always create a profile manually
@@ -240,6 +255,58 @@ xano function edit <function_id> -f new.xs              # Update from file
 xano function edit <function_id> -f new.xs --edit       # Open in $EDITOR before updating
 cat function.xs | xano function edit <function_id> --stdin  # Update from stdin
 xano function edit <function_id> --no-publish           # Edit without publishing
+
+# Run (execute) a function by name
+xano function run <name>                                # Prompts for declared inputs (on a TTY)
+xano function run <name> --data email=jo@x.com --data age:=30 --data active:=true
+xano function run <name> --json @payload.json --data env=staging   # base payload + override
+echo '{"email":"jo@x.com"}' | xano function run <name> --stdin -o json | jq .result
+xano function run <name> --branch dev --logs            # run on a branch, show execution logs
+```
+
+Input flexibility for `function run` (assembled into one JSON `input` object):
+
+| Form | Meaning |
+| --- | --- |
+| `--data key=value` | string field |
+| `--data key:=<json>` | raw JSON field (`age:=30`, `active:=true`, `tags:='["a","b"]'`) |
+| `--data key@file` | field value read from a file |
+| `--json '<inline>'` / `--json @file.json` / `--json -` | a base JSON object (stdin with `-`) |
+| `--stdin` | read the JSON object from stdin (same as `--json -`) |
+
+Merge order is JSON base first, then `--data` overrides. Missing required inputs are
+prompted for on an interactive terminal; in a non-TTY (CI) context the command fails
+listing them. Output defaults to the raw `result` (`-o json`); the exit code is non-zero
+when the function returns an error status.
+
+> **Permissions:** running a function requires **Function** (read) plus the **run/debug**
+> action on your workspace role. If your access token's role lacks run/debug, the call is
+> denied with an access error — grant run/debug to the role (or use a token whose role has
+> it). `function list`/`get`/`create`/`edit` only need the Function permission.
+
+### Knowledge
+
+```bash
+# List all enabled knowledge as markdown (always-on items show full content, on-demand show name + description)
+xano knowledge list -w 40
+
+# List as JSON
+xano knowledge list -w 40 --output json
+
+# Filter by knowledge type (skill, doc, agents.md)
+xano knowledge list -w 40 --type skill
+
+# Include disabled items
+xano knowledge list --no-enabled-only
+
+# Get a specific knowledge item's content by name
+xano knowledge get "deploy-runbook" -w 40
+
+# Get as JSON (includes all metadata)
+xano knowledge get "deploy-runbook" -w 40 --output json
+
+# Get a reference file attached to a knowledge item
+xano knowledge get "deploy-runbook" -w 40 --file checklist.md
 ```
 
 ### Releases
@@ -311,6 +378,7 @@ xano unit_test list --branch dev --obj-type function
 
 # Run a single unit test
 xano unit_test run <unit_test_id>
+xano unit_test run <unit_test_id> --branch dev   # run the test from a specific branch
 
 # Run all unit tests
 xano unit_test run_all
@@ -496,6 +564,38 @@ xano tenant cluster license set <cluster_id>
 xano tenant cluster license set <cluster_id> --file ./kubeconfig.yaml
 ```
 
+### Ephemeral Tenants
+
+Manage ephemeral tenants — short-lived, auto-expiring tenants scoped to a workspace (default TTL 1h, max 72h). Unlike a sandbox, an ephemeral tenant requires a workspace.
+
+```bash
+# List ephemeral tenants in the current workspace
+xano ephemeral list
+xano ephemeral list -w 5
+
+# List ephemeral tenants across every workspace you can access
+xano ephemeral list --global
+
+# Create an ephemeral tenant (workspace required)
+xano ephemeral create "PR preview"
+xano ephemeral create "Demo" --expires-hours 24 -w 5
+xano ephemeral create "Load test" -d "48h soak" --expires-hours 48
+
+# Get / edit / delete
+xano ephemeral get <tenant_name>
+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
+
+# Open in the browser (or print the URL)
+xano ephemeral impersonate <tenant_name>
+xano ephemeral impersonate <tenant_name> --url-only
+```
+
 ### Sandbox
 
 Manage your sandbox tenant. Each user has a single sandbox tenant that is auto-provisioned on first use.
@@ -541,14 +641,49 @@ xano sandbox reset --force
 # List static hosts
 xano static_host list
 
-# Create a build
-xano static_host build create default -f ./build.zip -n "v1.0.0"
+# 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
 xano static_host build list default
 
 # Get build details
-xano static_host build get default 52
+xano static_host build get default --build_id 52
+
+# Pull a build to disk. Defaults to the original uploaded source
+# (including package.json). Use --source built for the compiled/served output.
+xano static_host build pull default --build_id 52    # By build ID (original source)
+xano static_host build pull default --build_id 52 --source built   # Compiled output
+xano static_host build pull default --latest         # Latest build
+xano static_host build pull default --env dev        # Build currently deployed to dev
+xano static_host build pull default --env prod -d ./prod-release
+
+# Push a build (name optional — auto-generated from the timestamp if omitted).
+# Accepts a directory (-d) or a zip file (-f). Defaults to the current directory.
+# When pushing a directory, files matched by its .gitignore are skipped by default
+# (the .git/ folder is always excluded); use --no-gitignore to push everything.
+# For package.json builds, the CLI waits for the build to finish (--no-wait to skip).
+xano static_host build push default -d ./dist -n "v1.0.0"
+xano static_host build push default                          # current dir, auto-name
+xano static_host build push default -f ./build.zip -n "v1.0.0"  # from zip file
+xano static_host build push default -n "release" --description "Production build"
+xano static_host build push default -d ./static --no-gitignore  # push gitignored files too
+
+# Delete a build (prompts for confirmation; --force to skip)
+xano static_host build delete default --build_id 52
+xano static_host build delete default --build_id 52 --force
+
+# Deploy a build to an environment
+xano static_host deploy default --build_id 52 --env dev
+xano static_host deploy default --build_id 52 --env prod
+
+# Migrate a host to instance-managed (v2) hosting
+xano static_host migrate newsite                 # one host (both envs)
+xano static_host migrate newsite --env dev        # one env
+xano static_host migrate --all                    # every v1 host in the workspace
+xano static_host migrate --all --dry-run          # preview without changing anything
 ```
 
 ## Global Options

package/dist/base-command.d.ts

@@ -103,4 +103,31 @@ export default abstract class BaseCommand extends Command {
      * Use this for all Metadata API calls to support the --verbose flag.
      */
     protected verboseFetch(url: string, options: RequestInit, verbose: boolean, authToken?: string): Promise<Response>;
+    /**
+     * Poll a static-host build until it reaches a terminal status (ok | error),
+     * showing a live, ticking spinner with the current stage and elapsed time —
+     * mirroring the UI's build progress for async (package.json) builds, which
+     * keep running after the upload returns.
+     *
+     * On a TTY it renders an animated spinner via ux.action; when quiet (JSON
+     * output) or non-interactive it falls back to plain one-line status updates.
+     *
+     * Returns the final status. Resolves to the last-seen status on timeout.
+     */
+    protected logStaticHostUrls(opts: {
+        profile: ProfileConfig;
+        staticHost: string;
+        verbose: boolean;
+        workspaceId: string;
+    }): Promise<void>;
+    protected waitForBuild(opts: {
+        buildId: number | string;
+        intervalMs?: number;
+        profile: ProfileConfig;
+        quiet?: boolean;
+        staticHost: string;
+        timeoutMs?: number;
+        verbose: boolean;
+        workspaceId: string;
+    }): Promise<string>;
 }

package/dist/base-command.js

@@ -1,4 +1,4 @@
-import { Command, Flags } from '@oclif/core';
+import { Command, Flags, ux } from '@oclif/core';
 import * as yaml from 'js-yaml';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
@@ -358,4 +358,127 @@ export default class BaseCommand extends Command {
         }
         return response;
     }
+    /**
+     * Poll a static-host build until it reaches a terminal status (ok | error),
+     * showing a live, ticking spinner with the current stage and elapsed time —
+     * mirroring the UI's build progress for async (package.json) builds, which
+     * keep running after the upload returns.
+     *
+     * On a TTY it renders an animated spinner via ux.action; when quiet (JSON
+     * output) or non-interactive it falls back to plain one-line status updates.
+     *
+     * 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}`;
+        try {
+            const response = await this.verboseFetch(url, {
+                headers: { accept: 'application/json', Authorization: `Bearer ${profile.access_token}` },
+                method: 'GET',
+            }, verbose, profile.access_token);
+            if (!response.ok)
+                return;
+            const host = (await response.json());
+            if (host.dev?.default_url)
+                this.log(`Dev URL: ${host.dev.default_url}`);
+            if (host.dev?.custom_url)
+                this.log(`Dev Custom URL: ${host.dev.custom_url}`);
+            if (host.prod?.default_url)
+                this.log(`Prod URL: ${host.prod.default_url}`);
+            if (host.prod?.custom_url)
+                this.log(`Prod Custom URL: ${host.prod.custom_url}`);
+        }
+        catch {
+            // Non-fatal — the build succeeded, we just can't show the URL.
+        }
+    }
+    async waitForBuild(opts) {
+        const { buildId, profile, quiet, staticHost, 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}`;
+        // 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;
+        const start = Date.now();
+        const elapsed = () => Math.round((Date.now() - start) / 1000);
+        let stage = 'pending';
+        let ticker;
+        // Reflect the current stage: live spinner status on a TTY, else a plain line.
+        const render = () => {
+            if (animate) {
+                ux.action.status = `${stageLabel(stage)} (${elapsed()}s)`;
+            }
+            else if (!quiet && !terminal.has(stage)) {
+                this.log(`Build status: ${stage}`);
+            }
+        };
+        // Stop the spinner/ticker and emit a final line.
+        const conclude = (message) => {
+            if (ticker)
+                clearInterval(ticker);
+            if (animate) {
+                ux.action.stop(message);
+            }
+            else if (!quiet) {
+                this.log(message);
+            }
+        };
+        if (animate) {
+            ux.action.start('Building', stageLabel(stage));
+            // Re-render every 120ms so the elapsed counter ticks even between polls.
+            ticker = setInterval(render, 120);
+        }
+        else if (!quiet) {
+            this.log(`Build status: ${stage}`);
+        }
+        /* eslint-disable no-await-in-loop */
+        while (Date.now() - start < timeoutMs) {
+            const response = await this.verboseFetch(url, {
+                headers: { accept: 'application/json', Authorization: `Bearer ${profile.access_token}` },
+                method: 'GET',
+            }, verbose, profile.access_token);
+            if (response.ok) {
+                const build = (await response.json());
+                const status = build.status ?? 'pending';
+                if (status !== stage) {
+                    stage = status;
+                    render();
+                }
+                if (terminal.has(status)) {
+                    const took = `${elapsed()}s`;
+                    conclude(status === 'ok' ? `done in ${took}` : `failed after ${took}`);
+                    return status;
+                }
+            }
+            await new Promise((resolve) => {
+                setTimeout(resolve, intervalMs);
+            });
+        }
+        /* eslint-enable no-await-in-loop */
+        conclude(`stopped waiting after ${Math.round(timeoutMs / 1000)}s (last status: ${stage || 'unknown'})`);
+        return stage;
+    }
+}
+/** Human-friendly label for a build status stage. */
+function stageLabel(status) {
+    switch (status) {
+        case 'building': {
+            return 'Installing & building (npm)';
+        }
+        case 'ok': {
+            return 'Finishing';
+        }
+        case 'pending': {
+            return 'Queued';
+        }
+        case 'publishing': {
+            return 'Publishing files';
+        }
+        default: {
+            return status;
+        }
+    }
 }

package/dist/commands/auth/index.d.ts

@@ -1,14 +1,53 @@
 import { Command } from '@oclif/core';
+export interface Instance {
+    display: string;
+    id: string;
+    name: string;
+    origin: string;
+}
+export interface AuthResult {
+    branch: null | string;
+    credentialsPath: string;
+    instance: {
+        id: string;
+        name: string;
+        origin: string;
+    };
+    profile: string;
+    user: {
+        email: string;
+        id: string;
+        name: string;
+    };
+    workspace: null | {
+        id: string;
+        name: string;
+    };
+}
+/**
+ * Match a user-supplied --instance value against the instance list:
+ * numeric values match by ID, URL/hostname values match by the instance
+ * origin's hostname, anything else matches by name. Exported for tests.
+ */
+export declare function matchInstance(instances: Instance[], query: string): Instance | undefined;
 export default class Auth extends Command {
     static description: string;
+    static enableJsonFlag: boolean;
     static examples: string[];
     static flags: {
+        branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        code: 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>;
         insecure: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'no-browser': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         origin: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
-    run(): Promise<void>;
+    run(): Promise<AuthResult>;
+    protected toErrorJson(err: unknown): unknown;
+    private acquireToken;
     private getHeaders;
     private fetchBranches;
     private fetchInstances;
@@ -16,6 +55,11 @@ export default class Auth extends Command {
     private promptForToken;
     private promptProfileName;
     private readTokenFromStdin;
+    private resolveBranch;
+    private resolveInstance;
+    private resolveProfileName;
+    private resolveWorkspace;
+    private resolveWorkspaceAndBranch;
     private saveProfile;
     private selectBranch;
     private selectInstance;