Glossary

Most confusion with XanoTS comes from four or five words that sound interchangeable and are not. This page is the short answer for each; every entry links to the page that explains it properly.

The four places things live

These nest, largest first. Getting them straight makes most other docs read easily.

Term	What it is
Instance	Your Xano server — the thing with a URL like `your-instance.xano.io`. Holds one or more workspaces. `xanots whoami` prints its origin.
Workspace	One backend: its tables, endpoints, functions, and settings. A XanoTS credential addresses exactly one workspace — there is no `--workspace` flag. `xanots workspace details` says which.
Branch	A copy of a workspace’s logic (endpoints, functions, tasks…). Tables are shared across all branches — see what a branch isolates. One branch is live at a time. Releasing to a branch from the CLI is still in development.
Ephemeral	A disposable, auto-expiring environment with its own URL, created by `xanots deploy`. Where you try things. Not production, and nothing here can reach it.

“Branch” means two different things depending on context, and they are unrelated: a git branch (a parallel copy of your code) and a Xano branch (a copy of your workspace’s logic, living on the instance). The docs say “Xano branch” whenever it is the second.

The commands that write

Term	What it does
`deploy`	Compile and push to an ephemeral. A full replace, every time. Disposable, so iterate freely.
`release`	Promote to your real workspace. Merges — adds and updates, never deletes unless you ask, and never touches table rows.
`preflight`	Prove your code against a real engine in a throwaway environment, then delete it. Non-destructive; touches nothing you own.
`export`	Compile to a bundle on disk or stdout. No network, no auth.
`init --from workspace`	The pull direction: turn a live workspace into TypeScript.

deploy vs release is the distinction to internalise. deploy replaces something disposable; release merges into something you care about. They deliberately have no flag in common that would let you confuse the two targets.

Identity

Term	What it is
def object	The unit you author — `defineTable`, `defineQuery`, `defineFunction`. A plain typed object describing what should exist.
bundle	The single JSON document your whole workspace compiles to, and the only thing that is ever imported. Carries environment variable values — never commit one.
guid	An object’s stable identity. A release matches incoming objects to existing ones by guid, which is what makes re-running update instead of duplicate. Derived from the object’s name by default.
`xano.lock`	The file pinning every object’s guid, plus the `canonical` URL tokens of API groups and toolsets. Commit it. See why.
canonical	The URL token in an API group’s public address. Pinned by the lock, because the engine otherwise randomizes it per environment — so an unpinned one changes your public URLs.

Credentials

Term	What it is
`xanots login`	Interactive OAuth in your browser. For people. Never in CI — it blocks on consent.
meta credential	`XANO_INSTANCE_URL` + `XANO_WORKSPACE_ID` + `XANO_META_TOKEN`. For machines. Never expires or rotates; all three required together.
`auth.json`	Where a credential caches — shared (`~/.xanots/`) or project-local (`./.xano/`, gitignored by `login --local`).

Formats and other words

Term	What it is
multidoc	Xano’s own `.xs` (XanoScript) export format. What you read if you prefer XanoScript to TypeScript.
XanoScript	Xano’s native scripting language. XanoTS compiles to the same workspace, so the two describe the same objects.
static host	Frontend hosting attached to an environment. `deploy --static ./frontend/dist` puts your built frontend on the same ephemeral as its backend.
`window.XANO_HOST`	The backend URL, injected into every HTML document at deploy time — so a prebuilt frontend retargets any environment with no rebuild.
middleware	Logic that runs before or after an endpoint.
`--prune`	Deletes objects this project released and no longer defines. Requires `xano.lock`, and is the only ordinary way a release removes something.
`--dry-run`	Prints the plan and sends nothing. The habit worth forming.

Easily confused

Instance vs workspace vs environment

The instance is the server. A workspace is one backend on it. An environment is a place a workspace runs — your real one, or a disposable ephemeral. xanots whoami prints the instance origin; xanots status prints the environment this project last deployed to.

Git branch vs Xano branch

A git branch holds your code and is merged with git merge. A Xano branch holds your workspace’s logic and is promoted with xanots workspace branch set-live. In repo-is-the-truth you mostly use the first; in workspace-is-the-truth the second is the merge.

conversation vs history (realtime)

conversation is the client-visible transcript — what a user sees when they join a channel. history is execution/debugger retention, for you. Orthogonal: a channel can have either, both, or neither.

deploy --replace vs release --replace

Every deploy is already a full replace of a disposable environment, so there is no flag. release --replace wipes your real workspace and rebuilds it, minting fresh identities — which is why it re-pins your lock afterwards and tells you to commit it.

A bundle vs an export vs a backup

A bundle is the compiled JSON your code produces. xanots workspace export writes the live workspace as one. Neither is a backup — backups are a Xano workspace feature, and they are what restores lost table data. A release never restores rows.

Get Started

Authoring

Shipping

Workflow & collaboration

Help

Connectors

Migrating an existing workspace

The four places things live

The commands that write

Identity

Credentials

Formats and other words

Easily confused

​The four places things live

​The commands that write

​Identity

​Credentials

​Formats and other words

​Easily confused

The four places things live

The commands that write

Identity

Credentials

Formats and other words

Easily confused