CLI overview

Every command and flag has its own generated page in this group. This page covers what they share.

Running the CLI

Where you are	Run
Outside a project	`npx @xano/sdk <command>`
In a project with `@xano/sdk` installed	`npx xanosdk <command>`, or a scaffolded `npm run xano:*` script
After `npm i -g @xano/sdk`	`xanosdk <command>`

npx @xano/sdk init my-app                 # outside a project
npx xanosdk deploy ./xano/index.ts        # inside one: deploy to the Xano Engine
npx xanosdk deploy --help                 # one command's arguments and flags

A command the CLI prints for you to run next (a fix, a rerun) is spelled the same way for where you ran it.

Global flags

Every command takes these.

Flag	What it does
`--json`	JSON on stdout. This is the default whenever stdout is not a terminal; see Output.
`--profile`, `-p <name>`	For commands that sign in: act as this stored credential profile. It is the only thing that overrides the project’s `xano.profile.json`, then `$XANO_PROFILE`, then the credential file’s default.
`--no-refresh`	Do not refresh the managed block in `AGENTS.md`.
`--help`, `-h`	Show the command’s help and exit.
`--version`, `-v`	Print the CLI version and exit.

Credential flags

Every command that signs in (deploy, release, promote, tenant, workspace, ephemeral, env, pull, tables, login and the rest) takes the same set beside --profile:

Flag	What it does
`--config <path>`	Use this credential file (default: `$XANO_CONFIG`).
`--local-auth`	Use the project-local `.xano/auth.json` instead of the shared `~/.xanosdk/auth.json`.
`--origin <origin>`	The Xano OAuth host for `login` and a `XANO_REFRESH_TOKEN` exchange (default: `$XANO_ORIGIN`).

In CI, set XANO_INSTANCE_URL, XANO_WORKSPACE_ID and XANO_META_TOKEN together instead. That credential outranks every file and profile. See Environment & identity and CI/CD. A write to your workspace or a tenant asks for confirmation first. Off a terminal it needs --yes (-y), or it exits 1 with the command to rerun. A write to an ephemeral or a Xano Engine never asks.

Build flags

deploy, export, preflight, workspace diff and workspace reset-tables compile your project, and each takes this whole set:

Flag	What it does
`--strict`	Turn every export warning into a failure.
`--lock[=<path>]`	Use this `xano.lock` (default: beside the entry file).
`--no-lock`	Build with no lock. Refused once a lock exists.
`--frozen-lock`	CI guard: fail instead of changing the lock, or on a lock entry nothing matches.
`--allow-lock-orphans`	With `--frozen-lock`: accept lock entries no exported object matches.
`--env-var KEY=VALUE`	Set one backend env value for this run (repeatable). Beats `xano/.env`.
`--backend-env-file <path>`	Read backend env values from this file instead of `xano/.env`.
`--allow-empty-env=NAME[,NAME]`	Send these declared names empty when no value is supplied.
`--secrets-file <path>`	Read documentation tokens from this file instead of `xano/.secrets.json`.
`--doc-token <scope>=<value>`	Supply one documentation token inline (repeatable).
`--allow-empty-doc-token=<scope>`	Send this scope’s documentation token empty when none is supplied.

release create takes --strict and the env and documentation-token flags, but none of the lock flags. compile and routes take --strict and --lock. Each command’s page lists exactly what it takes.

Naming a backend

Every command that reads, writes or opens a running backend names it with one grammar, the backend selector:

Spelling	What it is
`workspace`	Your workspace, the one your credential is bound to.
`ephemeral`	The ephemeral this project deployed to.
`ephemeral:<name>`	A named ephemeral, by its name from `xanosdk ephemeral list` (`e4f2-9ab1`), not its display name.
`local`	The Xano Engine this project deployed to. Needs no Xano account.
`local:<name>`	A named Engine from `xanosdk local list`.
`tenant:<name>`	A tenant on your instance.
`release:<name>`	A stored release, where a command reads one.
a bundle path	A compiled bundle `.json` file, where a command takes a file.

The flag follows what the command does with the backend: reads take --from, writes take --to, test takes --on, and a command whose subject is the backend takes it as an argument.

