@xano/cli 1.3.3 → 1.3.5-beta.0

package/README.md

@@ -197,13 +197,16 @@ xano workspace delete -w <workspace_id> --force
 xano workspace pull
 xano workspace pull -d ./my-workspace                    # Specify output directory
 xano workspace pull -b dev                               # Specific branch
+xano workspace pull -b ''                                # The live branch, whatever the profile's branch
 xano workspace pull --env --records                      # Include env vars and table records
 xano workspace pull --draft                              # Include draft changes
+xano workspace pull --sync-state                         # Write .xano/sync_state.json; later pulls keep it current
 
 # Push local files to workspace (defaults to current directory, only changed files)
 xano workspace push
 xano workspace push -d ./my-workspace                    # Push from a specific directory
 xano workspace push -b dev
+xano workspace push -b ''                                # The live branch, whatever the profile's branch
 xano workspace push --sync                               # Full push — send all files, not just changed ones
 xano workspace push --sync --delete                      # Full push + delete remote objects not included
 xano workspace push --dry-run                            # Preview changes without pushing
@@ -212,10 +215,16 @@ xano workspace push --env                                # Include environment v
 xano workspace push --truncate                           # Truncate tables before import
 xano workspace push --no-transaction                     # Disable database transaction wrapping
 xano workspace push --no-guids                           # Skip writing GUIDs back to local files
+xano workspace push --fast                               # Push only files that changed since last sync
+xano workspace push --fast --refresh                     # Re-compare against the server export, then push
+xano workspace push --no-fast                            # Skip --fast even when profile.yaml sets fast: true
+xano workspace push --writeback                          # Write server-formatted XanoScript back to pushed files
+xano workspace push --writeback --writeback-diff ./diffs # Also save local vs server copies for linter work
 xano workspace push --force                              # Skip preview and confirmation (for CI/CD)
 xano workspace push -i "function/*"                      # Push only matching files
 xano workspace push -e "table/*"                         # Push all files except tables
 xano workspace push -i "function/*" -e "**/test*"        # Include functions, exclude tests
+xano workspace push -o json                              # One JSON document: the preview (with --dry-run) or the import result
 
 # Pull from a git repository to local files (defaults to current directory)
 xano workspace git pull -r https://github.com/owner/repo
@@ -244,6 +253,44 @@ directory *adds* a file rather than overwriting, and renaming a workspace leaves
 the old-name file behind. Delete the stale ones, keeping the single document that
 matches your target workspace.
 
+### `.xano/sync_state.json`
+
+`--fast` skips files whose contents still match a local sync
+record at `<push dir>/.xano/sync_state.json`. The file is per-working-copy
+state: it should not be committed. Ignoring it is up to you (the CLI never
+edits `.gitignore` or any other VCS ignore file).
+
+The record is created by `workspace pull --sync-state`, `sandbox pull --sync-state`,
+`workspace push --fast`, or `sandbox push --fast`.
+Once it exists, every successful workspace or sandbox push or pull updates it. A successful
+`workspace push --sync --delete` or `sandbox push --sync --delete` also removes entries for
+files deleted locally, which clears the "deleted locally" note. A default push or pull does
+not create it. `--dry-run` never writes it, and neither does `pull --draft`, because
+`--fast` compares against published versions. Push records the exact bytes it sent, so a
+file edited while a push runs is sent again by the next `--fast` push. Delete the file to turn this off; the next
+`--fast` push compares against the server export once (~99 seconds on a
+~1,100-document workspace) and rebuilds it. If that export fails, the CLI falls
+back to a full dry-run.
+
+Sandbox `--fast` also keeps a per-user marker at `sandbox_sync.json` next to your
+credentials file (normally `~/.xano/sandbox_sync.json`). A successful sandbox push
+or `sandbox pull --sync-state` writes a new token there and into the directory's
+record. `sandbox reset` and `sandbox delete` clear the host's entries, as does a
+sandbox push from another directory. If the tokens do not match, `--fast` compares
+against the sandbox export once instead of trusting the record. After a reset or
+push done outside this CLI or on another machine, use `--refresh`.
+
+`--refresh` (requires `--fast`) runs that export comparison even when a record
+already exists. Use it after edits in the Xano UI, a teammate's push, or when
+the record looks wrong. `--fast` will not overwrite remote-only changes; a push
+without `--fast` still will.
+
+`--fast` cannot be combined with `--sync`. It works with `--force` and still
+sends only the files the record (or export comparison) marked as changed.
+With `--records`, tables that have `items` are always sent, as they are without
+`--fast`. With `--env`, `--fast` compares every file with the dry-run, because the
+record does not track environment variables.
+
 ### Flatten
 
 A hand-authored `.xs` file can hold several documents joined by `---`. That is
