@xano/sdk 1.0.12 → 1.0.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +28 -0
- package/README.md +36 -36
- package/dist/.build-fingerprint +1 -1
- package/dist/{agent-file-refresh-YM5VRRHE.js → agent-file-refresh-3J6YRVFL.js} +12 -11
- package/dist/{agent-skill-command-GVVCBAGF.js → agent-skill-command-VWDMQWCT.js} +51 -50
- package/dist/{answer-shape-CBUQRSXI.js → answer-shape-AVZSKBR6.js} +4 -4
- package/dist/{backend-dir-NZOLU7TL.js → backend-dir-ISP7RVF2.js} +11 -10
- package/dist/{backend-slot-X5AUX2TT.js → backend-slot-DZAUHLTS.js} +3 -3
- package/dist/bin.js +47 -46
- package/dist/{branch-YS2K3VOB.js → branch-IJTBZZFO.js} +8 -8
- package/dist/{branch-commands-Q46PCVHU.js → branch-commands-75IYFTBS.js} +26 -25
- package/dist/{chunk-EMAFZROF.js → chunk-2FDHIBEU.js} +8 -8
- package/dist/{chunk-CPFWVB3V.js → chunk-2KOB4QPW.js} +13 -13
- package/dist/{chunk-PCHIHVX6.js → chunk-2LF734YB.js} +4 -4
- package/dist/{chunk-R7XZW4SB.js → chunk-3H7R4ISR.js} +2 -2
- package/dist/{chunk-ANBIMJPM.js → chunk-3SZ7QRYA.js} +36 -10
- package/dist/{chunk-DB7P2SSK.js → chunk-45K2QZBR.js} +3 -3
- package/dist/{chunk-C2SAVXAB.js → chunk-4MX5LMPQ.js} +2 -2
- package/dist/{chunk-IZI3SYXH.js → chunk-5FJ4M4HB.js} +38 -38
- package/dist/{chunk-LDSZPRGV.js → chunk-5TWLVFYB.js} +4 -4
- package/dist/{chunk-JKGRQW6D.js → chunk-5W7S2SCA.js} +4 -4
- package/dist/{chunk-F2NFNYCB.js → chunk-6ILHYSLR.js} +3 -3
- package/dist/{chunk-IFXPHVPY.js → chunk-6LJS4M6P.js} +3 -3
- package/dist/{chunk-CTUIMNEM.js → chunk-6X73VFCX.js} +2 -2
- package/dist/{chunk-DZUNF7IH.js → chunk-75QC66XI.js} +2 -2
- package/dist/{chunk-5SZSLAAC.js → chunk-7F3V6CFP.js} +3 -3
- package/dist/{chunk-2PAVJ3QD.js → chunk-B7CPSWQX.js} +7 -7
- package/dist/{chunk-4CS4DKQC.js → chunk-BEKEOXNG.js} +2 -2
- package/dist/{chunk-EC5P4W2D.js → chunk-BSGU4HS6.js} +44 -44
- package/dist/{chunk-U5CTYBAN.js → chunk-CB67GIR3.js} +26 -8
- package/dist/{chunk-M7DIIJPW.js → chunk-DBDTQR23.js} +4 -4
- package/dist/{chunk-5RSPMSSQ.js → chunk-DERQSEB5.js} +9 -9
- package/dist/{chunk-RZABQ4YH.js → chunk-DGYXCIBV.js} +4 -4
- package/dist/{chunk-BXVNRUDB.js → chunk-DLDYQNGP.js} +3 -3
- package/dist/{chunk-I2AVVARA.js → chunk-ECQXASG3.js} +2 -2
- package/dist/{chunk-2BHYGUTI.js → chunk-EQXHUWUO.js} +2 -2
- package/dist/{chunk-ONNSFD73.js → chunk-EYVIUX2T.js} +9 -9
- package/dist/{chunk-JFPLHK6Y.js → chunk-FBSGFPZ4.js} +2 -2
- package/dist/{chunk-EGEANMMK.js → chunk-FIERONKM.js} +2 -2
- package/dist/{chunk-K6BQPFRS.js → chunk-GBSHHNSD.js} +3 -3
- package/dist/{chunk-N3XSXGAL.js → chunk-GCINMMFL.js} +2 -2
- package/dist/{chunk-POZ6V4MU.js → chunk-GKQTXUOW.js} +2 -2
- package/dist/{chunk-HJSAGGHU.js → chunk-GOKRKTCX.js} +3 -3
- package/dist/{chunk-D4VKPOD4.js → chunk-GRXX2TOJ.js} +13 -112
- package/dist/{chunk-YJK4NPXC.js → chunk-GVHWIDEJ.js} +3 -3
- package/dist/{chunk-NZ7ML6LG.js → chunk-HINRE3UM.js} +5 -5
- package/dist/{chunk-OKR66IGL.js → chunk-HK554MDD.js} +7 -7
- package/dist/{chunk-WXLZCBPG.js → chunk-HKI5Y5KW.js} +14 -14
- package/dist/{chunk-HA5Y645X.js → chunk-HMYJOQXT.js} +23 -23
- package/dist/{chunk-DILYWJVP.js → chunk-HXFLHA5K.js} +2 -2
- package/dist/{chunk-A2AOUBJS.js → chunk-IHL2O7VY.js} +2 -2
- package/dist/{chunk-FLDFKG24.js → chunk-IKXXTRMN.js} +4 -4
- package/dist/{chunk-UZ55F3UK.js → chunk-IWJ6GFST.js} +4 -4
- package/dist/{chunk-AMHAGMJM.js → chunk-J3XLCYTQ.js} +80 -80
- package/dist/{chunk-2K2G5TSR.js → chunk-J62TYONQ.js} +3 -3
- package/dist/{chunk-MFEO3EHL.js → chunk-KDEU5FUJ.js} +3 -3
- package/dist/{chunk-VA4JK4TW.js → chunk-KMKUH2IO.js} +3 -3
- package/dist/{chunk-VTMTIBKP.js → chunk-L34DM6QB.js} +2 -2
- package/dist/{chunk-PBIV4DE2.js → chunk-L4WG4BKJ.js} +68 -68
- package/dist/{chunk-7XOQXZ6W.js → chunk-LB76VK6D.js} +7 -7
- package/dist/{chunk-E763QI3G.js → chunk-LJZIBT75.js} +2 -2
- package/dist/{chunk-ETMP7SJ3.js → chunk-LPQZICYN.js} +6 -6
- package/dist/{chunk-UFFIU57H.js → chunk-LSJ3SQEU.js} +4 -4
- package/dist/{chunk-RFB4EXM5.js → chunk-LW7TOIS7.js} +8 -8
- package/dist/{chunk-TOW4EJON.js → chunk-MAXDJZQR.js} +5 -5
- package/dist/{chunk-7NNLRNXE.js → chunk-MIS6F4HM.js} +4 -4
- package/dist/{chunk-WZXEQUIM.js → chunk-MTBKTGZT.js} +2 -2
- package/dist/{chunk-74NRFGL7.js → chunk-MYIIBV6A.js} +5 -5
- package/dist/{chunk-3RZ4UJWV.js → chunk-N6LGLNAC.js} +4 -4
- package/dist/{chunk-H7GMGZHI.js → chunk-NDV6CBR7.js} +2 -2
- package/dist/{chunk-RNVGXJJZ.js → chunk-NOW522B4.js} +13 -13
- package/dist/{chunk-DFCYAEBE.js → chunk-NUZXSIEA.js} +3 -3
- package/dist/{chunk-DYGRTWAI.js → chunk-O44MJTLR.js} +3 -3
- package/dist/{chunk-DH32QXVI.js → chunk-OLQN4Z5R.js} +53 -61
- package/dist/{chunk-2RDZDDPR.js → chunk-P4OWRYE7.js} +28 -28
- package/dist/{chunk-373AVIL2.js → chunk-QAEBBTYR.js} +7 -7
- package/dist/{chunk-6IOBEJWA.js → chunk-QJ25N4W6.js} +4 -4
- package/dist/{chunk-OK7CBTFW.js → chunk-QKHNJ7LE.js} +5 -5
- package/dist/{chunk-3ZVSOZZC.js → chunk-QRMKQYCB.js} +2 -2
- package/dist/{chunk-4GSXWOBS.js → chunk-QX5XQEYB.js} +5 -7
- package/dist/{chunk-4COXXP55.js → chunk-RDZBXTZ3.js} +4 -4
- package/dist/{chunk-U4DSFCH5.js → chunk-RPBB7P4Q.js} +2 -2
- package/dist/{chunk-W5MKVFBQ.js → chunk-RV2BDU7V.js} +5 -5
- package/dist/{chunk-XFQAA2SU.js → chunk-RVAEPPRH.js} +2 -2
- package/dist/{chunk-6QJORUHC.js → chunk-RYWNNJK5.js} +2 -2
- package/dist/{chunk-JPAUQ7MK.js → chunk-SAEIVQLP.js} +3 -3
- package/dist/{chunk-H5FAYLCR.js → chunk-SPLRKCFV.js} +2 -2
- package/dist/{chunk-3XZ44H2E.js → chunk-SUKO4SZG.js} +63 -55
- package/dist/{chunk-B5N6EWOM.js → chunk-UQ2OD7D4.js} +3 -3
- package/dist/{chunk-G3A3XKCS.js → chunk-VBSCWV5H.js} +49 -49
- package/dist/chunk-VYJYDMY6.js +9 -0
- package/dist/{chunk-C4TZP5PQ.js → chunk-WS2X5BB2.js} +5 -5
- package/dist/{chunk-P5JF3U65.js → chunk-WS4BA75E.js} +37 -4
- package/dist/{chunk-SAYHY2N3.js → chunk-XCFQLP6G.js} +8 -8
- package/dist/{chunk-OCNTMJSY.js → chunk-XPSDDTUZ.js} +3 -3
- package/dist/{chunk-OBRMA2VK.js → chunk-XY4OBD26.js} +3 -3
- package/dist/{chunk-XVOODRNK.js → chunk-Y5XAPLZS.js} +4 -4
- package/dist/{chunk-WQNN6WLB.js → chunk-YFQCDLCQ.js} +14 -14
- package/dist/{chunk-SAKWZG5I.js → chunk-YL3WVBR5.js} +9 -9
- package/dist/{chunk-XM56DAM7.js → chunk-YR3MNGWZ.js} +8 -8
- package/dist/{chunk-HUEFVPYW.js → chunk-YTQYP7UJ.js} +3 -3
- package/dist/{chunk-KICERNAP.js → chunk-Z3DQ7ULY.js} +4 -4
- package/dist/{chunk-JHQAVWHW.js → chunk-Z4BQPABS.js} +2 -2
- package/dist/{chunk-6LECAG3Y.js → chunk-ZMJRAMLA.js} +4 -4
- package/dist/{chunk-AUYXBKGR.js → chunk-ZOHEHIFS.js} +2 -2
- package/dist/{chunk-A3CT26GX.js → chunk-ZRXDPCMN.js} +2 -2
- package/dist/cli.js +45 -44
- package/dist/{codegen-command-H3HO7UFA.js → codegen-command-JWOW6HE5.js} +63 -62
- package/dist/codegen.js +2 -2
- package/dist/{commands-IFRAGWGK.js → commands-5ILSWDSV.js} +2 -2
- package/dist/{completion-RTXCODHS.js → completion-UNKBVVDT.js} +2 -2
- package/dist/{config-EHFXNFSP.js → config-NTOASFCA.js} +3 -3
- package/dist/{deploy-command-7PWQJ4VV.js → deploy-command-WESYWFJN.js} +52 -51
- package/dist/{deploy-source-CJHEVGOS.js → deploy-source-ZQQNMDFX.js} +27 -26
- package/dist/{dev-env-sync-VVLYQUPR.js → dev-env-sync-4XJT7WOT.js} +46 -45
- package/dist/{display-name-hint-BKPMISQU.js → display-name-hint-MYXCCAOP.js} +10 -10
- package/dist/{env-example-refresh-GLFC2FTE.js → env-example-refresh-4V2OCDJE.js} +64 -63
- package/dist/{env-pull-command-OY3SXNJC.js → env-pull-command-SK5FS477.js} +42 -41
- package/dist/{env-target-PDDDAA5I.js → env-target-TEFSYACA.js} +9 -9
- package/dist/{env-var-command-UTYDJN24.js → env-var-command-IJHKA2WJ.js} +37 -36
- package/dist/{ephemeral-CART6DIR.js → ephemeral-VLPRDNEJ.js} +8 -8
- package/dist/{ephemeral-command-ALIHUF7G.js → ephemeral-command-WCO5J4SN.js} +43 -42
- package/dist/{ephemeral-state-HPKSKC4Y.js → ephemeral-state-RUOU2GFS.js} +7 -7
- package/dist/{generate-command-S37XFYPD.js → generate-command-3WCOUOEQ.js} +68 -67
- package/dist/{gitignore-DKDWGWPS.js → gitignore-WYS3GMOX.js} +15 -14
- package/dist/{guards-RU4C7TFG.js → guards-PPIBIMFZ.js} +6 -6
- package/dist/{impersonate-command-HPCSKJAV.js → impersonate-command-UMYVQTCG.js} +33 -32
- package/dist/{import-RUBCGLCA.js → import-T4ZTOTBT.js} +4 -4
- package/dist/index.js +11 -11
- package/dist/{init-command-RWXBXJPG.js → init-command-UR5MSXIH.js} +50 -51
- package/dist/{init-modules-LFLW2PQC.js → init-modules-7KALFI5C.js} +7 -7
- package/dist/{init-web-OGKACAOC.js → init-web-DYE2FEXL.js} +2 -2
- package/dist/internal.js +72 -66
- package/dist/{keep-data-merge-7JGGZKDM.js → keep-data-merge-OVHCIEBG.js} +24 -24
- package/dist/{lambda-config-reconcile-FXPDH2U5.js → lambda-config-reconcile-VOBVZPWS.js} +3 -3
- package/dist/{landing-record-QJV7KNS4.js → landing-record-AIHNW4AZ.js} +17 -16
- package/dist/{live-diff-HARRGFV4.js → live-diff-UMSOGPX3.js} +6 -6
- package/dist/{local-engine-choice-NNSHE5FO.js → local-engine-choice-XDGTATKJ.js} +30 -29
- package/dist/{local-engine-command-UGIZ4UO6.js → local-engine-command-VQWNQ7UK.js} +35 -34
- package/dist/{local-engine-deploy-ZZVHBI2X.js → local-engine-deploy-4N4NFZ4T.js} +11 -11
- package/dist/{local-engine-lookup-QFRKO35F.js → local-engine-lookup-AQTUGSBT.js} +2 -2
- package/dist/{local-engine-mcp-bridge-T2EFRRAF.js → local-engine-mcp-bridge-AMYRH4SY.js} +9 -9
- package/dist/{local-engine-mcp-command-YUSZC7MF.js → local-engine-mcp-command-AIMNMXQG.js} +41 -48
- package/dist/{local-engine-process-XH35DURU.js → local-engine-process-OD5OSWDG.js} +6 -6
- package/dist/{local-engine-update-check-HAXE7BVG.js → local-engine-update-check-G3YCBXRE.js} +4 -4
- package/dist/{lock-commands-VT4R2DEE.js → lock-commands-H3YV2D6M.js} +50 -49
- package/dist/{login-command-4D3KPQUY.js → login-command-NMM3JNDZ.js} +23 -22
- package/dist/{logout-command-ALKHCJKS.js → logout-command-7DYC6G32.js} +13 -12
- package/dist/{loop-QHZD37KX.js → loop-DJNIHC7O.js} +6 -6
- package/dist/{marketplace-command-64TE2NGV.js → marketplace-command-UCSHDZGO.js} +33 -33
- package/dist/{marketplace-resolve-HPCRNV5O.js → marketplace-resolve-JR4BBJ6K.js} +5 -5
- package/dist/{meta-client-7MLLUZB4.js → meta-client-CD3TXQP6.js} +10 -10
- package/dist/{module-manifest-EFE6JBZW.js → module-manifest-63I5GRK4.js} +3 -3
- package/dist/node.js +50 -49
- package/dist/{operation-outcome-TYAOVNOM.js → operation-outcome-2ONIIDRU.js} +19 -19
- package/dist/{output-target-63ECBUX2.js → output-target-67LHZKCO.js} +16 -15
- package/dist/{plan-disclosure-WEMB5ZJ2.js → plan-disclosure-T7DF4SRJ.js} +16 -16
- package/dist/{plugin-contributions-U5PAZKBE.js → plugin-contributions-YYEP7IWH.js} +4 -4
- package/dist/{plugin-prompt-O5PAMV5B.js → plugin-prompt-GKCQKNYI.js} +4 -4
- package/dist/{plugin-questions-ZVYNKDRB.js → plugin-questions-P7MA3TYI.js} +3 -3
- package/dist/plugin.d.ts +2 -1
- package/dist/{preflight-command-OUVAX5IJ.js → preflight-command-TJ7FURXB.js} +56 -55
- package/dist/{profile-command-NUO5U2HQ.js → profile-command-LDPLTJEJ.js} +24 -23
- package/dist/{profile-pointer-VTOZDBHM.js → profile-pointer-JJ7K5O2R.js} +3 -3
- package/dist/{project-dependency-EZNTHMWI.js → project-dependency-X3KCWBK5.js} +6 -6
- package/dist/{project-sdk-ZGJM4WYQ.js → project-sdk-YHJZRCNB.js} +3 -3
- package/dist/promote-command-RURHOLNR.js +148 -0
- package/dist/{prompt-F7UVH4GP.js → prompt-QNMJIWNI.js} +3 -3
- package/dist/{publish-command-KVGNFBSU.js → publish-command-IIRN6NWN.js} +55 -54
- package/dist/{pull-command-OVXIMVUB.js → pull-command-ITO76ENU.js} +66 -65
- package/dist/{pull-superseded-77UZ7CHH.js → pull-superseded-6HADGGC5.js} +3 -3
- package/dist/{release-command-E54WUJKB.js → release-command-CVGIUD4M.js} +60 -59
- package/dist/{release-ns-command-SLRL3O3W.js → release-ns-command-YLCQPVH3.js} +78 -77
- package/dist/{retry-command-S5QALD5Z.js → retry-command-LFZYEVRU.js} +7 -7
- package/dist/{routes-manifest-ET2TTSCL.js → routes-manifest-R3TQRB24.js} +6 -6
- package/dist/{routes-manifest-file-IX4TOZCO.js → routes-manifest-file-GYNYFKAH.js} +9 -9
- package/dist/scaffold.d.ts +0 -5
- package/dist/scaffold.js +2 -2
- package/dist/{secrets-file-4NQWGCJG.js → secrets-file-PCNAFXNV.js} +15 -14
- package/dist/{secrets-fill-command-5NNHSYFX.js → secrets-fill-command-G7NQMRXU.js} +49 -48
- package/dist/{seed-5YLQRT2D.js → seed-4CD55LB4.js} +6 -6
- package/dist/{source-resolve-HSJSVKUC.js → source-resolve-U4SJR7ZA.js} +17 -17
- package/dist/{static-host-TQP3FXPI.js → static-host-MO4VDHL7.js} +4 -4
- package/dist/{status-command-UFIMW7SZ.js → status-command-CD72PXIT.js} +60 -34
- package/dist/{store-ZE5BXCOW.js → store-AJX4MC7Y.js} +5 -5
- package/dist/{sync-baseline-JGAAOS25.js → sync-baseline-BJDKG4F2.js} +7 -7
- package/dist/{sync-contributions-35ZAYBUH.js → sync-contributions-XK6LHISZ.js} +8 -8
- package/dist/{sync-record-ILWS44DG.js → sync-record-NE62ERA3.js} +9 -9
- package/dist/{table-V3LTQUY6.js → table-WPRAM4VW.js} +8 -8
- package/dist/{tables-command-TISOU6DR.js → tables-command-NMTKR52H.js} +35 -34
- package/dist/{tenant-7WUS7Q6V.js → tenant-IIYECNWO.js} +9 -9
- package/dist/{tenant-command-ITCPN43T.js → tenant-command-XQAWT46C.js} +83 -82
- package/dist/{test-command-7SFAJ6HX.js → test-command-W4AD4KT4.js} +32 -31
- package/dist/{tests-ENFUACKD.js → tests-JWQRHFCT.js} +5 -5
- package/dist/{token-OXGOA6WE.js → token-P3VQ6ITJ.js} +9 -8
- package/dist/{toolchain-hooks-QIFGPGH2.js → toolchain-hooks-UAJBPSTC.js} +8 -8
- package/dist/{toolchain-modules-Q3Z6APPF.js → toolchain-modules-S3MPHCUI.js} +4 -4
- package/dist/{toolchain-peers-K44IINPG.js → toolchain-peers-FQJBTKEB.js} +7 -7
- package/dist/{tracked-backend-IYTIZZYV.js → tracked-backend-WWEPNUD5.js} +30 -29
- package/dist/{update-check-LSCQRDRR.js → update-check-O7QC5TBB.js} +48 -47
- package/dist/{upgrade-command-RQEQJO5Y.js → upgrade-command-J6LRNHYF.js} +51 -50
- package/dist/{whoami-command-NT3FVBZM.js → whoami-command-KWRP2CII.js} +12 -11
- package/dist/{workspace-5RHOJC7K.js → workspace-3YNK4XO4.js} +4 -4
- package/dist/{workspace-binding-YUU6KB53.js → workspace-binding-TTDNXHO5.js} +11 -10
- package/dist/{workspace-command-QSJHX5RS.js → workspace-command-W4ANGLCZ.js} +79 -78
- package/dist/{workspace-env-M7RYVJB3.js → workspace-env-6LJGCTZA.js} +12 -11
- package/dist/{workspace-export-GHMUSX2P.js → workspace-export-PUEXKZNS.js} +4 -4
- package/dist/{writable-Y6CE2CGK.js → writable-LMMG4AFZ.js} +3 -3
- package/dist/{xano-2A2GT7EH.js → xano-Z3SRHYOR.js} +7 -7
- package/dist/{xanosdk-import-4TLNYFKC.js → xanosdk-import-PNNMZ4SF.js} +5 -5
- package/dist/{xanosdk-project-4NH6332J.js → xanosdk-project-YW3BQY2E.js} +13 -12
- package/guides/README.md +3 -3
- package/guides/authoring.md +24 -18
- package/guides/bundle.md +2 -2
- package/guides/cli.md +204 -191
- package/guides/codegen.md +20 -19
- package/guides/codes.md +3 -3
- package/guides/coverage.md +5 -4
- package/guides/deploying.md +140 -133
- package/guides/environment.md +38 -38
- package/guides/marketplace.md +35 -29
- package/guides/module-contract.md +20 -15
- package/guides/object-kinds.md +12 -9
- package/guides/project-structure.md +4 -4
- package/guides/scaffold.md +44 -32
- package/guides/typed-frontend.md +10 -9
- package/llms/client.md +4 -4
- package/llms/errors.md +2 -2
- package/llms/fields.md +1 -1
- package/llms/kinds-agent-mcp.md +1 -1
- package/llms/kinds-knowledge.md +2 -2
- package/llms/kinds-realtime.md +2 -2
- package/llms/lock.md +3 -3
- package/llms/object-kinds.md +2 -2
- package/llms/statements-calls.md +1 -1
- package/llms/statements-runtime.md +2 -2
- package/llms/tests.md +3 -3
- package/llms/toolchain.md +2 -2
- package/llms-full.txt +61 -58
- package/llms.txt +36 -33
- package/manifest.json +2 -2
- package/package.json +1 -1
- package/skills/xano-backend/SKILL.md +7 -7
- package/dist/promote-command-MGLAYQDY.js +0 -147
package/guides/deploying.md
CHANGED
|
@@ -4,7 +4,7 @@ Authentication, ephemeral environments, static hosting, releasing to production,
|
|
|
4
4
|
|
|
5
5
|
## Signing in & deploying (in depth)
|
|
6
6
|
|
|
7
|
-
**Sign in once** with `
|
|
7
|
+
**Sign in once** with `npx @xano/sdk login`. It runs the standard authorization-code + PKCE
|
|
8
8
|
browser flow (powered by the OpenID-certified [`openid-client`](https://github.com/panva/openid-client)):
|
|
9
9
|
opens your browser, you approve, and the CLI captures the redirect on a `127.0.0.1`
|
|
10
10
|
callback. On first use it dynamically registers its own OAuth client (RFC 7591) so the
|
|
@@ -15,20 +15,20 @@ read from the token's own `aud` claim.
|
|
|
15
15
|
`login` also **pins the numeric workspace** you consented to into the credential, so every
|
|
16
16
|
later command acts on exactly that workspace without looking it up again. There is **no
|
|
17
17
|
`--workspace` flag** — a credential addresses exactly one instance and one workspace. Run
|
|
18
|
-
`
|
|
18
|
+
`npx @xano/sdk workspace details` to see which.
|
|
19
19
|
|
|
20
20
|
The credential caches by default in a **shared** `~/.xanosdk/auth.json`, reusable
|
|
21
|
-
from **any** project directory — so a single `
|
|
21
|
+
from **any** project directory — so a single `npx @xano/sdk login` covers all your projects.
|
|
22
22
|
Override the OAuth host with `--origin`/`$XANO_ORIGIN` and the loopback port with `--port`.
|
|
23
23
|
|
|
24
24
|
**Named profiles.** That file holds any number of credentials, each under a name.
|
|
25
|
-
`
|
|
25
|
+
`npx @xano/sdk login --profile staging` adds one without touching the others; `--profile <name>`
|
|
26
26
|
(or `-p`) selects one for a single command. See [Credential profiles](#credential-profiles)
|
|
27
27
|
below.
|
|
28
28
|
|
|
29
29
|
**When the browser can't reach this machine** — a remote shell, a container, a
|
|
30
30
|
Codespace — the `127.0.0.1` redirect lands nowhere and `login` waits five minutes for a
|
|
31
|
-
callback that will never arrive. Run `
|
|
31
|
+
callback that will never arrive. Run `npx @xano/sdk login --paste` instead. It binds nothing:
|
|
32
32
|
it prints the authorize URL, you finish signing in in whatever browser you have, and
|
|
33
33
|
your browser then fails to load the `127.0.0.1` callback — which is expected. Paste that
|
|
34
34
|
URL back from the address bar (or just the `code=` value out of it) and the sign-in
|
|
@@ -54,14 +54,14 @@ already has `prod` proceeds to consent: the guard is per profile, not per file.
|
|
|
54
54
|
`auth.json` holds a map of **named profiles** under a versioned envelope. Each profile is
|
|
55
55
|
one credential — one instance, one workspace — in one of two shapes:
|
|
56
56
|
|
|
57
|
-
- **`oauth`** — written by `
|
|
57
|
+
- **`oauth`** — written by `npx @xano/sdk login`. Refreshes and rotates. Do not hand-edit.
|
|
58
58
|
- **`token`** — a meta API bearer token for the same meta APIs, for automation. No login
|
|
59
|
-
flow, no refresh, no rotation. Store one with `
|
|
59
|
+
flow, no refresh, no rotation. Store one with `npx @xano/sdk profile add <name> --instance <url>
|
|
60
60
|
--workspace-id <n>`, which prompts for the token (or reads it piped on stdin) rather than
|
|
61
61
|
taking it as a flag (a secret on a command line lands in the process list and the shell
|
|
62
62
|
history), and checks it against the instance before storing it. The token
|
|
63
|
-
itself stays valid until you revoke it wherever you minted it — `
|
|
64
|
-
`
|
|
63
|
+
itself stays valid until you revoke it wherever you minted it — `npx @xano/sdk logout` and
|
|
64
|
+
`npx @xano/sdk profile delete` only remove the CLI's copy.
|
|
65
65
|
|
|
66
66
|
Both shapes work at **either** location (project-local `./.xano/auth.json` or global
|
|
67
67
|
`~/.xanosdk/auth.json`) on the same file precedence ladder below.
|
|
@@ -71,15 +71,15 @@ Both shapes work at **either** location (project-local `./.xano/auth.json` or gl
|
|
|
71
71
|
1. `--profile <name>` / `-p <name>` on the command line.
|
|
72
72
|
2. `xano.profile.json` at the project root — a committed, secret-free pointer naming one
|
|
73
73
|
profile, found by walking up from the working directory and stopping at the first
|
|
74
|
-
`package.json`. Write it with `
|
|
74
|
+
`package.json`. Write it with `npx @xano/sdk profile use <name>`. Nothing ambient outranks it:
|
|
75
75
|
a `$XANO_PROFILE` left in a shell rc cannot retarget a pinned project.
|
|
76
76
|
3. `$XANO_PROFILE`.
|
|
77
|
-
4. The credential file's own `default` key. Set it with `
|
|
77
|
+
4. The credential file's own `default` key. Set it with `npx @xano/sdk profile set-default <name>`.
|
|
78
78
|
5. The literal name `default`.
|
|
79
79
|
|
|
80
|
-
`
|
|
81
|
-
machine**. `
|
|
82
|
-
marked, and `
|
|
80
|
+
`npx @xano/sdk profile use` pins **this project**; `npx @xano/sdk profile set-default` changes **this
|
|
81
|
+
machine**. `npx @xano/sdk profile list` shows every profile with the default and the active one
|
|
82
|
+
marked, and `npx @xano/sdk whoami` and `npx @xano/sdk status` both report which profile is in play and
|
|
83
83
|
which rung chose it.
|
|
84
84
|
|
|
85
85
|
Writes are serialised on a lock and merge one profile at a time, so signing in, signing
|
|
@@ -97,7 +97,7 @@ as a fallback**: it uses `./.xano/auth.json` when present, otherwise `~/.xanosdk
|
|
|
97
97
|
so a `--local-auth` project keeps working without repeating the flag. `login` and `logout` do
|
|
98
98
|
**not** fall back: they target the shared global cache unless you pass `--local-auth`. A `logout`
|
|
99
99
|
naming a profile that only `./.xano/auth.json` holds exits 8 (not found in the shared file)
|
|
100
|
-
and names `
|
|
100
|
+
and names `npx @xano/sdk logout --local-auth -p <name>` — it does not report the session as gone. A
|
|
101
101
|
logout clears stored profiles only: with the `XANO_*` credential variables still set, it
|
|
102
102
|
says so, and commands keep authenticating with them. An explicit
|
|
103
103
|
`--config`/`$XANO_CONFIG` wins over both default file locations; only the three-variable
|
|
@@ -127,19 +127,19 @@ as JSON, while the human-readable progress (and the live URLs) echoes to stderr:
|
|
|
127
127
|
}
|
|
128
128
|
```
|
|
129
129
|
|
|
130
|
-
Present only when they apply: `
|
|
130
|
+
Present only when they apply: `engine` (in place of `ephemeral`), `keepDataSkipped` and the
|
|
131
131
|
merge lists (see [Keeping your data between deploys](#keeping-your-data-between-deploys)),
|
|
132
132
|
`static` (`url`; `canonical`, the build's identity, and `verified` when the frontend was
|
|
133
133
|
confirmed live serving it; `staticEnv` — `{ injected, keys, documents, skipped?, reason? }` — when config was
|
|
134
|
-
injected; or `error` with `retry`, the `
|
|
134
|
+
injected; or `error` with `retry`, the `npx @xano/sdk publish` that retries only the static step),
|
|
135
135
|
`microservices` (or `microservicesError`, `{ message, remedy }`, when their status could not be
|
|
136
136
|
read after the deploy), `testRun` (`total` — the whole suite, `passed + failed + notRun` —
|
|
137
137
|
`passed`, `failed`, `notRun`, and `tests[]` each with `kind`,
|
|
138
|
-
`name`, `qualified` — the `type:object/name` form `
|
|
138
|
+
`name`, `qualified` — the `type:object/name` form `npx @xano/sdk test run` takes (a query's object is its
|
|
139
139
|
lock key, `query:<group>|<verb>|<name>/<test>`), `workflow:<name>` for a workflow test — `object` for a
|
|
140
140
|
unit test (a query's carries `group` and `verb`), `status`, `message` (the first failure),
|
|
141
141
|
`expectations` for a unit test — every expectation in order, `{ index, status, message? }`, `index`
|
|
142
|
-
from 0 — and `timing` for a workflow test — the engine reports none for a unit test; plus `error` and `retry`, the `
|
|
142
|
+
from 0 — and `timing` for a workflow test — the engine reports none for a unit test; plus `error` and `retry`, the `npx @xano/sdk test run-all` to run
|
|
143
143
|
again, when the suite could not be run — exit 6 — and `unreachable`, the tests it never reached
|
|
144
144
|
(as `test run` takes them), when it stopped answering part-way; the same `N passed, M failed,
|
|
145
145
|
K not run` line `test run-all` prints closes the run), `landingRecord` (`{ destination, file,
|
|
@@ -150,7 +150,7 @@ exists), `unconfigured`, and `passwordHashesUnverifiable` (below). The raw
|
|
|
150
150
|
workspace blob is deliberately never dumped: it carries per-tenant secrets that must not land
|
|
151
151
|
in shell history or CI logs.
|
|
152
152
|
|
|
153
|
-
`
|
|
153
|
+
`npx @xano/sdk test run-all --json` (and `test run`, `test list`) writes the same per-test entries at
|
|
154
154
|
the top level, beside the backend they ran on: `kind`, `env` (the ephemeral's or tenant's handle;
|
|
155
155
|
`null` for a Xano Engine or a workspace), `name` (the backend's own name whatever its kind — the
|
|
156
156
|
same handle on an ephemeral or tenant, the engine's name on a Xano Engine) and `display` (its display
|
|
@@ -169,9 +169,9 @@ out and named (`--env-var GREETING`) — pass them again, or keep them in `xano/
|
|
|
169
169
|
`xano/.secrets.json`, which a deploy reads. The same text is the `--json` error's `message`.
|
|
170
170
|
|
|
171
171
|
**Where it goes** — the instance your **token is bound to** (the token's `aud`), never a
|
|
172
|
-
flag. `
|
|
172
|
+
flag. `npx @xano/sdk deploy --ephemeral` create-or-refreshes an **ephemeral**; a bare `npx @xano/sdk deploy`
|
|
173
173
|
runs the code on the Xano Engine on this machine instead ([below](#deploying-locally)). Reaching your real workspace is the separate release flow: cut a release from
|
|
174
|
-
what ran, then `
|
|
174
|
+
what ran, then `npx @xano/sdk promote <release>` lands it there as a new branch, leaving live
|
|
175
175
|
untouched until you say otherwise.
|
|
176
176
|
|
|
177
177
|
**Static host** — `deploy --static <dir>` archives a directory and deploys it to a
|
|
@@ -188,13 +188,13 @@ path, a file, an empty directory, or a build whose compressed archive is over th
|
|
|
188
188
|
cap is refused and nothing is deployed (`publish` checks the cap before it asks, too). An upload that fails
|
|
189
189
|
after the backend landed leaves the backend in place and still writes the deploy's own `--json`
|
|
190
190
|
summary (not a failure document), with `static` holding `error` (the reason, as printed),
|
|
191
|
-
`retry` (the `
|
|
191
|
+
`retry` (the `npx @xano/sdk publish` that retries only the static step) and `completed`. The exit
|
|
192
192
|
code says whether the frontend is up: `3` with `completed: "no"` when nothing was sent or the
|
|
193
193
|
host refused it, `9` with `completed: "unknown"` when the upload was sent and its answer lost
|
|
194
194
|
(a 5xx, a timeout, a dropped connection) — run `retry`, which settles it either way.
|
|
195
195
|
|
|
196
196
|
A **replacing** deploy clears the target's static hosting — whatever the flags, the replace
|
|
197
|
-
removes it — so a later plain `
|
|
197
|
+
removes it — so a later plain `npx @xano/sdk deploy`, or `deploy --to … --replace` (a workspace, a
|
|
198
198
|
tenant, or an ephemeral named as one), takes a published frontend down. Before the import (and
|
|
199
199
|
in a `--dry-run` plan) it reads which frontends the target is serving from the platform — one
|
|
200
200
|
another project or the dashboard published included — warns naming each URL, and reports them
|
|
@@ -240,25 +240,25 @@ prebuilt `frontend/dist` can retarget any environment with no rebuild.
|
|
|
240
240
|
> copy — `curl -s "$URL/?nocache=$(date +%s)"` — and check the fetched HTML for the injected
|
|
241
241
|
> `window.XANO_HOST` line rather than retrying the same cached URL.
|
|
242
242
|
|
|
243
|
-
`
|
|
243
|
+
`npx @xano/sdk status` prints the same **environment base URL** out of band, for cases where you'd
|
|
244
244
|
rather bake it in at build time — along with the environment's name and expiry, without your
|
|
245
|
-
having to know either. (`
|
|
245
|
+
having to know either. (`npx @xano/sdk whoami` prints the *instance* base URL, i.e. the account's
|
|
246
246
|
origin rather than the environment.) A static failure after a committed backend deploy **does not roll
|
|
247
|
-
back**: it exits `3` (`9` when the upload was sent and its answer lost) and prints the `
|
|
247
|
+
back**: it exits `3` (`9` when the upload was sent and its answer lost) and prints the `npx @xano/sdk publish` command that retries just that
|
|
248
248
|
step, without re-importing the backend.
|
|
249
249
|
|
|
250
|
-
**Publishing a frontend on its own** — `
|
|
250
|
+
**Publishing a frontend on its own** — `npx @xano/sdk publish <dir>` uploads an already-built
|
|
251
251
|
directory and nothing else: no compile, no backend import. `--to` picks the destination —
|
|
252
252
|
`ephemeral[:<name>]`, `workspace`, or `tenant:<name>`; left off, the backend this project last
|
|
253
253
|
deployed to — and a workspace or tenant asks before replacing what its users are served
|
|
254
254
|
(`--yes` in CI). After a local deploy it publishes to that engine (`--to local`
|
|
255
|
-
names it), server half included — the upload `
|
|
255
|
+
names it), server half included — the upload `npx @xano/sdk deploy --local --static <dir>`
|
|
256
256
|
makes, without re-importing the backend (below). Scaffolded projects carry it as
|
|
257
257
|
`npm run xano:deploy:frontend`, which rebuilds first.
|
|
258
258
|
|
|
259
259
|
```bash
|
|
260
|
-
|
|
261
|
-
|
|
260
|
+
npx @xano/sdk promote v2 --set-live # the backend, landed and live
|
|
261
|
+
npx @xano/sdk publish ./frontend/dist --to workspace --release v2 --branch <label> --yes
|
|
262
262
|
```
|
|
263
263
|
|
|
264
264
|
The destination's own URL is injected as `window.XANO_HOST` at publish time (under any
|
|
@@ -286,7 +286,7 @@ in `--json` `warnings` naming the build step.
|
|
|
286
286
|
|
|
287
287
|
`deploy` reuses cached tokens and **refreshes them automatically** when the access token
|
|
288
288
|
expires (Xano rotates the refresh token on every use; the new one is persisted). A rejected
|
|
289
|
-
refresh (`invalid_grant`) clears the stale cache and tells you to `
|
|
289
|
+
refresh (`invalid_grant`) clears the stale cache and tells you to `npx @xano/sdk login` again.
|
|
290
290
|
|
|
291
291
|
**CI & agents** run non-interactively. The credential to reach for is the **meta credential
|
|
292
292
|
as three environment variables** — the `type: "token"` record above, with no file:
|
|
@@ -295,7 +295,7 @@ as three environment variables** — the `type: "token"` record above, with no f
|
|
|
295
295
|
XANO_INSTANCE_URL=https://your-instance.xano.io \
|
|
296
296
|
XANO_WORKSPACE_ID=3 \
|
|
297
297
|
XANO_META_TOKEN=your-meta-api-token \
|
|
298
|
-
npx
|
|
298
|
+
npx @xano/sdk deploy ./xano/index.ts --ephemeral
|
|
299
299
|
```
|
|
300
300
|
|
|
301
301
|
Nothing is read from or written to disk, and nothing rotates, so the same three secrets keep
|
|
@@ -312,18 +312,18 @@ All three are required **together**. Setting some but not others is a hard error
|
|
|
312
312
|
rest, rather than a quiet fallback to another credential — a workflow with one misspelled
|
|
313
313
|
secret must not deploy against whatever happens to be on the runner.
|
|
314
314
|
|
|
315
|
-
> **Automated agents:** do **not** invoke `
|
|
315
|
+
> **Automated agents:** do **not** invoke `npx @xano/sdk login` — it blocks on interactive browser
|
|
316
316
|
> consent. Use the three variables above.
|
|
317
317
|
>
|
|
318
318
|
> The older `$XANO_REFRESH_TOKEN` + `$XANO_CLIENT_ID` pair still works (both copied once
|
|
319
|
-
> from the profile in `auth.json` after a local `
|
|
319
|
+
> from the profile in `auth.json` after a local `npx @xano/sdk login`; the target instance is read from the refresh
|
|
320
320
|
> token's `aud` and the workspace resolved per run), but Xano **rotates refresh tokens on
|
|
321
321
|
> use** — a stored one is spent by its first exchange, so a job that runs twice fails the
|
|
322
322
|
> second time. Prefer the meta credential.
|
|
323
323
|
|
|
324
|
-
## Checking against a live instance (
|
|
324
|
+
## Checking against a live instance (npx @xano/sdk preflight)
|
|
325
325
|
|
|
326
|
-
`
|
|
326
|
+
`npx @xano/sdk preflight` proves your compiled output against a **real, running Xano
|
|
327
327
|
instance** — not a static snapshot. It compiles your workspace, imports it into a
|
|
328
328
|
**fresh ephemeral environment created for that run**, exports it back, and diffs it
|
|
329
329
|
against what you compiled, so you catch three classes of problem a local build can't:
|
|
@@ -346,7 +346,7 @@ short expiry, so even a killed process leaves nothing permanent behind. A fresh
|
|
|
346
346
|
environment per run is also what makes the diff trustworthy: the objects read back
|
|
347
347
|
can only have come from this bundle, never from what a previous run left.
|
|
348
348
|
|
|
349
|
-
**Setup** — nothing, if you have run `
|
|
349
|
+
**Setup** — nothing, if you have run `npx @xano/sdk login`. With no `XANO_VALIDATE_*`
|
|
350
350
|
variable set, `preflight` uses the credential the rest of the CLI already acts on
|
|
351
351
|
and creates its ephemeral under the workspace that credential pins.
|
|
352
352
|
|
|
@@ -363,11 +363,11 @@ XANO_VALIDATE_TOKEN=your-meta-bearer-token
|
|
|
363
363
|
```
|
|
364
364
|
|
|
365
365
|
```bash
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
366
|
+
npx @xano/sdk preflight ./xano/index.ts # import + round-trip diff, reports per object (every authored kind)
|
|
367
|
+
npx @xano/sdk preflight ./xano/index.ts --runtime # + run each deployed function
|
|
368
|
+
npx @xano/sdk preflight ./xano/index.ts --capture # + write fetched JSON to ./validate-out (fixture candidates)
|
|
369
|
+
npx @xano/sdk preflight ./xano/index.ts --instance http://localhost:8080 # override the target for one run
|
|
370
|
+
npx @xano/sdk preflight --bundle ws.json # check an already-exported bundle
|
|
371
371
|
```
|
|
372
372
|
|
|
373
373
|
Two sources, and the environment wins. Set any `XANO_VALIDATE_*` variable (or
|
|
@@ -395,7 +395,7 @@ const HOST = (typeof window !== "undefined" && window.XANO_HOST) || import.meta.
|
|
|
395
395
|
```
|
|
396
396
|
|
|
397
397
|
`window.XANO_HOST` is the **environment** URL your deployed APIs answer at (the same value
|
|
398
|
-
`
|
|
398
|
+
`npx @xano/sdk status` prints as the environment's URL); it is *not* `npx @xano/sdk whoami`, which prints
|
|
399
399
|
your account's instance origin. Because injection happens at deploy time, a prebuilt
|
|
400
400
|
`frontend/dist` retargets any environment with **no rebuild** — ideal for headless agents.
|
|
401
401
|
Add your own public config (base URLs, *publishable* keys) with `--static-env KEY=VALUE`
|
|
@@ -436,16 +436,16 @@ retrying the bare URL.
|
|
|
436
436
|
|
|
437
437
|
| Command | Where it goes |
|
|
438
438
|
|---|---|
|
|
439
|
-
| `
|
|
440
|
-
| `
|
|
441
|
-
| `
|
|
442
|
-
| `
|
|
443
|
-
| `
|
|
444
|
-
| `
|
|
439
|
+
| `npx @xano/sdk deploy` | The **Xano Engine** on this machine — the default, with no flag and no Xano account needed ([below](#deploying-locally)). `--local` spells it out. |
|
|
440
|
+
| `npx @xano/sdk deploy --ephemeral` | A disposable **ephemeral** environment on Xano's cloud — create-or-refreshed each run, auto-expiring, with its own URL. |
|
|
441
|
+
| `npx @xano/sdk promote <release>` | Your **main Xano instance** workspace — the production target. Lands a release on a branch named for it (`--set-live` serves it). Its table changes reach live as it lands — see [what a landing does to tables](#what-a-landing-does-to-tables). |
|
|
442
|
+
| `npx @xano/sdk tenant deploy <tenant> <release>` | A **customer tenant** — the same release, landed on someone else's deployment. It **replaces** what the tenant serves: anything the release does not carry is removed. Static hosting is kept. |
|
|
443
|
+
| `npx @xano/sdk deploy --to <dest>` | The **escape hatch**: merges a local build straight into `workspace` or `tenant:<name>`, skipping the release record. |
|
|
444
|
+
| `npx @xano/sdk test` | Nothing — it only reads. Runs the tests an already-deployed backend carries; `--on` picks which one, `local` and `workspace` included. |
|
|
445
445
|
|
|
446
446
|
Not every instance has ephemeral environments enabled. Where they are off, `deploy --ephemeral`
|
|
447
|
-
says so and names who can turn them on. A bare `deploy` (the Xano Engine), `
|
|
448
|
-
`
|
|
447
|
+
says so and names who can turn them on. A bare `deploy` (the Xano Engine), `npx @xano/sdk export` and
|
|
448
|
+
`npx @xano/sdk preflight` still work meanwhile.
|
|
449
449
|
|
|
450
450
|
Every `deploy` is a **full replace** of the disposable environment — always fresh — unless
|
|
451
451
|
you pass `--keep-data`. Landing somewhere real is the opposite by design: it changes what
|
|
@@ -461,7 +461,7 @@ object in `details.outOfScope`, and the rerun with `--yes` printed).
|
|
|
461
461
|
|
|
462
462
|
### Keeping your data between deploys
|
|
463
463
|
|
|
464
|
-
`
|
|
464
|
+
`npx @xano/sdk deploy --keep-data` redeploys to your ephemeral or Xano Engine by **merging** into
|
|
465
465
|
what an earlier deploy put there, instead of replacing it. Code and schema changes land,
|
|
466
466
|
objects removed from the project are deleted, and the rows already in the tables stay. Seed
|
|
467
467
|
rows are not written again.
|
|
@@ -517,7 +517,7 @@ Before it writes, a merge prints what it will cost, without prompting:
|
|
|
517
517
|
- every index it adds or drops;
|
|
518
518
|
- every new table whose seed rows it does not write;
|
|
519
519
|
- every env var whose project value differs from the live one — a merge keeps the live
|
|
520
|
-
value (`
|
|
520
|
+
value (`npx @xano/sdk env set <NAME> <value>` changes it). Only names are printed, never values;
|
|
521
521
|
- every other object it deletes, named `<kind>:<name>` (`function:old_helper`,
|
|
522
522
|
`query:GET ping (apiGroup shop)`).
|
|
523
523
|
|
|
@@ -529,9 +529,8 @@ and `omittedInsertsFail` / `setInsertsFail` when inserts fail; see below),
|
|
|
529
529
|
`notNullKept`, `pairedColumns` (`{ table, dropped, added }`: a drop beside an add, not a rename),
|
|
530
530
|
`narrowedEnums` (`{ table, column, removed }`), `retargetedRefs` (`{ table, column, from, to }`),
|
|
531
531
|
`indexChanges` (`{ table, index, action, unique }`), `notNullTightened` (`{ table, column, type }`),
|
|
532
|
-
`storageChanges` (`{ table, from, to }`: the table's `useXdo` before and after),
|
|
533
532
|
`removed`, `unseededTables` (new tables whose seed rows the merge did not
|
|
534
|
-
write), `renamedTables` (each `{ from, to }`: renamed through `
|
|
533
|
+
write), `renamedTables` (each `{ from, to }`: renamed through `npx @xano/sdk lock rename`, rows kept),
|
|
535
534
|
`unchangedEnv` and `canonicalChanges` (each `{ kind, name, from, to }`: a public URL slug a
|
|
536
535
|
changed `canonical` moved — every endpoint under `from` stops answering). A realtime server's
|
|
537
536
|
moved slug, or a channel renamed in place, also leaves its `conversation` transcript and
|
|
@@ -540,7 +539,7 @@ the name back restores them. Columns are named
|
|
|
540
539
|
`table.column` everywhere.
|
|
541
540
|
|
|
542
541
|
The limits, in one place: rows survive only in tables and columns that keep their identity
|
|
543
|
-
(a table renamed through `
|
|
542
|
+
(a table renamed through `npx @xano/sdk lock rename` keeps its rows; an unrecorded rename is refused,
|
|
544
543
|
below); changed env values and a new table's seeds need `--reset`;
|
|
545
544
|
a Xano Engine's rows last as long as its process (an engine update restarts it empty, and the
|
|
546
545
|
next run seeds); and a test whose `datasource` is `"live"`
|
|
@@ -552,8 +551,8 @@ the environment keeps its data. Each refusal is exit 2 and names its remedy:
|
|
|
552
551
|
- **A rename the lock was not told about** (`SDK_IDENTITY_CONFLICT`, `details.refused:
|
|
553
552
|
"renamePending"`): the merge would drop a table `xano.lock` still pins, with its rows, while
|
|
554
553
|
the project adds a new one. Each is in `details.renames[]` as `{ table, guid, candidates,
|
|
555
|
-
rename, prune }` — `rename` is the `
|
|
556
|
-
then renames it and keeps its rows), `prune` the `
|
|
554
|
+
rename, prune }` — `rename` is the `npx @xano/sdk lock rename …` to run if it was renamed (the merge
|
|
555
|
+
then renames it and keeps its rows), `prune` the `npx @xano/sdk lock prune …` if it was deleted.
|
|
557
556
|
Run one, then deploy again. When the new table's def pins its own `guid:`, `setGuid: { table,
|
|
558
557
|
guid, pins }` replaces `rename`: set that def's `guid:` to `guid` — a def's guid replaces any
|
|
559
558
|
lock entry, so a `lock rename` would not keep the rows. The lock marks such an entry
|
|
@@ -574,7 +573,7 @@ the environment keeps its data. Each refusal is exit 2 and names its remedy:
|
|
|
574
573
|
a `canonical` written in code is served as declared or the merge is refused. The usual cause
|
|
575
574
|
is an api group (toolset, realtime server) renamed while keeping its `canonical`: a merge
|
|
576
575
|
creates the renamed object beside the old one, which still holds the slug. The entry carries
|
|
577
|
-
`heldBy` and `rename` — the `
|
|
576
|
+
`heldBy` and `rename` — the `npx @xano/sdk lock rename …` that makes the merge rename it in place,
|
|
578
577
|
keeping its URL. Otherwise pick another `canonical`, or `--reset`.
|
|
579
578
|
- **A unique index the rows already there break** (`SDK_IMPORT_REFUSED`, `details.refused:
|
|
580
579
|
"uniqueViolation"`, the indexes the merge adds in `details.indexes[]` as `{ table, index }`,
|
|
@@ -599,9 +598,12 @@ the environment keeps its data. Each refusal is exit 2 and names its remedy:
|
|
|
599
598
|
refused for every table, empty or seeded — the instance cannot convert a table back to JSON
|
|
600
599
|
storage, and nothing is sent. A `deploy --replace` rebuilds the tables, so it switches either way.
|
|
601
600
|
|
|
602
|
-
A keep-data refusal's `details` carries `refused` (the reason, a string)
|
|
601
|
+
A keep-data refusal's `details` carries `refused` (the reason, a string). For `identityConflict`,
|
|
602
|
+
`renamePending`, `pruneOutOfScope` and `uniqueViolation` it also carries `conflicts`, `renames`
|
|
603
603
|
and `outOfScope` (each a list, empty when it does not apply), `serverCode` when the environment
|
|
604
|
-
itself refused, and `warnings` when the run had some.
|
|
604
|
+
itself refused, and `warnings` when the run had some. The others carry `landed: false` and their
|
|
605
|
+
own list: `tableTrigger` names `triggers`, `storageModeChange` names `tables`, and
|
|
606
|
+
`importInProgress` carries `serverCode` and, when there is one, `rerun`. A `--keep-data` deploy never falls back to a replace.
|
|
605
607
|
|
|
606
608
|
Another import already running on the instance is not a refusal of the project: any deploy
|
|
607
609
|
(`--keep-data`, a replace, `--to`) exits 8 with `SDK_IMPORT_REFUSED`, `details.refused:
|
|
@@ -611,7 +613,7 @@ with `--to` (`--seed`, `--prune`, `--dry-run`, …) stay refused alongside it.
|
|
|
611
613
|
|
|
612
614
|
### Deploying locally
|
|
613
615
|
|
|
614
|
-
A bare `
|
|
616
|
+
A bare `npx @xano/sdk deploy` deploys to an engine running on this machine — no network round-trip
|
|
615
617
|
per deploy. `--local` is that default spelled out, needed only to name an engine:
|
|
616
618
|
`--local=<version|url|path>` runs that one instead of the pinned version. It needs nothing
|
|
617
619
|
configured:
|
|
@@ -628,7 +630,7 @@ configured:
|
|
|
628
630
|
`XANOSDK_NO_UPDATE_CHECK=1`). In an interactive terminal the deploy asks whether to update,
|
|
629
631
|
defaulting to no — a version you declined is only noted afterwards, not asked again. In CI,
|
|
630
632
|
piped output or `--json` it prints a one-line notice and keeps the pin. The pin never moves
|
|
631
|
-
without a yes or an explicit `
|
|
633
|
+
without a yes or an explicit `npx @xano/sdk local update`.
|
|
632
634
|
- **A running engine on a different version** than the one the project now resolves to — after
|
|
633
635
|
an update, or after a teammate moved the pin — is stopped and replaced, and the deploy says
|
|
634
636
|
so.
|
|
@@ -642,18 +644,18 @@ An engine update restarts the engine, and a restarted engine starts **empty**: t
|
|
|
642
644
|
rather than merging, so rows entered through your app do not survive the upgrade.
|
|
643
645
|
|
|
644
646
|
**Operating on it.** After a local deploy, the engine is the backend this project
|
|
645
|
-
tracks, so bare `
|
|
647
|
+
tracks, so bare `npx @xano/sdk test run-all`, `env set`, `env pull`, `tables`, `impersonate` and
|
|
646
648
|
`status` reach it — none of them needs a Xano account. Name it explicitly as `local`,
|
|
647
|
-
or `local:<name>` for another one from `
|
|
649
|
+
or `local:<name>` for another one from `npx @xano/sdk local list` (the full grammar is in
|
|
648
650
|
[the CLI guide](cli.md#naming-a-backend)). `publish` puts a built frontend on it without
|
|
649
651
|
re-importing the backend. One command cannot serve it and refuses it by name: `release create`
|
|
650
652
|
(the cut runs on the instance — pass `--from ephemeral`).
|
|
651
653
|
|
|
652
654
|
| Command | What it does |
|
|
653
655
|
|---|---|
|
|
654
|
-
| `
|
|
655
|
-
| `
|
|
656
|
-
| `
|
|
656
|
+
| `npx @xano/sdk local update` | Moves the pin to the latest engine (`--version <v>`: that one, downgrades included), downloads it, and restarts the project's running engine on it. Commit `package.json`. |
|
|
657
|
+
| `npx @xano/sdk local cache list` | Each cached engine version, its size on disk, and the engines running on it. |
|
|
658
|
+
| `npx @xano/sdk local cache clear` | Removes every cached engine (`--version <v>`: just that one). An engine running on a removed version is stopped first; the next deploy fetches it again. |
|
|
657
659
|
|
|
658
660
|
#### Connecting a coding agent
|
|
659
661
|
|
|
@@ -661,10 +663,11 @@ The Xano Engine serves an MCP server for coding agents, and a local deploy print
|
|
|
661
663
|
for looking at the deployed backend (objects, table schemas, rows, run history), seeding and
|
|
662
664
|
editing rows, and running functions, tasks, triggers, endpoints and tests by hand, each
|
|
663
665
|
answering its result and logs. It never changes a primitive: tables, endpoints, functions and
|
|
664
|
-
every other object change in `xano/` and ship with `
|
|
666
|
+
every other object change in `xano/` and ship with `npx @xano/sdk deploy`.
|
|
665
667
|
|
|
666
|
-
`
|
|
667
|
-
server, `xano-local`, that launches a bridge
|
|
668
|
+
`npx @xano/sdk init` connects Claude Code (`.mcp.json`) and Cursor (`.cursor/mcp.json`) to it with one
|
|
669
|
+
server, `xano-local`, that launches a bridge. This is the Claude Code `.mcp.json` entry; Cursor's
|
|
670
|
+
appends `--project ${workspaceFolder}`, since Cursor does not promise to launch it inside the project:
|
|
668
671
|
|
|
669
672
|
```json
|
|
670
673
|
{ "mcpServers": { "xano-local": { "command": "npx", "args": ["--yes", "--package", "@xano/sdk", "xanosdk", "local", "mcp", "--stdio"] } } }
|
|
@@ -676,29 +679,29 @@ before `npm install`). The config holds no url and no token. The engine may come
|
|
|
676
679
|
always mints a new bearer, so the bridge looks both up when it needs them, and again when the
|
|
677
680
|
engine stops answering or refuses the bearer. Before the first deploy the server connects and
|
|
678
681
|
lists no tools; once an engine is up it tells the agent its tools changed. A call cut off after
|
|
679
|
-
it reached the engine is reported as unknown, never sent twice. `
|
|
682
|
+
it reached the engine is reported as unknown, never sent twice. `npx @xano/sdk local mcp` prints the
|
|
680
683
|
details and each agent's config line, and `init` in an existing project adds the server beside
|
|
681
684
|
the ones a config already declares. An engine too old to serve MCP says so on deploy, and
|
|
682
|
-
`
|
|
685
|
+
`npx @xano/sdk local update` moves the project to one that does. Claude Code asks once before it
|
|
683
686
|
starts a project's server; a Cursor version that does not pick up the tool change needs the
|
|
684
687
|
`xano-local` server refreshed in its MCP settings after the first deploy.
|
|
685
688
|
|
|
686
689
|
#### A frontend on the Xano Engine, and server rendering
|
|
687
690
|
|
|
688
|
-
`
|
|
691
|
+
`npx @xano/sdk deploy <entry> --local --static <dir>` publishes a built frontend to the
|
|
689
692
|
engine's own static host after the import, as on an ephemeral, and reports it as `static.url`:
|
|
690
693
|
`http://<prefix>.localhost:<port>`. Chrome, Firefox and Safari 26 resolve `*.localhost` to this
|
|
691
694
|
machine by themselves (Safari on macOS 15 and earlier does not); a tool that does not resolve it
|
|
692
695
|
can call the engine's own URL with a `Host: <prefix>.localhost:<port>` header. The engine needs a release
|
|
693
696
|
that hosts static sites: an older one answers the upload with a 501, which the deploy reports
|
|
694
|
-
without failing the backend (exit `3`), and `
|
|
697
|
+
without failing the backend (exit `3`), and `npx @xano/sdk local update` moves the pin on.
|
|
695
698
|
|
|
696
699
|
The engine hosts built output only, and refuses a build of more than 20,000 files or 256 MB unpacked.
|
|
697
700
|
The deploy checks both before the import, so an oversize directory stops the run with nothing
|
|
698
701
|
written. A symbolic link in the directory is not uploaded.
|
|
699
702
|
|
|
700
703
|
A SvelteKit app can also render on the server there. Build it with the SDK's adapter (it needs
|
|
701
|
-
`esbuild` in the app: `npm i -D esbuild`). In a project `
|
|
704
|
+
`esbuild` in the app: `npm i -D esbuild`). In a project `npx @xano/sdk init` scaffolded, SvelteKit's
|
|
702
705
|
config is the object passed to `sveltekit()` in `vite.config.ts` (a `svelte.config.js` is ignored
|
|
703
706
|
there), and it already builds with this adapter: stop prerendering the routes that should render
|
|
704
707
|
per request (the scaffold prerenders every route from `frontend/src/routes/+layout.ts`):
|
|
@@ -760,14 +763,14 @@ its unpacked runtime files, its logs, and the records of running engines — bes
|
|
|
760
763
|
fails names it.
|
|
761
764
|
|
|
762
765
|
Expect it to reach roughly 600 MB after the first deploy, and to grow by a similar amount for
|
|
763
|
-
each engine version you run, since every version unpacks its own copy. `
|
|
764
|
-
list` shows its size, and `
|
|
766
|
+
each engine version you run, since every version unpacks its own copy. `npx @xano/sdk local cache
|
|
767
|
+
list` shows its size, and `npx @xano/sdk local cache clear` (with no `--version`) removes it with the
|
|
765
768
|
engines once none is running — it names any engine still up; stop it and clear again. The next
|
|
766
769
|
deploy recreates what it needs.
|
|
767
770
|
|
|
768
771
|
Versions before this layout unpacked the same runtime into your own per-user cache directory.
|
|
769
772
|
Nothing runs from that copy now; `cache list` shows it when it is there, and
|
|
770
|
-
`
|
|
773
|
+
`npx @xano/sdk local cache clear --legacy-runtime` removes it after asking (`--yes` without a
|
|
771
774
|
terminal).
|
|
772
775
|
|
|
773
776
|
#### Running a different engine without moving the pin
|
|
@@ -777,7 +780,7 @@ pin for your own runs instead of editing `package.json`:
|
|
|
777
780
|
|
|
778
781
|
- `--local=<value>` for one deploy;
|
|
779
782
|
- `XANOSDK_ENGINE_OVERRIDE=<value>` for every deploy in this shell, including
|
|
780
|
-
`npm run xano:deploy`, which
|
|
783
|
+
`npm run xano:deploy`, which names no engine.
|
|
781
784
|
|
|
782
785
|
Both take a **version** (`v0.1.8`, or `0.1.8`: that release from the release manager), an
|
|
783
786
|
**`https` URL** to an engine archive, or the **path** to an engine archive on this machine. A
|
|
@@ -803,21 +806,21 @@ unset XANOSDK_ENGINE_OVERRIDE # next deploy is back on the pinned version
|
|
|
803
806
|
`XANOSDK_ENGINE_RELEASES_URL` points version lookups at a different engine release service. Its
|
|
804
807
|
engines are downloaded fresh on every deploy and kept apart from the version cache, and the
|
|
805
808
|
deploy runs its latest without reading or writing the pin or checking for updates;
|
|
806
|
-
`
|
|
809
|
+
`npx @xano/sdk local update` refuses while it is set.
|
|
807
810
|
|
|
808
811
|
### The release flow
|
|
809
812
|
|
|
810
813
|
This is the path to a real destination. Each step leaves something the next one can name:
|
|
811
814
|
|
|
812
815
|
```bash
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
816
|
+
npx @xano/sdk deploy ./xano/index.ts --ephemeral --test # 1. stand it up on an ephemeral, run its tests
|
|
817
|
+
npx @xano/sdk release create v1 # 2. cut a release from what just ran (after a local deploy: --from ephemeral)
|
|
818
|
+
npx @xano/sdk promote v1 # 3. land it in your workspace, on a branch named for it
|
|
819
|
+
npx @xano/sdk tenant deploy acme v1 # …or on a customer tenant
|
|
817
820
|
```
|
|
818
821
|
|
|
819
822
|
Step 2 is what makes the rest re-runnable. A release is a stored record that this code came
|
|
820
|
-
up and answered, so `promote v1` a week later lands the same bytes — and `
|
|
823
|
+
up and answered, so `promote v1` a week later lands the same bytes — and `npx @xano/sdk release
|
|
821
824
|
list` says what you have. Cut a release per merge, per tag, or per deploy you want to keep;
|
|
822
825
|
an existing name is refused rather than replaced, because a tenant may be running it.
|
|
823
826
|
|
|
@@ -942,8 +945,8 @@ it on failure as well as success, once it knows what it was about to write. Ever
|
|
|
942
945
|
{ "name": "land", "completed": "unknown" },
|
|
943
946
|
{ "name": "verify", "completed": "skipped" }
|
|
944
947
|
],
|
|
945
|
-
"resolveWith": "
|
|
946
|
-
"resolveSteps": ["If \"v1-…\" is absent, nothing landed: re-run as `
|
|
948
|
+
"resolveWith": "npx @xano/sdk workspace branch list --json",
|
|
949
|
+
"resolveSteps": ["If \"v1-…\" is absent, nothing landed: re-run as `npx @xano/sdk promote v1 --branch v1-… --yes`.", "…"],
|
|
947
950
|
"startedAt": "2026-09-22T14:00:00.000Z",
|
|
948
951
|
"resolveNotBefore": "2026-09-22T14:10:00.000Z",
|
|
949
952
|
"error": { "code": "SDK_ERROR", "message": "…", "exitCode": 9 } // only when the run failed
|
|
@@ -1050,12 +1053,12 @@ extra flags is not a release "without tables" — it has all of them.
|
|
|
1050
1053
|
What it does not carry, unless you ask for it, is any table's **rows**:
|
|
1051
1054
|
|
|
1052
1055
|
```bash
|
|
1053
|
-
|
|
1054
|
-
|
|
1055
|
-
|
|
1056
|
-
|
|
1057
|
-
|
|
1058
|
-
|
|
1056
|
+
npx @xano/sdk tables # id, guid, and name — of what this project deployed to
|
|
1057
|
+
npx @xano/sdk tables ephemeral:e4f2-9ab1 # …or a named env (its name, not its display name)
|
|
1058
|
+
npx @xano/sdk tables tenant:acme # …or a tenant
|
|
1059
|
+
npx @xano/sdk tables workspace # …or your workspace
|
|
1060
|
+
npx @xano/sdk release create v1 --seed # every table's rows ride along
|
|
1061
|
+
npx @xano/sdk release create v1 --seed=<guid>,<guid> # only those two tables' rows
|
|
1059
1062
|
```
|
|
1060
1063
|
|
|
1061
1064
|
Rows are opt-in because a release is durable and can be landed on another environment; data
|
|
@@ -1077,7 +1080,7 @@ pointer without the file — on the backend it lands on, the row's file would be
|
|
|
1077
1080
|
icon would answer 404. So `release create` refuses (`SDK_RELEASE_FILES_NOT_CARRIED`, exit 2) a
|
|
1078
1081
|
cut whose source serves `hostedFile()` icons, or whose `--seed` selects a table with a file
|
|
1079
1082
|
column while the source holds files. Land a project like that by deploying it directly, which
|
|
1080
|
-
ships its files: `
|
|
1083
|
+
ships its files: `npx @xano/sdk deploy --to tenant:<name> --seed`.
|
|
1081
1084
|
|
|
1082
1085
|
List from **the source you are cutting from**, not from your workspace. A table this project
|
|
1083
1086
|
deployed carries the guid `xano.lock` pins for it wherever it landed, but one created anywhere
|
|
@@ -1109,7 +1112,7 @@ list of them could not be read back reliably.
|
|
|
1109
1112
|
>
|
|
1110
1113
|
> What changes one is a **rename** — the name is what the guid derives from. A 32-hex guid that
|
|
1111
1114
|
> no longer matches usually means the table was renamed or removed in code since it was noted;
|
|
1112
|
-
> `
|
|
1115
|
+
> `npx @xano/sdk lock rename` carries the identity across a rename you meant. A guid in the engine's own
|
|
1113
1116
|
> shape (about 27 base64url characters) belongs to a table this project did not deploy, and does
|
|
1114
1117
|
> not travel between backends.
|
|
1115
1118
|
|
|
@@ -1118,7 +1121,7 @@ source's real tables if one does not match, and names the listing verb for that
|
|
|
1118
1121
|
|
|
1119
1122
|
### The alternative: merging a local build
|
|
1120
1123
|
|
|
1121
|
-
`
|
|
1124
|
+
`npx @xano/sdk deploy <entry> --to workspace` (or `--to tenant:<name>`) skips the release record and
|
|
1122
1125
|
merges the build on your disk straight into the destination. Reach for it when you want the
|
|
1123
1126
|
pre-flight the release path does not have — a plan preview, a prune scope, loss warnings —
|
|
1124
1127
|
or when you are deleting objects, which a release does not do.
|
|
@@ -1148,6 +1151,7 @@ publishes beside the merge, but not under `--dry-run`; `--skip-liveness` needs `
|
|
|
1148
1151
|
| `--backup-branch[=<label>]` | Snapshot the live branch's logic first. Switching back restores logic only — see below. |
|
|
1149
1152
|
| `--allow-shared-schema-changes` | Proceed even though table and microservice changes reach every branch. |
|
|
1150
1153
|
| `--allow-branch-deletion` | Proceed even though `--replace` permanently deletes the workspace's other branches. |
|
|
1154
|
+
| `--overwrite` | Deploy over objects changed in Xano since the last deploy or pull, instead of refusing with `SDK_WORKSPACE_CHANGED`. See below. |
|
|
1151
1155
|
|
|
1152
1156
|
#### `--replace` clears by workspace, not by branch
|
|
1153
1157
|
|
|
@@ -1176,11 +1180,11 @@ replace deletes them like any other.
|
|
|
1176
1180
|
|
|
1177
1181
|
`--yes` does not cover this; it waives the confirmation, not the loss. To go
|
|
1178
1182
|
ahead, pass `--allow-branch-deletion`. To keep the work first, export each branch
|
|
1179
|
-
on its own — a bare `
|
|
1183
|
+
on its own — a bare `npx @xano/sdk workspace export` reads the **live** branch, which is
|
|
1180
1184
|
the one a replace restores anyway:
|
|
1181
1185
|
|
|
1182
1186
|
```sh
|
|
1183
|
-
|
|
1187
|
+
npx @xano/sdk workspace export --branch branch2
|
|
1184
1188
|
```
|
|
1185
1189
|
|
|
1186
1190
|
Or drop `--replace`: the default merge leaves other branches untouched. Tenants
|
|
@@ -1195,7 +1199,7 @@ read, which is not the same as nothing to lose.
|
|
|
1195
1199
|
### Where a release lives
|
|
1196
1200
|
|
|
1197
1201
|
A release is always a record **in your workspace**, whatever it was cut from —
|
|
1198
|
-
that is what `
|
|
1202
|
+
that is what `npx @xano/sdk release list`, `promote`, and `tenant deploy` all read.
|
|
1199
1203
|
|
|
1200
1204
|
Cutting from an environment is one call. The platform reads that environment's
|
|
1201
1205
|
live state and writes the record here — **nothing is written to the
|
|
@@ -1204,9 +1208,9 @@ sandbox you cut from is left exactly as it was.
|
|
|
1204
1208
|
|
|
1205
1209
|
Only a throwaway environment may be a source. `--from tenant:<name>` is accepted
|
|
1206
1210
|
for an ephemeral or a sandbox, and refused for a `standard` or `run` tenant: that
|
|
1207
|
-
is a live deployment. `
|
|
1211
|
+
is a live deployment. `npx @xano/sdk tenant get <name>` names the last release landed
|
|
1208
1212
|
there, which lands anywhere as it is — but a `deploy --to` merge since may have
|
|
1209
|
-
changed what the tenant runs. To start from what it runs now, `
|
|
1213
|
+
changed what the tenant runs. To start from what it runs now, `npx @xano/sdk pull` it,
|
|
1210
1214
|
deploy that to an ephemeral, and cut from there.
|
|
1211
1215
|
|
|
1212
1216
|
Cutting `--from workspace` packages a branch directly — whatever the workspace
|
|
@@ -1220,18 +1224,18 @@ contents are not what its name claims.
|
|
|
1220
1224
|
|
|
1221
1225
|
### Moving a release to another workspace or instance
|
|
1222
1226
|
|
|
1223
|
-
`
|
|
1227
|
+
`npx @xano/sdk release transfer <name> --to-profile <profile>` copies a stored release into the
|
|
1224
1228
|
workspace a stored credential profile is bound to — another workspace, or another
|
|
1225
1229
|
instance. It moves the archive and nothing else: no compile, no branch, nothing lands.
|
|
1226
1230
|
Run `promote` on the destination afterwards, exactly as you would at the source.
|
|
1227
1231
|
|
|
1228
1232
|
```bash
|
|
1229
|
-
|
|
1230
|
-
|
|
1231
|
-
|
|
1233
|
+
npx @xano/sdk release transfer v1 --to-profile prod --dry-run # is it already there?
|
|
1234
|
+
npx @xano/sdk release transfer v1 --to-profile prod --yes # copy it
|
|
1235
|
+
npx @xano/sdk promote v1 --profile prod # land it there
|
|
1232
1236
|
```
|
|
1233
1237
|
|
|
1234
|
-
`--to-profile` names a profile from `
|
|
1238
|
+
`--to-profile` names a profile from `npx @xano/sdk profile list`; the run's own credential is the
|
|
1235
1239
|
source. A profile bound to the same instance and workspace is refused.
|
|
1236
1240
|
|
|
1237
1241
|
A transfer decides "already there" by content, never by name or size: the sha256 of the
|
|
@@ -1253,15 +1257,15 @@ removes it.
|
|
|
1253
1257
|
|
|
1254
1258
|
### Pulling a backend into a project
|
|
1255
1259
|
|
|
1256
|
-
`
|
|
1257
|
-
and a git history — where `
|
|
1260
|
+
`npx @xano/sdk pull <source>` refreshes `xano/` in a project that already has a frontend, a lockfile,
|
|
1261
|
+
and a git history — where `npx @xano/sdk init --from <source>` writes a whole new project instead. It
|
|
1258
1262
|
takes the same source vocabulary everything else does: `release:<name>`, `ephemeral:<name>`,
|
|
1259
1263
|
`tenant:<name>`, `workspace`, or a bundle path.
|
|
1260
1264
|
|
|
1261
1265
|
```bash
|
|
1262
|
-
|
|
1263
|
-
|
|
1264
|
-
|
|
1266
|
+
npx @xano/sdk pull release:v1 # refresh xano/ from a release (keeps files you added)
|
|
1267
|
+
npx @xano/sdk pull workspace # …or from the live workspace
|
|
1268
|
+
npx @xano/sdk pull release:v1 --yes # skip the confirmation and the dirty-tree refusal (CI)
|
|
1265
1269
|
```
|
|
1266
1270
|
|
|
1267
1271
|
`pull` **replaces** and cannot merge: a file the previous decode wrote that this one does not
|
|
@@ -1283,7 +1287,7 @@ commands that record one are `deploy --to workspace`, a verified `promote`, `pul
|
|
|
1283
1287
|
and `init --from workspace`. Commit it with the rest of the lock.
|
|
1284
1288
|
|
|
1285
1289
|
```bash
|
|
1286
|
-
|
|
1290
|
+
npx @xano/sdk workspace diff ./xano/index.ts --json
|
|
1287
1291
|
```
|
|
1288
1292
|
|
|
1289
1293
|
```jsonc
|
|
@@ -1353,13 +1357,13 @@ serves the branch until you promote it.
|
|
|
1353
1357
|
`promote` lands a release on a branch and takes the same flag:
|
|
1354
1358
|
|
|
1355
1359
|
```bash
|
|
1356
|
-
|
|
1357
|
-
|
|
1358
|
-
|
|
1360
|
+
npx @xano/sdk promote v1 --branch staging # land the release there, live untouched
|
|
1361
|
+
npx @xano/sdk workspace branch list # see what exists, and what is live
|
|
1362
|
+
npx @xano/sdk workspace branch set-live staging # promote when you are happy
|
|
1359
1363
|
```
|
|
1360
1364
|
|
|
1361
1365
|
A promote **always** lands on a branch, named or not: without `--branch` the label is derived
|
|
1362
|
-
from the release and the moment (`v1-20260910T200511Z
|
|
1366
|
+
from the release and the moment (`v1-20260910T200511Z-3f2a`, four random hex digits last), and the run prints it. There is no
|
|
1363
1367
|
unnamed landing — a branch the engine leaves unlabelled cannot be selected, promoted or
|
|
1364
1368
|
deleted afterwards, so the CLI names it rather than letting that happen.
|
|
1365
1369
|
|
|
@@ -1367,17 +1371,17 @@ deleted afterwards, so the CLI names it rather than letting that happen.
|
|
|
1367
1371
|
stage first and cut over immediately, or on its own as the one-shot to production:
|
|
1368
1372
|
|
|
1369
1373
|
```bash
|
|
1370
|
-
|
|
1374
|
+
npx @xano/sdk promote v1 --set-live # land on a derived branch and serve it
|
|
1371
1375
|
```
|
|
1372
1376
|
|
|
1373
1377
|
The merge path takes it too, when you want the preview a release cannot run:
|
|
1374
1378
|
|
|
1375
1379
|
```bash
|
|
1376
|
-
|
|
1377
|
-
|
|
1380
|
+
npx @xano/sdk deploy ./xano/index.ts --to workspace --branch staging --dry-run # preview against the branch
|
|
1381
|
+
npx @xano/sdk deploy ./xano/index.ts --to workspace --branch staging # land it, live untouched
|
|
1378
1382
|
```
|
|
1379
1383
|
|
|
1380
|
-
There, `--backup-branch` snapshots live first, so the way back is `
|
|
1384
|
+
There, `--backup-branch` snapshots live first, so the way back is `npx @xano/sdk workspace branch
|
|
1381
1385
|
set-live <backup-label>`. That restores **logic only**: tables are shared by every branch, so a
|
|
1382
1386
|
column or table the deploy dropped stays dropped, with its data, after the switch back. The
|
|
1383
1387
|
data-safe path is before landing: read `droppedColumns` in the `--dry-run` plan, and keep the
|
|
@@ -1406,9 +1410,9 @@ are applied — even while the logic that reads them is staged on a branch. No o
|
|
|
1406
1410
|
a half-data, half-logic change atomic; one order is simply less bad than the other:
|
|
1407
1411
|
|
|
1408
1412
|
```bash
|
|
1409
|
-
|
|
1410
|
-
|
|
1411
|
-
|
|
1413
|
+
npx @xano/sdk workspace reset-tables ./index.ts --table <guid> # dry run, per-table counts
|
|
1414
|
+
npx @xano/sdk workspace reset-tables ./index.ts --table <guid> --write # then apply
|
|
1415
|
+
npx @xano/sdk promote v2 # then the logic
|
|
1412
1416
|
```
|
|
1413
1417
|
|
|
1414
1418
|
Rows first, then logic: new rows under old logic break only a feature you are removing, while
|
|
@@ -1445,10 +1449,13 @@ either way, and `dryRun` says which it was:
|
|
|
1445
1449
|
| `renamedTables`, `droppedColumns`, `retypedColumns`, `narrowedEnums`, `retargetedRefs`, `indexChanges`, `notNullKept`, `notNullTightened`, `storageChanges` | the table effects (see [What a landing does to tables](#what-a-landing-does-to-tables)); `tenant deploy` and `promote` carry the same keys, plus `droppedTables` (`{ table, rows }`), under `tableEffects`. |
|
|
1446
1450
|
| `unchangedEnv`, `droppedEnv`, `unappliedDocumentation`, `workspaceRename` | the rest of what the plan cannot say. |
|
|
1447
1451
|
| `workspaceSettingsNotApplied` | workspace settings a `--branch` landing held back (`[]` otherwise). |
|
|
1452
|
+
| `syncBaseline` | always present: the sync baseline recorded for the branch it landed on — `null` on a dry run, for a tenant or ephemeral, and when there is no `xano.lock`. |
|
|
1448
1453
|
|
|
1449
|
-
Present only when they apply: `branchDeletion`, `unnamedPublicUrls`, `staticRemoved`,
|
|
1450
|
-
|
|
1451
|
-
and `
|
|
1454
|
+
Present only when they apply: `branchDeletion`, `unnamedPublicUrls`, `staticRemoved`,
|
|
1455
|
+
`sharedSchemaChanges` (with `--branch`), on a dry run `seedRows` (under `--seed`: each table's
|
|
1456
|
+
seed rows and how many overwrite a live row) and `changedInXano` (objects changed in Xano that the
|
|
1457
|
+
real run would refuse to overwrite without `--overwrite`), and on a real run `setLive` (with
|
|
1458
|
+
`--branch`), `backupBranch`, `liveRestored` and `static`.
|
|
1452
1459
|
|
|
1453
1460
|
The comparison is deliberately one-sided: a false "changed" costs one import that was
|
|
1454
1461
|
happening anyway, while a false "unchanged" would silently skip a real release. So anything
|
|
@@ -1459,7 +1466,7 @@ no longer defines is work to do, so that is not a no-op either.
|
|
|
1459
1466
|
|
|
1460
1467
|
On the merge path, anything destructive is **previewed first** — the CLI fetches the plan,
|
|
1461
1468
|
prints what would change, and asks (an ephemeral never does). `--yes` skips the prompt for CI but never skips the
|
|
1462
|
-
preview. Start with `
|
|
1469
|
+
preview. Start with `npx @xano/sdk deploy ./xano/index.ts --to workspace --dry-run` to see the plan
|
|
1463
1470
|
without committing to it. (`promote` runs no preview — the platform lands the release — which
|
|
1464
1471
|
is the trade the release flow makes and says so before writing.)
|
|
1465
1472
|
|
|
@@ -1512,12 +1519,12 @@ by hand, or defined again, deployed, and then removed. A prune with no lock at a
|
|
|
1512
1519
|
either, so it is the same refusal — `SDK_PRUNE_OUT_OF_SCOPE`, exit `2`, the refusal document
|
|
1513
1520
|
under `--json` — saying there is no lock; reaching that usually means `--no-lock` suppressed
|
|
1514
1521
|
it, and the remedy is the same one landing without `--prune` (and without `--no-lock`), then
|
|
1515
|
-
committing the lock. A lock alone does not unlock a prune: `
|
|
1522
|
+
committing the lock. A lock alone does not unlock a prune: `npx @xano/sdk export` writes one with no
|
|
1516
1523
|
landing record. Deploying a pre-exported `--bundle` carries no entry file to find a lock beside,
|
|
1517
1524
|
so name it with `--lock=<path>` — without one that is a usage error (exit `1`). None of
|
|
1518
1525
|
that applies to an ephemeral: its record is `.xano/ephemeral.json` in the project the run is in —
|
|
1519
1526
|
the directory you deploy from when it is a project (it has `.xano/` or its own `xano/` entry),
|
|
1520
|
-
otherwise the entry's (`suites/alpha/.xano/` for `
|
|
1527
|
+
otherwise the entry's (`suites/alpha/.xano/` for `npx @xano/sdk deploy suites/alpha/xano/index.ts` typed
|
|
1521
1528
|
from a repository root holding no project) — written lock or not, so a prune there needs no lock,
|
|
1522
1529
|
and one refused there names that file and asks for a landing of that entry, with nothing to
|
|
1523
1530
|
commit. The credential in `.xano/auth.json` is read from the same project. Commands that default
|
|
@@ -1562,7 +1569,7 @@ object this project would create under a name the workspace already holds with a
|
|
|
1562
1569
|
identity is refused: the import would not update it, it would create a **second** object beside
|
|
1563
1570
|
it under a suffixed name and report success — with an auth table, that binds every endpoint to
|
|
1564
1571
|
one table while tokens are minted against the other. Three ways forward, all named in the
|
|
1565
|
-
message: adopt the objects that are already there with `
|
|
1572
|
+
message: adopt the objects that are already there with `npx @xano/sdk lock import` and commit the lock,
|
|
1566
1573
|
rename yours, or release into a workspace that does not hold them. A workspace that could not be
|
|
1567
1574
|
read refuses too — a failed read is not evidence that there is no collision.
|
|
1568
1575
|
|
|
@@ -1620,7 +1627,7 @@ and `XANO_META_TOKEN`, [above](#signing-in--deploying-in-depth) — no browser,
|
|
|
1620
1627
|
nothing that rotates:
|
|
1621
1628
|
|
|
1622
1629
|
```bash
|
|
1623
|
-
XANO_INSTANCE_URL=… XANO_WORKSPACE_ID=… XANO_META_TOKEN=… npx
|
|
1630
|
+
XANO_INSTANCE_URL=… XANO_WORKSPACE_ID=… XANO_META_TOKEN=… npx @xano/sdk deploy ./xano/index.ts --ephemeral
|
|
1624
1631
|
```
|
|
1625
1632
|
|
|
1626
1633
|
> ⚠️ A deploy without `--keep-data` is a full replace of the target environment, including
|