Command	Slot	Accepts	When omitted
`deploy`	`[source]`	an entry file, `release:<name>`, a bundle path, or a running backend	`xano/index.ts`
`deploy`	`--to`	`workspace`, `tenant:<name>` (`--ephemeral` and `--local` pick the other two)	The Xano Engine
`publish`, `env set`, `env unset`	`--to`	`workspace`, `ephemeral[:<name>]`, `local[:<name>]`, `tenant:<name>`	The tracked backend
`env pull`	`--from`	`workspace`, `ephemeral[:<name>]`, `local[:<name>]`, `tenant:<name>`	The tracked backend
`release create`	`--from`	`workspace`, `ephemeral[:<name>]`, `tenant:<name>` (a throwaway tenant only). Not `local`: the cut runs on your instance.	The tracked backend
`init`	`--from`	any running backend, `release:<name>`, or a bundle path	An empty project
`test list`, `test run`, `test run-all`	`--on`	`workspace`, `ephemeral[:<name>]`, `local[:<name>]`, `tenant:<name>`	The tracked backend
`pull`	`[source]`	any running backend, or `release:<name>`	The tracked backend
`generate`	`<source>`	any running backend, `release:<name>`, or a bundle path	Required
`tables`	`[backend]`	`workspace`, `ephemeral[:<name>]`, `local[:<name>]`, `tenant:<name>`	The tracked backend
`impersonate`	`[backend]`	`ephemeral[:<name>]`, `local[:<name>]`, `tenant:<name>`	The tracked backend

A command that cannot serve a backend refuses it with the reason and the spellings it does take, whether you typed it or it came from the tracked backend.

npx xanosdk test run-all --on ephemeral          # run the tests on this project's ephemeral
npx xanosdk env pull --from tenant:stage         # read a tenant's env values into xano/.env
npx xanosdk release create v1.4.0 --from workspace --branch staging   # cut from a Xano branch

The tracked backend

Leave the backend off and a command follows the one this project last deployed to, recorded in .xano/deployed.json. Only a deploy to an ephemeral or a Xano Engine records it. A deploy to your workspace or a tenant never does, so a bare command cannot reach something real unasked. With no record, a command falls back to the ephemeral recorded under your current credential, then to the Engine recorded for this directory, and otherwise refuses, naming the flag to pass. deploy is the exception: bare, it deploys to the Xano Engine (or an ephemeral with --ephemeral, or the workspace or a tenant with --to) and writes the record rather than reading it. generate and init --from always need a backend named. npx xanosdk status shows the tracked backend.

Output

When stdout is a terminal, commands print text. When it is not (a pipe, a file, a CI step), stdout carries one JSON document, a failure’s included, and progress goes to stderr. --json forces JSON on a terminal too.

npx xanosdk release list --json | jq '.releases[].name'

Text stays text for --help, xanosdk version, and a command whose stdout is its data (export to stdout, --path -). Exit codes and outcomes covers every exit code, the failure document { ok: false, error: { code, message, exitCode, details } }, and the completed outcome of a release write.

Commands by group

Group	Commands
Author	`compile`, `export`, `routes`, `paths`, `init`, `pull`, `generate`, `marketplace` (`list`, `search`, `details`, `install`, `reinstall`, `remove`)
Deploy	`deploy`, `env` (`pull`, `set`, `unset`), `secrets fill`, `release` (`create`, `list`, `show`, `export`, `delete`, `transfer`), `promote`, `publish`, `preflight`
Environments	`tenant` (`list`, `get`, `deploy`, `delete`), `workspace` (`details`, `export`, `diff`, `reset-tables`, `branch`), `ephemeral` (`list`, `get`, `export`, `delete`), `local` (`list`, `token`, `mcp`, `stop`, `update`, `cache`), `test` (`list`, `run`, `run-all`), `tables`, `impersonate`
Account	`login`, `logout`, `status`, `whoami`, `profile` (`list`, `show`, `add`, `use`, `set-default`, `delete`)
Maintenance	`lock` (`rename`, `prune`, `import`), `completion`, `version`, `upgrade`, `agent-skill` (`install`, `status`, `uninstall`), `help`

The files these commands read and write: Config files.
When a command fails: Troubleshooting.

Overview

Authoring and config

CLI

Errors and formats

Running the CLI

Global flags

Credential flags

Build flags

Naming a backend

The tracked backend

Output

Commands by group

Next

​Running the CLI

​Global flags

​Credential flags

​Build flags

​Naming a backend

​The tracked backend

​Output

​Commands by group

​Next

Running the CLI

Global flags

Credential flags

Build flags

Naming a backend

The tracked backend

Output

Commands by group

Next