Cheat Sheet - Xano Documentation

A quick-scan map of the commands you reach for most. Everything is grouped by task, and each group links to the full reference when you need every flag. New to the CLI? Start with Get Started.

Looking for every command, subcommand, and flag? See the complete Command Reference.

Quickstart

Install the CLI

npm install -g @xano/cli

Requires Node ≥ 20.12.

Authenticate

xano auth

Opens your browser and saves a profile.

Get a sandbox

xano sandbox get

Auto-provisions a personal, free-tier dev environment.

Pull your code

xano sandbox pull -d ./code

Splits the multidoc into folders of .xs files.

Commands at a glance

Auth and profiles

Sandbox

Your personal dev environment.

Workspace

Git-friendly pull and push.

Branch

Labels, promotion, and live.

Function

Edit a single function fast.

Knowledge

Read agent knowledge and skills.

Release

Snapshots and deploys.

Tenant

Isolated multi-tenant deploys.

Testing

Unit and workflow tests in CI.

Hosting and platform

Frontends, platform, and updates.

Auth and profiles

Profiles store credentials and the active workspace + branch. Keep one per environment (prod / staging / dev) and switch with -p.

Command	What it does
`xano auth`	Browser OAuth login. Auto-creates a profile.
`xano profile wizard`	Interactive token-based setup (CI / headless friendly).
`xano profile create production -i https://x8.xano.io -t <token>`	Non-interactive, scriptable profile creation.
`xano profile list --details`	See every configured profile and which is default.
`xano profile set staging`	Change the default profile.
`xano profile me`	Show authenticated user, instance, and workspace.
`xano profile token \| pbcopy`	Pipe the token (use `$(xano profile token)` in scripts).
`xano profile workspace set`	Interactive picker for the active workspace.

Full reference: Profiles →

Sandbox

A singleton dev environment per user, auto-provisioned on first call — the fastest path from auth to shipping XanoScript.

Command	What it does
`xano sandbox get`	Returns your sandbox; creates it on first run.
`xano sandbox pull -d ./code`	Download the multidoc into snake_case folders of `.xs`.
`xano sandbox push --review`	Push changes and open the browser to verify or promote.
`xano sandbox push --dry-run`	Preview only — no changes applied.
`xano sandbox push --sync --delete`	Full sync; remove remote objects missing locally.
`xano sandbox review`	Open the sandbox in the browser to review and promote changes (`--url-only` just prints the URL).
`xano sandbox reset`	Wipe data and drafts; the sandbox itself stays.
`xano sandbox env set -n API_KEY --value sk-...`	Manage sandbox env vars (also `get`, `list`, `delete`, `get_all`, `set_all`).
`xano sandbox unit_test run_all`	Run sandbox-scoped tests (also `workflow_test`).

Full reference: Sandbox →

Workspace

Canonical pull/push for shared and production workspaces. Splits the multidoc into a folder tree your version control will love.

Command	What it does
`xano workspace list`	Show every workspace your account can reach.
`xano workspace pull -d ./xano-code`	Pull the entire workspace into snake_case folders.
`xano workspace pull -d ./bk --env --records --draft`	Include env vars, table records, and drafts.
`xano workspace push --dry-run`	Preview the diff before any write.
`xano workspace push --sync --delete --force`	Full mirror push (deletes remotes not present locally).
`xano workspace push -i "api/" -i "function/"`	Include globs, repeatable. Mirror with `-e` to exclude.
`xano workspace push --no-transaction --no-guids`	Disable transactional import / GUID write-back.
`xano workspace git pull -r https://github.com/owner/repo`	Pull XanoScript straight from a git repo (token via `-t`).

Full reference: Push & pull →

Branch

v1 always exists and can’t be renamed or deleted. The live branch serves production traffic — set_live swaps it instantly.

Command	What it does
`xano branch list`	All branches in the workspace.
`xano branch create dev`	Clone from `v1` (use `-s` to clone from elsewhere).
`xano branch create feature-auth -s dev -d "Auth feature"`	Branch from another branch with a description.
`xano branch edit dev --label development --color "#ff5733"`	Rename or recolor a branch.
`xano branch set_live staging`	Promote to production — affects traffic immediately.
`xano branch delete feature-old --force`	Delete a branch (never `v1` or the live branch).
`xano workspace pull -b dev`	Target a specific branch on pull/push with `-b`.

