> ## 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.

# xanosdk deploy

> Deploy to the Xano Engine on this machine (default) or an ephemeral (--ephemeral) → URL.

## Usage

```bash theme={null}
xanosdk deploy [source] [options]
```

## Backends

| Slot | Accepts | When omitted |
| - | - | - |
| `<source>` | release:\<name>, workspace, ephemeral, ephemeral:\<name>, local, local:\<name>, tenant:\<name>, or a path to a bundle .json | This project's entry file, compiled |
| `--to` | workspace, or tenant:\<name> | Nothing: name one |

* `--to` refuses `local`: a deploy to a Xano Engine is `--local`, which also downloads, pins and starts one
* `--to` refuses `ephemeral`: `--ephemeral` already replaces an ephemeral. To merge into one instead, name it as the tenant it is: `--to tenant:<ephemeral name>`

## Flags

| Flag | Description |
| - | - |
| `--expires-hours <n>` | Ephemeral TTL at create time, 1–24 (default: 1) — not with --to |
| `--name <n>` | Display name for the ephemeral env (default for a new one: the release name for release:\<name>, else the workspace name, else this directory's) — not with --to |
| `--to <destination>` | Merge into a real destination instead of replacing the Xano Engine or an ephemeral. The escape hatch from the release flow: workspace, or tenant:\<name> |
| `--local[=<version\|url\|path>]` | Deploy to the Xano Engine on this machine — the default, so the flag is needed only to name an engine. Bare: runs the project's pinned engine version (the latest on first run, then pinned in package.json — commit it); a newer engine is offered, never applied without a yes. A version, URL or archive path (or XANOSDK\_ENGINE\_OVERRIDE, for every run in a shell) runs that engine as an override and never touches the pin; a URL must be https (plain http only from this machine). Not combinable with --to or --ephemeral |
| `--ephemeral` | Deploy to a disposable ephemeral on Xano's cloud instead of the Xano Engine on this machine |
| `--dry-run` | Print what would change and exit without sending it — only with --to |
| `--prune` | Also delete workspace objects your project no longer defines — only with --to |
| `--reset-data` | Empty every table the bundle carries before importing — only with --to |
| `--seed` | Write the bundle's table rows (off by default; `--replace` always writes them) — only with --to |
| `--replace` | Wipe the workspace — including ALL its branches — and import in its place — only with --to |
| `--allow-shared-schema-changes` | Proceed even though table/microservice changes reach every branch — only with --to |
| `--overwrite` | Deploy over objects changed in Xano since the last deploy or pull (see `workspace diff`) — only with --to |
| `--allow-branch-deletion` | Acknowledge that --replace permanently deletes the workspace's other branches — only with --to |
| `--branch <label>` | Release to this branch instead of the live one (stages logic; schema is shared) — only with --to |
| `--set-live` | Promote the branch to live once the import lands — only with --to |
| `--backup-branch[=<label>]` | Snapshot the live branch's logic first; set-live back restores logic, not tables (shared by every branch) — only with --to |
| `--yes, -y` | Confirm a destructive action non-interactively |
| `--bundle <path>` | Use an already-exported bundle instead of an entry file |
| `--static <dir>` | Archive this built frontend and deploy it to the static host |
| `--static-host <name>` | With --static: static-host name to deploy to (default: default) |
| `--static-routing spa\|multipage` | With --static: override URL resolution (inferred from the bundle; rarely needed) |
| `--static-env KEY=VALUE` | With --static: public config baked in as window.\<KEY> (repeatable; never secrets) |
| `--no-dev-env` | Do not point this project's .env.local at the deployed backend (only written when no static site is published) — not with --to |
| `--skip-liveness` | Do not wait to confirm the deploy came up (static host, microservices) |
| `--require-microservices` | Fail the deploy (exit 4) when a microservice is not ready by the end of the wait — not with --to |
| `--test` | After deploying, run the environment's tests; exit 5 if one fails, 6 if they cannot be reached; the deploy stands either way — not with --to |
| `--kind <unit\|workflow>` | With --test: only this test family (default: both) — not with --to |
| `--concurrency <n>` | With --test: run this many tests at once (default: 1) — not with --to |
| `--open` | Open the deployed URL in your browser when it lands — not with --to |
| `--keep-data` | Keep the environment's table rows: merge into what an earlier deploy filled instead of replacing it. Seed rows are not re-written, objects removed from the project are deleted, and a new or never-filled environment is replaced and seeded as usual. --reset overrides it; --to already merges |
| `--reset` | Replace the environment and re-seed it, overriding --keep-data (a deploy without --keep-data already does) — not with --to |
| `--lock[=<path>]` | Name the xano.lock to use — default: beside the entry file |
| `--no-lock` | Build with no lock: identities derive from names, public URLs are left to the instance |
| `--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, for a workspace adopted with `lock import` and ported a piece at a time |
| `--strict` | Promote every export warning (data-losing shapes, unresolvable filters) to a hard failure |
| `--env-var KEY=VALUE` | Set one BACKEND workspace env var for this run (repeatable). Beats xano/.env and --backend-env-file; the value never touches disk |
| `--backend-env-file <path>` | Read backend env values from this dotenv-style file INSTEAD of the default xano/.env (for CI, which does not have the ignored default) |
| `--allow-empty-env=NAME[,NAME]` | Send these declared names EMPTY when no value is supplied, clearing them in whatever imports the bundle. Only `deploy` refuses without it; per-name on purpose, and a bare --allow-empty-env is refused |
| `--allow-empty-doc-token=<scope>` | Send this scope's documentation token EMPTY when none is supplied, clearing that doc site's gate in whatever imports the bundle — `workspace`, or an API group's name. Repeat for more than one. Without it `deploy` refuses any gate left with no token, and every build refuses one on a group that publishes its docs (`swagger` on); a bare --allow-empty-doc-token is refused |
| `--secrets-file <path>` | Read documentation tokens from this file INSTEAD of the default xano/.secrets.json (for CI, which does not have the ignored default) |
| `--doc-token <scope>=<value>` | Supply one documentation token inline — `workspace=…`, or an API group's name. Repeat for more than one. Prefer --secrets-file: a value here is visible in shell history, the process list, and any CI log that echoes the command |
| `--origin <origin>` | Xano OAuth host for `login` and a XANO\_REFRESH\_TOKEN exchange (default: \$XANO\_ORIGIN) |
| `--config <path>` | Explicit credential file (default: \$XANO\_CONFIG) |
| `--local-auth` | Use the project-local ./.xano/auth.json instead of the shared cache |

Global flags are listed in the [CLI overview](/reference/cli).

***

*Generated from @xano/sdk 1.0.9.*


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