> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.docs.xano.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI overview

> What every xanosdk command shares: how to run the CLI, the global flags, the credential and build flag sets, the backend selector grammar, the tracked backend, and JSON output.

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>` |

```bash theme={null}
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](#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](/reference/environment-variables) and [CI/CD](/govern/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`](/reference/cli/deploy) | `[source]` | an entry file, `release:<name>`, a bundle path, or a running backend | `xano/index.ts` |
| [`deploy`](/reference/cli/deploy) | `--to` | `workspace`, `tenant:<name>` (`--ephemeral` and `--local` pick the other two) | The Xano Engine |
| [`publish`](/reference/cli/publish), [`env set`](/reference/cli/env-set), [`env unset`](/reference/cli/env-unset) | `--to` | `workspace`, `ephemeral[:<name>]`, `local[:<name>]`, `tenant:<name>` | The tracked backend |
| [`env pull`](/reference/cli/env-pull) | `--from` | `workspace`, `ephemeral[:<name>]`, `local[:<name>]`, `tenant:<name>` | The tracked backend |
| [`release create`](/reference/cli/release-create) | `--from` | `workspace`, `ephemeral[:<name>]`, `tenant:<name>` (a throwaway tenant only). Not `local`: the cut runs on your instance. | The tracked backend |
| [`init`](/reference/cli/init) | `--from` | any running backend, `release:<name>`, or a bundle path | An empty project |
| [`test list`](/reference/cli/test-list), [`test run`](/reference/cli/test-run), [`test run-all`](/reference/cli/test-run-all) | `--on` | `workspace`, `ephemeral[:<name>]`, `local[:<name>]`, `tenant:<name>` | The tracked backend |
| [`pull`](/reference/cli/pull) | `[source]` | any running backend, or `release:<name>` | The tracked backend |
| [`generate`](/reference/cli/generate) | `<source>` | any running backend, `release:<name>`, or a bundle path | Required |
| [`tables`](/reference/cli/tables) | `[backend]` | `workspace`, `ephemeral[:<name>]`, `local[:<name>]`, `tenant:<name>` | The tracked backend |
| [`impersonate`](/reference/cli/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.

```bash theme={null}
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.

```bash theme={null}
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](/help/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`](/reference/cli/compile), [`export`](/reference/cli/export), [`routes`](/reference/cli/routes), [`paths`](/reference/cli/paths), [`init`](/reference/cli/init), [`pull`](/reference/cli/pull), [`generate`](/reference/cli/generate), `marketplace` ([`list`](/reference/cli/marketplace-list), [`search`](/reference/cli/marketplace-search), [`details`](/reference/cli/marketplace-details), [`install`](/reference/cli/marketplace-install), [`reinstall`](/reference/cli/marketplace-reinstall), [`remove`](/reference/cli/marketplace-remove)) |
| Deploy | [`deploy`](/reference/cli/deploy), `env` ([`pull`](/reference/cli/env-pull), [`set`](/reference/cli/env-set), [`unset`](/reference/cli/env-unset)), [`secrets fill`](/reference/cli/secrets-fill), `release` ([`create`](/reference/cli/release-create), [`list`](/reference/cli/release-list), [`show`](/reference/cli/release-show), [`export`](/reference/cli/release-export), [`delete`](/reference/cli/release-delete), [`transfer`](/reference/cli/release-transfer)), [`promote`](/reference/cli/promote), [`publish`](/reference/cli/publish), [`preflight`](/reference/cli/preflight) |
| Environments | `tenant` ([`list`](/reference/cli/tenant-list), [`get`](/reference/cli/tenant-get), [`deploy`](/reference/cli/tenant-deploy), [`delete`](/reference/cli/tenant-delete)), `workspace` ([`details`](/reference/cli/workspace-details), [`export`](/reference/cli/workspace-export), [`diff`](/reference/cli/workspace-diff), [`reset-tables`](/reference/cli/workspace-reset-tables), [`branch`](/reference/cli/workspace-branch)), `ephemeral` ([`list`](/reference/cli/ephemeral-list), [`get`](/reference/cli/ephemeral-get), [`export`](/reference/cli/ephemeral-export), [`delete`](/reference/cli/ephemeral-delete)), `local` ([`list`](/reference/cli/local-list), [`token`](/reference/cli/local-token), [`mcp`](/reference/cli/local-mcp), [`stop`](/reference/cli/local-stop), [`update`](/reference/cli/local-update), [`cache`](/reference/cli/local-cache)), `test` ([`list`](/reference/cli/test-list), [`run`](/reference/cli/test-run), [`run-all`](/reference/cli/test-run-all)), [`tables`](/reference/cli/tables), [`impersonate`](/reference/cli/impersonate) |
| Account | [`login`](/reference/cli/login), [`logout`](/reference/cli/logout), [`status`](/reference/cli/status), [`whoami`](/reference/cli/whoami), `profile` ([`list`](/reference/cli/profile-list), [`show`](/reference/cli/profile-show), [`add`](/reference/cli/profile-add), [`use`](/reference/cli/profile-use), [`set-default`](/reference/cli/profile-set-default), [`delete`](/reference/cli/profile-delete)) |
| Maintenance | `lock` ([`rename`](/reference/cli/lock-rename), [`prune`](/reference/cli/lock-prune), [`import`](/reference/cli/lock-import)), [`completion`](/reference/cli/completion), [`version`](/reference/cli/version), [`upgrade`](/reference/cli/upgrade), `agent-skill` ([`install`](/reference/cli/agent-skill-install), [`status`](/reference/cli/agent-skill-status), [`uninstall`](/reference/cli/agent-skill-uninstall)), [`help`](/reference/cli/help) |

## Next

* The files these commands read and write: [Config files](/reference/config-files).
* When a command fails: [Troubleshooting](/help/troubleshooting).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.