@@ -387,8 +434,8 @@ Input flexibility for `function run` (assembled into one JSON `input` object):
 to run against `live`; an unknown label is rejected by the server with
 `Invalid data source.`
 
-`-t/--tenant <name>` runs the function on that tenant instead of the workspace by sending
-the `X-Tenant` header (also used when reading the function's declared inputs).
+`-t/--tenant <name>` runs the function on that tenant
+(`/workspace/{id}/tenant/{name}/function/run`) instead of the workspace.
 
 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
@@ -610,9 +657,14 @@ xano tenant get <tenant_name>
 xano tenant create "My Tenant"
 xano tenant create "My Tenant" -d "Description" --type tier2 --cluster_id 1 --platform_id 5
 xano tenant create "My Tenant" --type tier2 --cluster_id 1 --license ./license.yaml
+xano tenant create "Production" --required_reviewers 1 --allow_deploy_bypass
+xano tenant create "Staging" --required_reviewers 0 --allow_quick_deploy
 
 # Edit a tenant
 xano tenant edit <tenant_name> --display "New Name" -d "New description"
+xano tenant edit <tenant_name> --required_reviewers 1
+xano tenant edit <tenant_name> --required_reviewers 0
+xano tenant edit <tenant_name> --allow_quick_deploy
 
 # Delete a tenant (confirmation required)
 xano tenant delete <tenant_name>
@@ -663,6 +715,65 @@ xano tenant deploy_release <tenant_name> --release v1.0
 xano tenant deploy_platform <tenant_name> --platform_id 5 --license ./license.yaml
 ```
 
+If a tenant has `required_reviewers` set above 0, `tenant deploy_release` fails with an
+error naming the `tenant_deploy_request` command to run instead — see below. A tenant
+with `allow_quick_deploy` enabled skips the gate entirely, regardless of
+`required_reviewers`.
+
+#### Tenant Deploy Requests
+
+When a tenant has `required_reviewers` set above 0 and `allow_quick_deploy` is off (see
+`tenant create`/`tenant edit` above), a release may only be deployed to it through an
+**approved deploy request**, requiring that many distinct reviewer approvals. An author
+with no deploy permission opens a request; a named reviewer who does hold deploy
+permission on the tenant votes to approve it, and once enough reviewers have approved,
+it deploys as part of that action. `allow_deploy_bypass` (set at `tenant create` time
+only) additionally allows an authorized user to skip a specific request's gate via
+`tenant_deploy_request bypass`, audited with a required reason.
+
+```bash
+# List deploy requests in a workspace (results show the target tenant and release)
+xano tenant_deploy_request list
+xano tenant_deploy_request list --tenant prod --status pending
+xano tenant_deploy_request list --tenant prod --release v1.2
+xano tenant_deploy_request list --to-review
+
+# Get details of a specific deploy request
+xano tenant_deploy_request get <id>
+
+# Open a deploy request (submits for review immediately unless --draft is passed)
+xano tenant_deploy_request create "Deploy v1.2 to prod" --tenant prod --release v1.2 --reviewers 12,45
+xano tenant_deploy_request create "Deploy v1.2 to prod" --tenant prod --release v1.2 --draft
+
+# Edit a deploy request's title, description or reviewers
+xano tenant_deploy_request edit <id> --title "Deploy v1.2.1 to prod"
+xano tenant_deploy_request edit <id> --reviewers 12,45,67
+
+# Change status: draft, submit, approve, request_changes, close, or reopen
+# (approve records one reviewer's vote; once enough votes are in it deploys the
+# release as part of that same call)
+xano tenant_deploy_request set_status <id> --status submit
+xano tenant_deploy_request set_status <id> --status approve
+xano tenant_deploy_request set_status <id> --status request_changes --reason "Needs a migration note"
+xano tenant_deploy_request set_status <id> --status close --reason "Superseded by a newer request"
+xano tenant_deploy_request set_status <id> --status reopen
+
+# Link a newer release to a request after changes were requested (author only)
+xano tenant_deploy_request revision <id> --release v1.2.1 --note "Added the missing migration"
+
+# Deploy past the approval gate under the deploy-bypass permission (requires the
+# tenant's allow_deploy_bypass to be enabled, and a separately-grantable RBAC
+# permission). Every use is audited.
+xano tenant_deploy_request bypass <id> --reason "Prod incident, reviewer unavailable"
+```
+
+CI example (e.g. a GitHub Action step):
+
+```bash
+xano tenant_deploy_request create "$PR_TITLE" --tenant prod --release v1.2 \
+  --description "$PR_BODY" --reviewers 12,45 -o json
+```
+
 #### Tenant License
 
 ```bash
@@ -820,6 +931,7 @@ xano sandbox get -o json
 xano sandbox pull
 xano sandbox pull -d ./my-sandbox
 xano sandbox pull --env --records
+xano sandbox pull --sync-state                           # Write .xano/sync_state.json; later pulls keep it current
 
 # Push local files to sandbox (defaults to current directory, only changed files)
 xano sandbox push
@@ -827,6 +939,11 @@ xano sandbox push -d ./my-workspace                      # Push from a specific
 xano sandbox push --sync                                 # Full push — send all files
 xano sandbox push --sync --delete                        # Full push + delete remote objects not included
 xano sandbox push --dry-run                              # Preview changes without pushing
+xano sandbox push --fast                                 # Skip unchanged files using .xano/sync_state.json
+xano sandbox push --fast --refresh                       # Re-compare against the sandbox export, then push
+xano sandbox push --no-fast                              # Push without --fast even when profile.yaml sets fast: true
+xano sandbox push --writeback                            # Write server-formatted XanoScript back after push
+xano sandbox push --writeback --writeback-diff ./diffs   # Also save local vs server copies
 xano sandbox push --records --env                        # Include records and environment variables
 xano sandbox push --truncate                             # Truncate tables before import
 xano sandbox push --no-guids                             # Skip writing GUIDs back to local files
@@ -972,11 +1089,28 @@ workspace: 110            # optional override
 instance_origin: https://your-instance.xano.io        # optional override
 account_origin: https://app.xano.com                  # optional override
 branch: main              # optional override
+fast: true                # optional: default workspace/sandbox push --fast
+writeback: true           # optional: default workspace/sandbox push --writeback
+writeback_object_limit: 50  # optional: workspace push --writeback per-object fetch limit (default 25)
 ```
 
 When a `profile.yaml` is in effect, every command prints the active target,
 e.g. `Using profile 'staging' (workspace 110) · profile.yaml` (suppressed for
-`--output json`).
+`--output json`). `workspace push` and `sandbox push` also log
+`Using --fast --writeback · profile.yaml` when those keys turn the flags on.
+`--no-fast` and `--no-writeback` override them for one run. `--sync` ignores a
+`fast: true` rather than erroring.
+
+`workspace push --writeback` fetches each pushed object individually when the push
+has at most `writeback_object_limit` documents (default 25), and otherwise downloads
+the full workspace export. Per-object requests grow with the number of documents;
+the export costs about the same no matter how many you pushed. Raise the limit for a
+large workspace where the export is slow; `0` always uses the export. If a per-object
+request fails, writeback falls back to the export. Sandbox push always uses the export.
+Writeback skips, with a warning, any file that changed on disk after the push read it.
+
+An explicit `-p/--profile` or `XANO_PROFILE` ignores `profile.yaml` entirely,
+including `fast`, `writeback`, and `writeback_object_limit`.
 
 Generate one with `xano profile use`. It writes a self-documenting
 `profile.yaml` (every overridable field is included as a commented example, so

package/dist/base-command.d.ts

@@ -63,6 +63,16 @@ export default abstract class BaseCommand extends Command {
      * Sets NODE_TLS_REJECT_UNAUTHORIZED=0 so all fetch() calls skip cert verification.
      */
     protected applyInsecureFromProfile(): void;
+    /**
+     * Report a failure as exit 1 for commands that reserve exit 2 for findings: operational errors,
+     * flag errors and oclif's own default exit 2 all become 1, and under `-o json` the failure is also
+     * written to stdout as `{"error": {"exit": 1, "message"}}`. A deliberate exit 0 passes through.
+     */
+    protected catchAsOperational(error: Error & {
+        oclif?: {
+            exit?: number;
+        };
+    }): Promise<void>;
     finally(_: Error | undefined): Promise<void>;
     /**
      * Get the resolved credentials file path, respecting --config flag and XANO_CONFIG env var.
@@ -78,6 +88,8 @@ export default abstract class BaseCommand extends Command {
     protected getOrCreateSandbox(profile: ProfileConfig, verbose: boolean): Promise<SandboxTenant>;
     protected getProfile(): string | undefined;
     init(): Promise<void>;
+    /** Raw-argv check: the parsed flags are not available yet when the banner prints. */
+    protected isJsonOutput(): boolean;
     protected loadCredentialsFile(): CredentialsFile | null;
     /**
      * Poll a static-host build until it reaches a terminal status (ok | error),
@@ -129,7 +141,6 @@ export default abstract class BaseCommand extends Command {
         verbose: boolean;
         workspaceId: string;
     }): Promise<string>;
-    private isJsonOutput;
     /**
      * Find and parse the nearest project-local profile.yaml, unless an explicit
      * -p/XANO_PROFILE was given (in which case the local file is ignored).

package/dist/base-command.js

@@ -156,6 +156,18 @@ export default class BaseCommand extends Command {
             // Don't fail the command if we can't read the profile for insecure check
         }
     }
+    /**
+     * Report a failure as exit 1 for commands that reserve exit 2 for findings: operational errors,
+     * flag errors and oclif's own default exit 2 all become 1, and under `-o json` the failure is also
+     * written to stdout as `{"error": {"exit": 1, "message"}}`. A deliberate exit 0 passes through.
+     */
+    async catchAsOperational(error) {
+        if (error.oclif?.exit === 0)
+            return super.catch(error);
+        if (this.isJsonOutput())
+            this.log(JSON.stringify({ error: { exit: 1, message: error.message } }, null, 2));
+        this.error(error, { exit: 1 });
+    }
     async finally(_) {
         if (this.updateNotice && !this.isJsonOutput()) {
             this.log(this.updateNotice);
@@ -221,6 +233,19 @@ export default class BaseCommand extends Command {
         const forceUpdateCheck = process.env.XANO_FORCE_UPDATE_CHECK === '1';
         this.updateNotice = checkForUpdate(this.config.version, forceUpdateCheck);
     }
+    /** Raw-argv check: the parsed flags are not available yet when the banner prints. */
+    isJsonOutput() {
+        const args = this.argv;
+        for (let i = 0; i < args.length; i++) {
+            if (args[i] === '--output' && args[i + 1] === 'json')
+                return true;
+            if (args[i] === '-o' && args[i + 1] === 'json')
+                return true;
+            if (args[i] === '--output=json' || args[i] === '-o=json')
+                return true;
+        }
+        return false;
+    }
     loadCredentialsFile() {
         const credentialsPath = this.getCredentialsPath();
         if (!fs.existsSync(credentialsPath)) {
@@ -354,18 +379,19 @@ export default class BaseCommand extends Command {
             ...(timeoutMs > 0 && !options.signal ? { signal: AbortSignal.timeout(timeoutMs) } : {}),
         });
         const contentType = headers['Content-Type'] || 'application/json';
+        const logDiagnostic = this.isJsonOutput() ? this.logToStderr.bind(this) : this.log.bind(this);
         if (verbose) {
-            this.log('');
-            this.log('─'.repeat(60));
-            this.log(`→ ${method} ${url}`);
-            this.log(`  Content-Type: ${contentType}`);
+            logDiagnostic('');
+            logDiagnostic('─'.repeat(60));
+            logDiagnostic(`→ ${method} ${url}`);
+            logDiagnostic(`  Content-Type: ${contentType}`);
             if (authToken) {
-                this.log(`  Authorization: Bearer ${authToken.slice(0, 8)}...${authToken.slice(-4)}`);
+                logDiagnostic(`  Authorization: Bearer ${authToken.slice(0, 8)}...${authToken.slice(-4)}`);
             }
             if (options.body) {
                 const bodyStr = typeof options.body === 'string' ? options.body : String(options.body);
                 const bodyPreview = bodyStr.length > 500 ? bodyStr.slice(0, 500) + '...' : bodyStr;
-                this.log(`  Body: ${bodyPreview}`);
+                logDiagnostic(`  Body: ${bodyPreview}`);
             }
         }
         const startTime = Date.now();
@@ -381,7 +407,7 @@ export default class BaseCommand extends Command {
             if (dispatcherSupported && isInvalidDispatcherError(error)) {
                 dispatcherSupported = false;
                 if (verbose) {
-                    this.log('  (this Node runtime rejected undici dispatcher; retrying without it — see DEV-7773)');
+                    logDiagnostic('  (this Node runtime rejected undici dispatcher; retrying without it — see DEV-7773)');
                 }
                 response = await fetch(url, buildFetchOptions(false));
             }
@@ -391,9 +417,9 @@ export default class BaseCommand extends Command {
         }
         const elapsed = Date.now() - startTime;
         if (verbose) {
-            this.log(`← ${response.status} ${response.statusText} (${elapsed}ms)`);
-            this.log('─'.repeat(60));
-            this.log('');
+            logDiagnostic(`← ${response.status} ${response.statusText} (${elapsed}ms)`);
+            logDiagnostic('─'.repeat(60));
+            logDiagnostic('');
         }
         return response;
     }
@@ -468,18 +494,6 @@ export default class BaseCommand extends Command {
         conclude(`stopped waiting after ${Math.round(timeoutMs / 1000)}s (last status: ${stage || 'unknown'})`);
         return stage;
     }
-    isJsonOutput() {
-        const args = process.argv;
-        for (let i = 0; i < args.length; i++) {
-            if (args[i] === '--output' && args[i + 1] === 'json')
-                return true;
-            if (args[i] === '-o' && args[i + 1] === 'json')
-                return true;
-            if (args[i] === '--output=json' || args[i] === '-o=json')
-                return true;
-        }
-        return false;
-    }
     /**
      * Find and parse the nearest project-local profile.yaml, unless an explicit
      * -p/XANO_PROFILE was given (in which case the local file is ignored).

package/dist/commands/branch/set_live/index.d.ts

@@ -8,11 +8,25 @@ export default class BranchSetLive extends BaseCommand {
     static flags: {
         force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'policy-override': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         workspace: import("@oclif/core/interfaces").OptionFlag<number | 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>;
     };
+    /** Set once the set-live policy gate refuses, the one failure that exits 2. */
+    private refusedByPolicyGate;
+    /** Exit 2 is the set-live gate's refusal; every other failure, flag errors included, exits 1. */
+    protected catch(error: Error & {
+        oclif?: {
+            exit?: number;
+        };
+    }): Promise<void>;
     run(): Promise<void>;
     private confirm;
+    /**
+     * The set-live gate refused: the verdict on stdout (under `-o json`, `{set_live: false, message,
+     * policy_gate}`), then the platform's message and how to proceed, exiting 2.
+     */
+    private refuseSetLive;
 }

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

@@ -1,5 +1,6 @@
 import { Args, Flags } from '@oclif/core';
 import BaseCommand from '../../../base-command.js';
+import { BLANK_POLICY_OVERRIDE, blankPolicyOverride, gateOverrideHint, gateRefusal, liveGateLines, quoted, } from '../../../utils/policy/gate.js';
 export default class BranchSetLive extends BaseCommand {
     static args = {
         branch_label: Args.string({
@@ -40,14 +41,25 @@ Branch 'v1' is now live
             options: ['summary', 'json'],
             required: false,
         }),
+        'policy-override': Flags.string({ description: 'Set the branch live past a blocking set-live policy gate with an audited reason (requires workspace:policy update)', hidden: true }),
         workspace: Flags.integer({
             char: 'w',
             description: 'Workspace ID (uses profile workspace if not provided)',
             required: false,
         }),
     };
+    /** Set once the set-live policy gate refuses, the one failure that exits 2. */
+    refusedByPolicyGate = false;
+    /** Exit 2 is the set-live gate's refusal; every other failure, flag errors included, exits 1. */
+    async catch(error) {
+        if (this.refusedByPolicyGate)
+            return super.catch(error);
+        return this.catchAsOperational(error);
+    }
     async run() {
         const { args, flags } = await this.parse(BranchSetLive);
+        if (blankPolicyOverride(flags['policy-override']))
+            this.error(BLANK_POLICY_OVERRIDE);
         const { profile } = this.resolveProfile(flags);
         // Get workspace ID from flag or profile
         const workspaceId = flags.workspace || profile.workspace;
@@ -66,16 +78,23 @@ Branch 'v1' is now live
         }
         // Construct the API URL
         const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/branch/${encodeURIComponent(branchLabel)}/live`;
+        // A reason from someone with workspace:policy update sets the branch live past a blocking gate.
+        const overrideReason = flags['policy-override']?.trim();
         // Set branch as live via the API
         try {
             const response = await this.verboseFetch(apiUrl, {
+                ...(overrideReason ? { body: JSON.stringify({ override_reason: overrideReason }) } : {}),
                 headers: {
                     'accept': 'application/json',
                     'Authorization': `Bearer ${profile.access_token}`,
+                    ...(overrideReason ? { 'Content-Type': 'application/json' } : {}),
                 },
                 method: 'POST',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
+                const refused = await gateRefusal(response);
+                if (refused)
+                    this.refuseSetLive(refused, flags, branchLabel);
                 const errorText = await response.text();
                 this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
             }
@@ -89,6 +108,8 @@ Branch 'v1' is now live
             }
         }
         catch (error) {
+            if (this.refusedByPolicyGate)
+                throw error;
             if (error instanceof Error) {
                 this.error(`Failed to set branch as live: ${error.message}`);
             }
@@ -111,4 +132,21 @@ Branch 'v1' is now live
             });
         });
     }
