@xano/cli 1.3.3 → 1.3.4

package/README.md

@@ -199,6 +199,7 @@ xano workspace pull -d ./my-workspace                    # Specify output direct
 xano workspace pull -b dev                               # Specific 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
@@ -212,6 +213,11 @@ 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
@@ -244,6 +250,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
@@ -820,6 +864,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 +872,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 +1022,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/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,8 +1,9 @@
 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';
 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.';
@@ -24,6 +25,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 +67,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 +88,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 +114,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 +135,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,13 +161,17 @@ 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({
             accessToken: profile.access_token,
@@ -135,6 +182,11 @@ 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);
         if (flags.review) {

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/workspace/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 Pull extends BaseCommand {
     static description: string;
     static examples: string[];
@@ -8,6 +14,7 @@ export default class Pull 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>;
         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>;

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

@@ -5,6 +5,17 @@ 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 { recordEntriesForPaths, resolveTarget, 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 Pull extends BaseCommand {
     static description = 'Pull a workspace multidoc from the Xano Metadata API and split into individual files';
     static examples = [
@@ -22,6 +33,9 @@ Pulled 58 documents
 `,
         `$ xano workspace pull --draft`,
         `$ xano workspace pull -b dev`,
+        `$ xano workspace pull --sync-state
+Write .xano/sync_state.json after pulling; later pulls keep it current while it exists
+`,
     ];
     static flags = {
         ...BaseCommand.baseFlags,
@@ -51,6 +65,11 @@ Pulled 58 documents
             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,
+        }),
         workspace: Flags.string({
             char: 'w',
             description: 'Workspace ID (optional if set in profile)',
@@ -140,6 +159,7 @@ Pulled 58 documents
         // Track filenames per type to handle duplicates
         const filenameCounters = new Map();
         let writtenCount = 0;
+        const writtenPaths = [];
         for (const doc of documents) {
             const { baseName, typeDir } = resolveDocumentPath(doc, outputDir, {
                 getApiGroupFolder,
@@ -160,6 +180,7 @@ Pulled 58 documents
             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 ────────────────────────────────────────────────────
@@ -173,5 +194,38 @@ Pulled 58 documents
         if (knowledgeCount > 0)
             parts.push(`${knowledgeCount} knowledge file${knowledgeCount === 1 ? '' : 's'}`);
         this.log(`Pulled ${parts.join(' + ')} 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;
+        }
+        const origin = profile.instance_origin.replace(/\/$/, '');
+        try {
+            const target = await resolveTarget(profile.instance_origin, workspaceId, branch, async (pathname) => {
+                const response = await this.verboseFetch(`${origin}/api:meta${pathname}`, {
+                    headers: {
+                        accept: 'application/json',
+                        Authorization: `Bearer ${profile.access_token}`,
+                    },
+                    method: 'GET',
+                }, flags.verbose, profile.access_token);
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}`);
+                }
+                return response.json();
+            });
+            if (!target) {
+                this.warn('Could not resolve workspace/branch fingerprints; skipped writing .xano/sync_state.json');
+                return;
+            }
+            const entries = recordEntriesForPaths(outputDir, writtenPaths);
+            saveSyncState(outputDir, target, entries, { replace: true });
+        }
+        catch (error) {
+            this.warn(`Skipped writing .xano/sync_state.json: ${error.message}`);
+        }
     }
 }

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

@@ -9,14 +9,18 @@ export default class Push extends BaseCommand {
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         env: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         exclude: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        fast: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         guids: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         include: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         records: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        refresh: 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>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        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/workspace/push/index.js

@@ -1,7 +1,8 @@
 import { Flags } from '@oclif/core';
 import * as fs from 'node:fs';
-import { resolve } from 'node:path';
+import { basename, relative, resolve } from 'node:path';
 import BaseCommand from '../../../base-command.js';
+import { formatWorkspacePushDefaultsBanner, resolvePushDefaults } from '../../../utils/local-config.js';
 import { executePush } from '../../../utils/multidoc-push.js';
 export default class Push extends BaseCommand {
     static description = '[IMPORTANT] ALWAYS run --dry-run first and show the user the output before pushing. Push local documents to a workspace. 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.';
@@ -23,6 +24,18 @@ Preview changes without pushing
 `,
         `$ xano workspace push --force
 Skip preview and push immediately (for CI/CD)
+`,
+        `$ xano workspace push --fast
+Push only files that changed since the last sync, and write .xano/sync_state.json
+`,
+        `$ xano workspace push --fast --refresh
+Re-compare local files against the server export, then push changes
+`,
+        `$ xano workspace push --no-fast
+Push without --fast even when profile.yaml sets fast: true
+`,
+        `$ xano workspace push --writeback
+Push and write server-formatted XanoScript back to local files
 `,
         `$ xano workspace push -d ./output -w 40
 Pushed 15 documents from ./output
@@ -95,6 +108,11 @@ Full sync including knowledge files; removes server objects not present locally
             multiple: true,
             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 server export once. Can be set as `fast: true` in profile.yaml.',
+            required: false,
+        }),
         force: Flags.boolean({
             default: false,
             description: '[CRITICAL] NEVER run without explicit user confirmation. Skips preview and confirmation prompt (for CI/CD pipelines).',
@@ -117,6 +135,11 @@ Full sync including knowledge files; removes server objects not present locally
             description: '[CRITICAL] STOP and ALWAYS run --dry-run first to show the user a preview before pushing live table records. Includes table records in import.',
             required: false,
         }),
+        refresh: Flags.boolean({
+            default: false,
+            description: 'With --fast, re-compare local files against the server export even when a sync record exists',
+            required: false,
+        }),
         sync: Flags.boolean({
             default: false,
             description: 'Full push — send all files, not just changed ones. Required for --delete.',
@@ -138,6 +161,15 @@ Full sync including knowledge files; removes server objects not present locally
             description: 'Workspace ID (optional if set in profile)',
             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(Push);
@@ -164,6 +196,17 @@ Full sync including knowledge files; removes server objects not present locally
         }
         const branch = flags.branch || profile.branch || '';
         const baseUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}`;
+        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()}`,
@@ -178,14 +221,19 @@ Full sync including knowledge files; removes server objects not present locally
             'dry-run': flags['dry-run'],
             env: flags.env,
             exclude: flags.exclude,
+            fast: pushDefaults.fast,
             force: flags.force,
             guids: flags.guids,
             include: flags.include,
             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'],
+            writebackObjectLimit: this.localProfile?.config.writeback_object_limit,
         };
         await executePush({
             accessToken: profile.access_token,
@@ -196,6 +244,11 @@ Full sync including knowledge files; removes server objects not present locally
                 listUrl: () => `${baseUrl}/knowledge/sync`,
                 rootDir: inputDir,
             },
+            syncTarget: {
+                instanceOrigin: profile.instance_origin,
+                kind: 'workspace',
+                workspace: workspaceId,
+            },
             verboseFetch: this.verboseFetch.bind(this),
         }, target, pushFlags);
     }