Full reference: Workspaces & branches →

Function

Skip the full pull when you only need to tweak one function. edit with no flags fetches and opens it directly in $EDITOR.

Command	What it does
`xano function list --include_draft`	List functions; sort with `--sort`, `--order`, `--per_page`.
`xano function get 145 -o xs > my_function.xs`	Dump raw XanoScript to a file.
`xano function edit 145`	Most ergonomic flow — opens current code in `$EDITOR`.
`xano function create -f ./scaffold.xs --edit`	Create from a file; `--edit` opens it first.
`cat fn.xs \| xano function create --stdin`	Pipe XanoScript in from another tool.
`xano function run calcScore -d email=jo@x.com -d age:=30`	Execute a function; `key:=json` sends raw JSON, `--logs` prints debugger output.

Full reference: Function commands →

Knowledge

Read the agent knowledge and skills that shape how AI agents build in a workspace. Both commands are read-only and print plain-text markdown by default.

Command	What it does
`xano knowledge list -w 40`	List enabled knowledge and skills; `--type skill\|doc\|agents.md` filters.
`xano knowledge list --no-enabled-only`	Include disabled knowledge too.
`xano knowledge get "deploy-runbook" -w 40`	Fetch one item; `--file checklist.md` grabs a reference file.

Full reference: Knowledge commands →

Release

Releases are named, versioned snapshots of a branch. Deploy them to tenants, export them to a file, or move them between workspaces.

Command	What it does
`xano release create v1.0.0 -b dev`	Cut a release from a branch (name is positional).
`xano release create hotfix-auth -b v1 --hotfix`	Bypass the normal flow for urgent prod fixes.
`xano release deploy v1.0 -w 40 --set_live --force`	Deploy to a workspace as a new branch and go live.
`xano release export v1.0.0 --output ./v1.tar.gz`	Export a portable file (note `--output`, not `-o`).
`xano release import -f ./v1.tar.gz -w 123`	Import into another workspace.
`xano release pull -r v1.0.0 -d ./release-v1`	Inspect a release’s contents locally.
`xano release push -d ./release -n v1.1 -b dev`	Push a directory as a brand-new release.

Full reference: Releases →

Tenant

Each tenant has its own database, env vars, license, and backups. Direct push is blocked — deploy through a release or iterate in a sandbox.

Command	What it does
`xano tenant list`	All tenants in the workspace.
`xano tenant create "My Tenant" --type tier2 --cluster_id 1`	Create a new tenant on a cluster.
`xano tenant deploy_release my-tenant -r v1.0.0`	Promote a release to a tenant.
`xano tenant deploy_platform my-tenant --platform_id 5`	Update the runtime platform version.
`xano tenant pull -t my-tenant -d ./out`	Read-only export of tenant code/data.
`xano tenant impersonate my-tenant`	Open the tenant dashboard in a browser.
`xano tenant env set_all my-tenant -f ./env.yaml --clean`	Bulk import env vars (`--clean` replaces).
`xano tenant backup create my-tenant -d "pre-deploy"`	Snapshot before risky changes.
`xano tenant backup restore my-tenant --backup_id 123 --force`	Disaster recovery — restore in place.
`xano tenant snapshot create my-tenant -l before-v2`	Instant clone of the tenant’s database (`list`, `swap`, `delete`).
`xano tenant snapshot swap my-tenant --snapshot my-tenant`	Repoint live DB to a snapshot; swap to the original name to roll back.
`xano tenant cluster list`	Manage clusters (`create`, `edit`, `license get/set`).

Full reference: Tenants →

Testing

Tests are authored in the dashboard; the CLI runs them. Use -o json for machine-readable results in pipelines.

Command	What it does
`xano unit_test list --branch dev --obj-type function`	Filter by branch or object type.
`xano unit_test run_all -o json`	CI gate — run every unit test, machine-readable output.
`xano unit_test run 123`	Run a single test by ID.
`xano workflow_test run_all --branch dev -o json`	Run end-to-end, multi-step request flows.
`xano workflow_test get 456 -o xs`	Inspect a workflow test as XanoScript.
`xano workflow_test delete 456 --force`	Remove a workflow test (rarely needed).

Full reference: Workflow tests →

Static hosting, platform, and maintenance