+    /**
+     * The set-live gate refused: the verdict on stdout (under `-o json`, `{set_live: false, message,
+     * policy_gate}`), then the platform's message and how to proceed, exiting 2.
+     */
+    refuseSetLive(refused, flags, branchLabel) {
+        if (flags.output === 'json') {
+            this.log(JSON.stringify({ message: refused.message, policy_gate: refused.answer, set_live: false }, null, 2));
+        }
+        else {
+            for (const line of liveGateLines(refused.answer, 'branch'))
+                this.log(line);
+        }
+        const workspace = flags.workspace ? ` -w ${flags.workspace}` : '';
+        const hint = gateOverrideHint(refused.answer, `xano branch set_live ${quoted(branchLabel)}${workspace} --policy-override "<why>"`);
+        this.refusedByPolicyGate = true;
+        this.error(`${refused.message}${hint}`, { exit: 2 });
+    }
 }

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

@@ -4,6 +4,7 @@ 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';
+import { policiesSkippedNotice } from '../../../utils/policy/feedback.js';
 /** Status glyph for one microservice row in the `--wait` progress block. */
 const icon = (e) => {
     if (!isAwaited(e))
@@ -168,13 +169,17 @@ Skip preview and push immediately
             truncate: flags.truncate,
             verbose: flags.verbose,
         };
