@xano/cli 1.3.3 → 1.3.5-beta.0

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

@@ -10,4 +10,11 @@ export default class ReleaseList extends BaseCommand {
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
+    /**
+     * The releases' stored policy checks, read once for the whole list. The list never fails or
+     * changes because of this read: it answers `null` when the checks cannot be read (the Policies
+     * feature is off, the credential lacks `workspace:policy` read, or the request failed), and the
+     * list then prints as it would without policies.
+     */
+    private policyChecks;
 }

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

@@ -1,6 +1,7 @@
 import { Flags } from '@oclif/core';
 import BaseCommand from '../../../base-command.js';
 import { buildPagingJson } from '../../../utils/paging.js';
+import { readReleasePolicyChecks, releasePolicyCheckTag } from '../../../utils/policy/release.js';
 export default class ReleaseList extends BaseCommand {
     static description = 'List all releases in a workspace';
     static examples = [
@@ -57,22 +58,19 @@ Releases in workspace 5:
             else {
                 this.error('Unexpected API response format');
             }
+            const checks = await this.policyChecks(profile, String(workspaceId), releases, flags.verbose);
             if (flags.output === 'json') {
-                this.log(JSON.stringify(buildPagingJson({ items: releases }, { tier: 'none' }), null, 2));
+                this.log(JSON.stringify(buildPagingJson({ items: withPolicyChecks(releases, checks) }, { tier: 'none' }), null, 2));
             }
             else if (releases.length === 0) {
                 this.log('No releases found');
             }
             else {
                 this.log(`Releases in workspace ${workspaceId}:`);
-                for (const release of releases) {
-                    const branch = release.branch ? ` - ${release.branch}` : '';
-                    const hotfix = release.hotfix ? ' [hotfix]' : '';
-                    const createdAt = release.created_at
-                        ? ` (${new Date(release.created_at).toLocaleString(undefined, { timeZoneName: 'short' })})`
-                        : '';
-                    this.log(`  - ${release.name} (ID: ${release.id})${branch}${hotfix}${createdAt}`);
-                }
+                for (const release of releases)
+                    this.log(releaseLine(release, checks));
+                if (checks)
+                    this.log('Policy check details: xano policy runs --release <name>');
             }
         }
         catch (error) {
@@ -84,4 +82,43 @@ Releases in workspace 5:
             }
         }
     }
+    /**
+     * The releases' stored policy checks, read once for the whole list. The list never fails or
+     * changes because of this read: it answers `null` when the checks cannot be read (the Policies
+     * feature is off, the credential lacks `workspace:policy` read, or the request failed), and the
+     * list then prints as it would without policies.
+     */
+    async policyChecks(profile, workspace, releases, verbose) {
+        if (releases.length === 0)
+            return null;
+        return readReleasePolicyChecks({ logToStderr: (message) => this.logToStderr(message), verboseFetch: (...args) => this.verboseFetch(...args) }, { branch: '', profile, verbose, workspace }, releases.map(release => release.id));
+    }
+}
+/** A release's summary line, tagged with its stored check when the checks were read. */
+function releaseLine(release, checks) {
+    const branch = release.branch ? ` - ${release.branch}` : '';
+    const hotfix = release.hotfix ? ' [hotfix]' : '';
+    const createdAt = release.created_at
+        ? ` (${new Date(release.created_at).toLocaleString(undefined, { timeZoneName: 'short' })})`
+        : '';
+    const policies = checks ? ` ${releasePolicyCheckTag(checks.get(release.id))}` : '';
+    return `  - ${release.name} (ID: ${release.id})${branch}${hotfix}${createdAt}${policies}`;
+}
+/**
+ * The releases for `-o json`: each gains `policy_check` (its stored check as the platform lists
+ * it, without the release id it is keyed by, or `null` for a release with no stored check) when
+ * the checks were read, and stays as served when they could not be, so a reader can tell an
+ * unchecked release (`null`) from checks the CLI could not read (absent).
+ */
+function withPolicyChecks(releases, checks) {
+    if (!checks)
+        return releases;
+    return releases.map(release => {
+        const check = checks.get(release.id);
+        if (!check)
+            return { ...release, policy_check: null };
+        const stored = { ...check };
+        delete stored.release_id;
+        return { ...release, policy_check: stored };
+    });
 }

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