Ship the SPA next to the API, pin the runtime version, and keep the CLI itself current.

Command	What it does
`xano static_host list`	Every static host in the workspace (also `create`, `get`, `edit`).
`xano static_host build push my-app -d ./dist -n 'v1.0.0'`	Push a directory (or zip with `-f`) as a new build; name optional.
`xano static_host build pull my-app --latest -d ./out`	Download a build by `--build_id`, `--latest`, or `--env dev\|prod`.
`xano static_host deploy my-app --build_id 52 --env prod`	Promote a build to the dev or prod environment.
`xano static_host build list my-app`	Browse historical builds (also `get`, `delete`).
`xano static_host migrate --all --dry-run`	Preview migrating v1 hosts to instance-managed (v2) hosting.
`xano platform list`	Available platform versions (helm + image tags).
`xano platform get 23629 -o json`	Inspect details before `tenant deploy_platform`.
`xano update`	Pull the latest CLI release.

Full reference: Static hosting →

Power-user tips

Global flags

Available on any command:

-p <name> — swap profile
-c <path> — alternate credentials file
-v — verbose HTTP
-o <fmt> — output format (summary / json / xs)

Override with env vars

XANO_PROFILE=staging
XANO_CONFIG=/opt/.xano/creds.yaml
XANO_VERBOSE=1

Sandbox vs. workspace

Sandbox for personal experiments and AI-generated code. Workspace for shared/production code and CI. Same multidoc layout — workflows translate 1:1.

Always dry-run first

xano workspace push --dry-run

Add --sync --delete only when you want a true mirror. The default mode is partial (changed-only).

Binding is by guid, not path

Objects bind by the guid line inside each .xs file — not by folder or ID. There is no .xano/objects.json or manifest. A fresh pull regenerates each file with its correct guid, so pushing updates in place instead of duplicating.How objects are identified →

Glob filters

xano workspace push \
  -i "api/users/**" \
  -e "table/**"

-i includes and -e excludes — both repeatable, both glob.

Atomic by default

Pushes wrap in a DB transaction and write server-assigned GUIDs back to local files. Disable only when needed with --no-transaction or --no-guids.

Edit a function in $EDITOR

export EDITOR=cursor
xano function edit 145

No file, no flags — the CLI fetches the current code, opens it, and publishes on save.

Reuse the token

TOKEN=$(xano profile token)
curl -H "Authorization: Bearer $TOKEN" \
  https://x8.xano.io/api:meta/workspace

CI/CD recipe

xano profile create ci -i $URL -t $TOKEN
xano unit_test run_all -o json
xano release create v$SHA -b dev
xano tenant deploy_release prod -r v$SHA

Branches as environments

xano workspace pull -b dev   -d ./code
xano workspace push -b stage -d ./code

Branches are labels (strings), not IDs. v1 is reserved.

Include data on pull/push

Add data alongside code:

--records — include table rows
--env — include env vars
--draft — include drafts

Combine for full backups: pull --env --records --draft.

Tenant push is blocked

xano release create v1 -b dev
xano tenant deploy_release my-tenant -r v1

Or iterate in a sandbox first, then promote.

Go deeper

Command Reference

Every command, subcommand, and flag.

Get Started

Install, authenticate, and pull your first code.

Team workflows

Branching, releases, and promotion across a team.

Push & pull

How the multidoc maps to a local folder tree.

​Quickstart

​Commands at a glance

Auth and profiles

Sandbox

Workspace

Branch

Function

Knowledge

Release

Tenant

Testing

Hosting and platform

​Auth and profiles

​Sandbox

​Workspace

​Branch

​Function

​Knowledge

​Release

​Tenant

​Testing

​Static hosting, platform, and maintenance

​Power-user tips

Global flags

Override with env vars

Sandbox vs. workspace

Always dry-run first

Binding is by guid, not path

Glob filters

Atomic by default

Edit a function in $EDITOR

Reuse the token

CI/CD recipe

Branches as environments

Include data on pull/push

Tenant push is blocked

​Go deeper

Command Reference

Get Started

Team workflows

Push & pull

Quickstart

Commands at a glance

Auth and profiles

Sandbox

Workspace

Branch

Function

Knowledge

Release

Tenant

Testing

Static hosting, platform, and maintenance

Power-user tips

Go deeper