-        await executePush({
+        const result = await executePush({
             accessToken: profile.access_token,
             branch: '',
             command: this,
             inputDir,
             verboseFetch: this.verboseFetch.bind(this),
         }, target, pushFlags);
+        // When the platform leaves policy files out, it says so once.
+        const skipped = policiesSkippedNotice(result.response ?? result.preview);
+        if (skipped)
+            this.warn(skipped);
         // --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).

package/dist/commands/function/create/index.d.ts

@@ -7,13 +7,28 @@ export default class FunctionCreate extends BaseCommand {
         edit: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'policy-override': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         stdin: 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>;
     };
+    /** Set once the publish policy gate refuses, the one failure that exits 2. */
+    private refusedByPolicyGate;
+    /** Exit 2 is the publish gate's refusal; every other failure, flag errors included, exits 1. */
+    protected catch(error: Error & {
+        oclif?: {
+            exit?: number;
+        };
+    }): Promise<void>;
     run(): Promise<void>;
     private editFile;
     private readStdin;
+    /**
+     * The live-branch publish gate refused the new function: the verdict on stdout (under `-o json`,
+     * `{created: false, message, policy_gate}`), then the platform's message and how to proceed,
+     * exiting 2.
+     */
+    private refusePublish;
 }

package/dist/commands/function/create/index.js

@@ -4,6 +4,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import path from 'node:path';
 import BaseCommand from '../../../base-command.js';
+import { BLANK_POLICY_OVERRIDE, blankPolicyOverride, gateRefusal, publishRefusal, quoted } from '../../../utils/policy/gate.js';
 export default class FunctionCreate extends BaseCommand {
     static args = {};
     static description = 'Create a new function in a workspace';
@@ -59,6 +60,7 @@ Name: my_function
             options: ['summary', 'json'],
             required: false,
         }),