@@ -2,7 +2,9 @@ import { Flags } from '@oclif/core';
 import * as fs from 'node:fs';
 import path from 'node:path';
 import BaseCommand from '../../../base-command.js';
-import { findFilesWithGuid } from '../../../utils/document-parser.js';
+import { findFilesWithGuid, parseDocument } from '../../../utils/document-parser.js';
+import { policiesSkippedNotice } from '../../../utils/policy/feedback.js';
+import { releasePolicyRunLines } from '../../../utils/policy/release.js';
 export default class ReleasePush extends BaseCommand {
     static description = '[IMPORTANT] ALWAYS confirm with the user before creating a release from local files. Creates a new release from local XanoScript files via the multidoc endpoint.';
     static examples = [
@@ -110,6 +112,12 @@ Output release details as JSON
         if (documentEntries.length === 0) {
             this.error(`All .xs files in ${flags.directory} are empty`);
         }
+        // A release carries its policy files like its code.
+        const policyKeys = documentEntries
+            .map((entry) => parseDocument(entry.content))
+            .filter((document) => document?.type === 'policy')
+            .map((document) => document.name)
+            .sort();
         const multidoc = documentEntries.map((d) => d.content).join('\n---\n');
         // Construct the API URL with query params
         const queryParams = new URLSearchParams({
@@ -158,6 +166,10 @@ Output release details as JSON
                 this.error(errorMessage);
             }
             const release = (await response.json());
+            // The platform says which policy files it left out: all of them while the Policies feature is
+            // off, and those of a caller who may not author policies, whose release carries the live
+            // branch's policies instead.
+            const skipped = policiesSkippedNotice(release);
             if (flags.output === 'json') {
                 this.log(JSON.stringify(release, null, 2));
             }
@@ -171,8 +183,14 @@ Output release details as JSON
                     this.log(`  Description: ${release.description}`);
                 const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
                 this.log(`  Documents: ${documentEntries.length}`);
+                if (policyKeys.length > 0 && !skipped)
+                    this.log(`  Policy documents: ${policyKeys.length} (${policyKeys.join(', ')})`);
+                for (const line of releasePolicyRunLines(release.policy_run, release.name ?? flags.name))
+                    this.log(line);
                 this.log(`  Time: ${elapsed}s`);
             }
+            if (skipped)
+                this.warn(skipped);
         }
         catch (error) {
             if (error instanceof Error) {

package/dist/commands/sandbox/delete/index.js

@@ -1,5 +1,7 @@
 import { Flags } from '@oclif/core';
+import { dirname } from 'node:path';
 import BaseCommand from '../../../base-command.js';
+import { invalidateSandboxMarkerForOrigin } from '../../../utils/sandbox-marker.js';
 export default class SandboxDelete extends BaseCommand {
     static description = '[CRITICAL] NEVER run without explicit user confirmation; this destroys all sandbox data. Deletes your sandbox environment completely (debugging only — it will be re-created on next access).';
     static examples = [
@@ -43,6 +45,12 @@ Sandbox environment deleted.
                 this.error(message);
             }
             this.log('Sandbox environment deleted.');
+            try {
+                invalidateSandboxMarkerForOrigin(dirname(this.getCredentialsPath()), profile.instance_origin);
+            }
+            catch (error) {
+                this.warn(`Skipped invalidating sandbox sync marker: ${error.message}`);
+            }
         }
         catch (error) {
             if (error instanceof Error && 'oclif' in error)

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

@@ -1,4 +1,10 @@
 import BaseCommand from '../../../base-command.js';
+/**
+ * Whether pull should write `.xano/sync_state.json`: only when asked to, or to keep an existing
+ * record current. A `--draft` pull never writes it, because `--fast` compares against published
+ * versions and recording draft bodies as synced would stop those drafts from being pushed.
+ */
+export declare function syncStateAction(flag: boolean, dir: string, draft: boolean): 'draft' | 'skip' | 'write';
 export default class SandboxPull extends BaseCommand {
     static description: string;
     static examples: string[];
@@ -7,6 +13,7 @@ export default class SandboxPull extends BaseCommand {
         draft: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         env: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         records: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'sync-state': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         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>;

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

@@ -5,6 +5,18 @@ import path from 'node:path';
 import BaseCommand from '../../../base-command.js';
 import { buildApiGroupFolderResolver, buildChannelServerResolver, parseDocument, resolveDocumentPath, } from '../../../utils/document-parser.js';
 import { fetchKnowledge, writeKnowledge } from '../../../utils/knowledge-sync.js';
+import { writeMarkerToken } from '../../../utils/sandbox-marker.js';
+import { instanceHost, recordEntriesForPaths, sandboxTargetIdentity, saveSyncState, syncStateExists, } from '../../../utils/sync-state.js';
+/**
+ * Whether pull should write `.xano/sync_state.json`: only when asked to, or to keep an existing
+ * record current. A `--draft` pull never writes it, because `--fast` compares against published
+ * versions and recording draft bodies as synced would stop those drafts from being pushed.
+ */
+export function syncStateAction(flag, dir, draft) {
+    if (!flag && !syncStateExists(dir))
+        return 'skip';
+    return draft ? 'draft' : 'write';
+}
 export default class SandboxPull extends BaseCommand {
     static description = 'Pull documents from your sandbox environment and split into individual files';
     static examples = [
@@ -15,6 +27,9 @@ Pulled 42 documents from sandbox environment to current directory
 Pulled 42 documents from sandbox environment to ./my-sandbox
 `,
         `$ xano sandbox pull --env --records`,
+        `$ xano sandbox pull --sync-state
+Write .xano/sync_state.json after pulling; later pulls keep it current while it exists
+`,
     ];
     static flags = {
         ...BaseCommand.baseFlags,
@@ -39,6 +54,11 @@ Pulled 42 documents from sandbox environment to ./my-sandbox
             description: 'Include records',
             required: false,
         }),
+        'sync-state': Flags.boolean({
+            default: false,
+            description: 'Write .xano/sync_state.json after a successful pull. Needed only the first time; later pulls keep the record current while it exists.',
+            required: false,
+        }),
     };
     async run() {
         const { flags } = await this.parse(SandboxPull);
@@ -97,6 +117,7 @@ Pulled 42 documents from sandbox environment to ./my-sandbox
         const getChannelServer = buildChannelServerResolver(documents);
         const filenameCounters = new Map();
         let writtenCount = 0;
+        const writtenPaths = [];
         for (const doc of documents) {
             const { baseName, typeDir } = resolveDocumentPath(doc, outputDir, {
                 getApiGroupFolder,
@@ -115,6 +136,7 @@ Pulled 42 documents from sandbox environment to ./my-sandbox
             const filename = count === 0 ? `${baseName}.xs` : `${baseName}_${count + 1}.xs`;
             const filePath = path.join(typeDir, filename);
             fs.writeFileSync(filePath, doc.content, 'utf8');
+            writtenPaths.push(filePath);
             writtenCount++;
         }
         // ── Pull knowledge ────────────────────────────────────────────────────
@@ -128,5 +150,32 @@ Pulled 42 documents from sandbox environment to ./my-sandbox
         if (knowledgeCount > 0)
             parts.push(`${knowledgeCount} knowledge file${knowledgeCount === 1 ? '' : 's'}`);
         this.log(`Pulled ${parts.join(' + ')} from sandbox environment to ${flags.directory}`);
+        const syncState = syncStateAction(flags['sync-state'], outputDir, flags.draft);
+        if (syncState === 'skip') {
+            return;
+        }
+        if (syncState === 'draft') {
+            this.warn('Skipped writing .xano/sync_state.json: --draft pulls draft versions, which --fast does not compare against');
+            return;
+        }
+        try {
+            const tenant = await this.getOrCreateSandbox(profile, flags.verbose);
+            if (typeof tenant.created_at !== 'string') {
+                this.warn('Could not resolve sandbox fingerprints; skipped writing .xano/sync_state.json');
+                return;
+            }
+            const target = sandboxTargetIdentity(instanceHost(profile.instance_origin), {
+                created_at: tenant.created_at,
+                id: tenant.id,
+            });
+            const sandboxToken = writeMarkerToken(path.dirname(this.getCredentialsPath()), target.instance_host, target.branch_created_at);
+            saveSyncState(outputDir, target, recordEntriesForPaths(outputDir, writtenPaths), {
+                replace: true,
+                sandboxToken,
+            });
+        }
+        catch (error) {
+            this.warn(`Skipped writing .xano/sync_state.json: ${error.message}`);
+        }
     }
 }

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

@@ -7,13 +7,17 @@ export default class SandboxPush extends BaseCommand {
         directory: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         env: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        fast: 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>;
+        refresh: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         review: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         sync: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         transaction: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         truncate: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        writeback: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'writeback-diff': 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>;

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

@@ -1,9 +1,11 @@
 import { Flags } from '@oclif/core';
 import * as fs from 'node:fs';
-import { resolve } from 'node:path';
+import { basename, dirname, relative, resolve } from 'node:path';
 import open from 'open';
 import BaseCommand from '../../../base-command.js';
+import { formatWorkspacePushDefaultsBanner, resolvePushDefaults } from '../../../utils/local-config.js';
 import { executePush } from '../../../utils/multidoc-push.js';
+import { policiesSkippedNotice } from '../../../utils/policy/feedback.js';
 export default class SandboxPush extends BaseCommand {
     static description = '[IMPORTANT] ALWAYS run --dry-run first and show the user the output before pushing. Push local documents to your sandbox environment via multidoc import. By default, only changed files are pushed (partial mode). Use --sync to push all files. Shows a preview of changes before pushing unless --force is specified. Use --dry-run to preview only. Include/exclude glob filters are intentionally not supported on sandbox push — partial pushes can hide deletions during review and lead to data loss when promoted to the workspace. Pushing into a sandbox that currently holds a different workspace will prompt for confirmation; run `xano sandbox reset` first to start clean.';
     static examples = [
@@ -24,6 +26,18 @@ Preview changes without pushing
 `,
         `$ xano sandbox push --force
 Skip preview and push immediately
+`,
+        `$ xano sandbox push --fast
+Push only files that changed since the last sync, and write .xano/sync_state.json
+`,
+        `$ xano sandbox push --fast --refresh
+Re-compare local files against the sandbox export, then push changes
+`,
+        `$ xano sandbox push --no-fast
+Push without --fast even when profile.yaml sets fast: true
+`,
+        `$ xano sandbox push --writeback
+Push and write server-formatted XanoScript back to local files
 `,
         `$ xano sandbox push --records --env`,
         `$ xano sandbox push --truncate`,
@@ -54,6 +68,11 @@ Push and open sandbox review in the browser
             description: 'Include environment variables in import',
             required: false,
         }),
+        fast: Flags.boolean({
+            allowNo: true,
+            description: 'Skip files whose contents match .xano/sync_state.json, and write or update that record. Without a record, compares against the sandbox export once. Can be set as `fast: true` in profile.yaml.',
+            required: false,
+        }),
         force: Flags.boolean({
             default: false,
             description: 'Skip preview and confirmation prompt (for CI/CD pipelines)',
@@ -70,6 +89,11 @@ Push and open sandbox review in the browser
             description: 'Include records in import',
             required: false,
         }),
+        refresh: Flags.boolean({
+            default: false,
+            description: 'With --fast, re-compare local files against the sandbox export even when a sync record exists',
+            required: false,
+        }),
         review: Flags.boolean({
             default: false,
             description: 'Open sandbox review in the browser after pushing',
@@ -91,6 +115,15 @@ Push and open sandbox review in the browser
             description: '[CRITICAL] STOP and confirm with the user; this truncates live tables before importing.',
             required: false,
         }),
+        writeback: Flags.boolean({
+            allowNo: true,
+            description: 'After a successful push, write server-formatted XanoScript back to the files that were pushed. Can be set as `writeback: true` in profile.yaml.',
+            required: false,
+        }),
+        'writeback-diff': Flags.string({
+            description: 'With --writeback, save local vs server copies of rewritten files under this directory',
+            required: false,
+        }),
     };
     async run() {
         const { flags } = await this.parse(SandboxPush);
@@ -103,6 +136,17 @@ Push and open sandbox review in the browser
             this.error(`Not a directory: ${inputDir}`);
         }
         const baseUrl = `${profile.instance_origin}/api:meta/sandbox`;
+        const pushDefaults = resolvePushDefaults({
+            flagFast: flags.fast,
+            flagWriteback: flags.writeback,
+            localFast: this.localProfile?.config.fast,
+            localWriteback: this.localProfile?.config.writeback,
+            sync: flags.sync,
+        });
+        if (pushDefaults.fromLocal.length > 0 && this.localProfile) {
+            const relativePath = relative(process.cwd(), this.localProfile.path) || basename(this.localProfile.path);
+            this.log(formatWorkspacePushDefaultsBanner(pushDefaults.fromLocal, relativePath));
+        }
         const target = {
             buildDryRunUrl: (params) => `${baseUrl}/multidoc/dry-run?${params.toString()}`,
             buildPushUrl: (params) => `${baseUrl}/multidoc?${params.toString()}`,
@@ -118,15 +162,19 @@ Push and open sandbox review in the browser
             delete: flags.delete,
             'dry-run': flags['dry-run'],
             env: flags.env,
+            fast: pushDefaults.fast,
             force: flags.force,
             guids: flags.guids,
             records: flags.records,
+            refresh: flags.refresh,
             sync: flags.sync,
             transaction: flags.transaction,
             truncate: flags.truncate,
             verbose: flags.verbose,
+            writeback: pushDefaults.writeback,
+            writebackDiff: flags['writeback-diff'],
         };
-        await executePush({
+        const result = await executePush({
             accessToken: profile.access_token,
             branch: '',
             command: this,
@@ -135,8 +183,17 @@ Push and open sandbox review in the browser
                 listUrl: () => `${baseUrl}/knowledge/sync`,
                 rootDir: inputDir,
             },
+            syncTarget: {
+                instanceOrigin: profile.instance_origin,
+                kind: 'sandbox',
+                markerDir: dirname(this.getCredentialsPath()),
+            },
             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);
         if (flags.review) {
             await this.openReview(profile.instance_origin, profile.access_token, flags.verbose);
         }

package/dist/commands/sandbox/reset/index.js

@@ -1,6 +1,8 @@
 import { Flags } from '@oclif/core';
+import { dirname } from 'node:path';
 import BaseCommand from '../../../base-command.js';
 import { pushKnowledge } from '../../../utils/knowledge-sync.js';
+import { invalidateSandboxMarkerForOrigin } from '../../../utils/sandbox-marker.js';
 export default class SandboxReset extends BaseCommand {
     static description = '[CRITICAL] NEVER run without explicit user confirmation; this clears all workspace data and drafts. Resets your sandbox environment.';
     static examples = [
@@ -55,6 +57,12 @@ Sandbox environment has been reset.
                 this.warn(`Sandbox environment was reset, but clearing knowledge files failed: ${error instanceof Error ? error.message : String(error)}`);
             }
             this.log('Sandbox environment has been reset.');
+            try {
+                invalidateSandboxMarkerForOrigin(dirname(this.getCredentialsPath()), profile.instance_origin);
+            }
+            catch (error) {
+                this.warn(`Skipped invalidating sandbox sync marker: ${error.message}`);
+            }
         }
         catch (error) {
             if (error instanceof Error && 'oclif' in error)

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

@@ -0,0 +1,30 @@
+import PolicyCommand from '../../../policy-command.js';
+/**
+ * The SKILL.md a coding agent reads: the CLI's own frontmatter (`name` and `description`), the
+ * instance's content below it. The CLI always writes the frontmatter itself and drops any block the
+ * served content opens with: frontmatter configures the agent (`allowed-tools`, `hooks`, `model`),
+ * and a workspace knowledge record may replace the platform skill, so its text must never set it.
+ * The description is written as a double-quoted YAML scalar, so a `:` or `#` in it stays a
+ * description instead of becoming syntax.
+ */
+export declare function buildSkillDocument(description: string, content: string): string;
+export default class SkillsPull extends PolicyCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        directory: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        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>;
+    };
+    /** Any failure exits 1 with its own message: this is not a `policy *` command to name. */
+    protected catch(error: Error & {
+        oclif?: {
+            exit?: number;
+        };
+    }): Promise<void>;
+    run(): Promise<void>;
+}

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

@@ -0,0 +1,118 @@
+import { Flags } from '@oclif/core';
+import * as fs from 'node:fs';
+import path from 'node:path';
+import PolicyCommand from '../../../policy-command.js';
+/** The one skill this command installs. The instance generates it from its check catalogue. */
+const SKILL = 'xano-policies';
+/**
+ * The served content without a leading YAML frontmatter block, if it opens with one: the lines up
+ * to and including the closing `---`, and the blank lines after it.
+ */
+function stripFrontmatter(content) {
+    if (!/^---\r?\n/.test(content))
+        return content;
+    const lines = content.split(/\r?\n/);
+    const close = lines.indexOf('---', 1);
+    if (close === -1)
+        return content;
+    let start = close + 1;
+    while (start < lines.length && lines[start].trim() === '')
+        start++;
+    return lines.slice(start).join('\n');
+}
+/**
+ * The SKILL.md a coding agent reads: the CLI's own frontmatter (`name` and `description`), the
+ * instance's content below it. The CLI always writes the frontmatter itself and drops any block the
+ * served content opens with: frontmatter configures the agent (`allowed-tools`, `hooks`, `model`),
+ * and a workspace knowledge record may replace the platform skill, so its text must never set it.
+ * The description is written as a double-quoted YAML scalar, so a `:` or `#` in it stays a
+ * description instead of becoming syntax.
+ */
+export function buildSkillDocument(description, content) {
+    // Exactly one trailing newline, whatever the instance sent, so a re-pull is byte-identical.
+    const body = `${stripFrontmatter(content).replace(/\n+$/, '')}\n`;
+    return `---\nname: ${SKILL}\ndescription: ${JSON.stringify(description)}\n---\n\n${body}`;
+}
+/** True when the path is a symbolic link; false when it is anything else or does not exist. */
+function isSymbolicLink(filePath) {
+    try {
+        return fs.lstatSync(filePath).isSymbolicLink();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+/**
+ * Whether the served skill is the workspace's own knowledge record. A stored record has a positive
+ * id; the skill the platform generates has none of its own (the platform serves it under a
+ * negative sentinel id), so an item without a positive id is the platform's.
+ */
+function isWorkspaceRecord(skill) {
+    return typeof skill.id === 'number' && Number.isInteger(skill.id) && skill.id > 0;
+}
+export default class SkillsPull extends PolicyCommand {
+    static description = `Install the ${SKILL} agent skill this instance generates
+
+Writes <directory>/.claude/skills/${SKILL}/SKILL.md, the project skill folder Claude Code reads, and replaces that file without a backup. A copy installed anywhere else, such as a global ~/.claude/skills/${SKILL} or another agent's skills folder, is not touched: remove it, so the agent does not load it instead.`;
+    static examples = [
+        `$ xano skills pull
+Wrote .claude/skills/${SKILL}/SKILL.md (${SKILL} skill for workspace 40, branch live)
+`,
+        '$ xano skills pull -d ./my-project',
+        '$ xano skills pull -b dev -o json',
+    ];
+    static flags = {
+        ...PolicyCommand.policyFlags,
+        directory: Flags.string({
+            char: 'd',
+            default: '.',
+            description: `Project directory whose .claude/skills/${SKILL}/SKILL.md is written (defaults to current directory)`,
+            required: false,
+        }),
+    };
+    /** Any failure exits 1 with its own message: this is not a `policy *` command to name. */
+    async catch(error) {
+        return this.catchAsOperational(error);
+    }
+    async run() {
+        const { flags } = await this.parse(SkillsPull);
+        // The route lives beside /policy under the workspace and is gated by the same
+        // `workspace:policy` permission, so it answers failures the way the policy commands do.
+        const { branch, request, workspace } = this.policyTarget(flags, { label: 'Agent skills', path: '/agent-skills' });
+        // `surface=cli` asks for the terminal wording of the skill, not the Studio one.
+        const payload = (await request('', 'GET', undefined, { surface: 'cli' }));
+        const items = Array.isArray(payload?.knowledge) ? payload.knowledge : [];
+        const skill = items.find((item) => typeof item?.name === 'string' && item.name.trim().toLowerCase() === SKILL);
+        if (!skill) {
+            this.error(`The instance returned no ${SKILL} skill for workspace ${workspace}, branch ${branch || 'live'}.`);
+        }
+        const document = buildSkillDocument(skill.description ?? '', skill.content ?? '');
+        const filePath = path.join(path.resolve(flags.directory), '.claude', 'skills', SKILL, 'SKILL.md');
+        // Writing through a symbolic link would overwrite whatever it points at.
+        if (isSymbolicLink(filePath)) {
+            this.error(`${filePath} is a symbolic link; remove it and run the command again. Nothing was written.`);
+        }
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        // The file is regenerated on every pull and no backup is kept.
+        fs.writeFileSync(filePath, document, 'utf8');
+        const own = isWorkspaceRecord(skill);
+        if (flags.output === 'json') {
+            this.log(JSON.stringify({
+                branch,
+                bytes: Buffer.byteLength(document, 'utf8'),
+                name: SKILL,
+                path: filePath,
+                source: own ? 'workspace' : 'platform',
+                workspace,
+            }, null, 2));
+            return;
+        }
+        const relative = path.relative(process.cwd(), filePath);
+        const shown = relative && !relative.startsWith('..') ? relative : filePath;
+        this.log(`Wrote ${shown} (${SKILL} skill for workspace ${workspace}, branch ${branch || 'live'})`);
+        if (own)
+            this.log(`This is the workspace's own ${SKILL} knowledge record, which replaces the platform skill.`);
+    }
+}

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

@@ -6,6 +6,8 @@ export default class TenantCreate extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
+        allow_deploy_bypass: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        allow_quick_deploy: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         cluster_id: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
         description: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         domain: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -13,6 +15,7 @@ export default class TenantCreate extends BaseCommand {
         license: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         platform_id: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        required_reviewers: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         tasks: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         type: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

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

@@ -17,9 +17,20 @@ Created tenant: Production (production) - ID: 42
 `,
         `$ xano tenant create "Staging" --description "Staging env" --cluster_id 1 --platform_id 1 --type tier2 -o json`,
         `$ xano tenant create "Staging" --type tier2 --cluster_id 1 --license ./license.yaml`,
+        `$ xano tenant create "Production" --required_reviewers 1 --allow_deploy_bypass`,
     ];
     static flags = {
         ...BaseCommand.baseFlags,
+        allow_deploy_bypass: Flags.boolean({
+            default: false,
+            description: 'Allow authorized users to bypass the deploy approval gate on this tenant (via tenant_deploy_request bypass). Has no effect unless --required_reviewers is also set above 0.',
+            required: false,
+        }),
+        allow_quick_deploy: Flags.boolean({
+            default: false,
+            description: 'Allow this tenant to skip the deploy approval gate entirely for quick deploys, regardless of --required_reviewers.',
+            required: false,
+        }),
         cluster_id: Flags.integer({
             description: 'Cluster ID to deploy to (required for tier2/tier3)',
             required: false,
@@ -54,6 +65,11 @@ Created tenant: Production (production) - ID: 42
             description: 'Platform ID to use',
             required: false,
         }),
+        required_reviewers: Flags.integer({
+            default: 0,
+            description: 'When greater than 0, that many distinct reviewers must approve a tenant_deploy_request before a release may be deployed to this tenant. 0 (default) means not gated.',
+            required: false,
+        }),
         tasks: Flags.boolean({
             allowNo: true,
             default: true,
@@ -79,6 +95,11 @@ Created tenant: Production (production) - ID: 42
             this.error('No workspace ID provided. Use --workspace flag or set one in your profile.');
         }
         const body = {
+            deploy_settings: {
+                allow_deploy_bypass: flags.allow_deploy_bypass,
+                allow_quick_deploy: flags.allow_quick_deploy,
+                required_reviewers: flags.required_reviewers,
+            },
             display: args.display,
             ingress: flags.ingress,
             license: flags.type,