+        'policy-override': Flags.string({ description: 'Create the function past a blocking live-branch publish policy gate with an audited reason (requires workspace:policy update)', hidden: true }),
         stdin: Flags.boolean({
             char: 's',
             default: false,
@@ -72,8 +74,18 @@ Name: my_function
             required: false,
         }),
     };
+    /** Set once the publish policy gate refuses, the one failure that exits 2. */
+    refusedByPolicyGate = false;
+    /** Exit 2 is the publish gate's refusal; every other failure, flag errors included, exits 1. */
+    async catch(error) {
+        if (this.refusedByPolicyGate)
+            return super.catch(error);
+        return this.catchAsOperational(error);
+    }
     async run() {
         const { flags } = await this.parse(FunctionCreate);
+        if (blankPolicyOverride(flags['policy-override']))
+            this.error(BLANK_POLICY_OVERRIDE);
         const { profile, profileName } = this.resolveProfile(flags);
         // Determine workspace_id from flag or profile
         let workspaceId;
@@ -133,6 +145,10 @@ Name: my_function
         const queryParams = new URLSearchParams({
             include_xanoscript: 'false',
         });
+        // A reason from someone with workspace:policy update saves past a blocking publish gate.
+        const overrideReason = flags['policy-override']?.trim();
+        if (overrideReason)
+            queryParams.set('override_reason', overrideReason);
         const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/function?${queryParams.toString()}`;
         // Create function via API
         try {
@@ -146,6 +162,9 @@ Name: my_function
                 method: 'POST',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
+                const refused = await gateRefusal(response);
+                if (refused)
+                    this.refusePublish(refused, flags);
                 const errorText = await response.text();
                 this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
             }
@@ -166,6 +185,8 @@ Name: my_function
             }
         }
         catch (error) {
+            if (this.refusedByPolicyGate)
+                throw error;
             if (error instanceof Error) {
                 this.error(`Failed to create function: ${error.message}`);
             }
@@ -239,4 +260,22 @@ Name: my_function
             process.stdin.resume();
         });
     }
+    /**
+     * The live-branch publish gate refused the new function: the verdict on stdout (under `-o json`,
+     * `{created: false, message, policy_gate}`), then the platform's message and how to proceed,
+     * exiting 2.
+     */
+    refusePublish(refused, flags) {
+        const workspace = flags.workspace ? ` -w ${quoted(flags.workspace)}` : '';
+        const source = flags.file ? ` -f ${quoted(flags.file)}` : ' --stdin';
+        const { lines, message } = publishRefusal(refused, {
+            json: flags.output === 'json',
+            outcome: 'created',
+            rerun: `xano function create${workspace}${source} --policy-override "<why>"`,
+        });
+        for (const line of lines)
+            this.log(line);
+        this.refusedByPolicyGate = true;
+        this.error(message, { exit: 2 });
+    }
 }

package/dist/commands/function/edit/index.d.ts

@@ -9,6 +9,7 @@ export default class FunctionEdit extends BaseCommand {
         edit: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'policy-override': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         publish: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         stdin: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -16,10 +17,24 @@ export default class FunctionEdit extends BaseCommand {
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
+    /** Set once the publish policy gate refuses, the one failure that exits 2. */
+    private refusedByPolicyGate;
+    /** Exit 2 is the publish gate's refusal; every other failure, flag errors included, exits 1. */
+    protected catch(error: Error & {
+        oclif?: {
+            exit?: number;
+        };
+    }): Promise<void>;
     run(): Promise<void>;
     private editFile;
     private editFunctionContent;
     private fetchFunctionCode;
     private promptForFunctionId;
     private readStdin;
+    /**
+     * The live-branch publish gate refused the update: the verdict on stdout (under `-o json`,
+     * `{updated: false, message, policy_gate}`), then the platform's message and how to proceed,
+     * exiting 2.
+     */
+    private refusePublish;
 }