# Xano SDK

- [Xano SDK](https://sdk.docs.xano.com/index.md): The official TypeScript SDK for Xano: write the database, APIs and AI agents in TypeScript, run them on the Xano Engine on your machine with no account, then deploy them to Xano.
- [Quickstart](https://sdk.docs.xano.com/start/quickstart.md): Scaffold a TypeScript backend and a React frontend with npx @xano/sdk init, run the backend on the Xano Engine on your machine, and open the app, with no Xano account.
- [What you built](https://sdk.docs.xano.com/start/what-you-built.md): A tour of the project that npx @xano/sdk init writes: the backend in xano/, the frontend in frontend/, the files to commit, and which npm script deploys to which target.
- [How it works](https://sdk.docs.xano.com/start/how-it-works.md): How the Xano SDK turns TypeScript def objects into a bundle that Xano imports, what runs at build time and at request time, and how the SDK fits with XanoScript, the Xano CLI and the Xano editor.
- [Connect to Xano](https://sdk.docs.xano.com/start/connect-to-xano.md): Take the project from the quickstart to its first cloud deploy: create a free Xano account, sign in with npx xanosdk login, confirm the workspace, and deploy to an ephemeral with tests.
- [Add a backend to an existing app](https://sdk.docs.xano.com/start/existing-app.md): Run npx @xano/sdk init inside an app you already have to add a Xano backend in xano/, merge the xano scripts into package.json, and point your frontend at the backend URL.
- [Start from an existing workspace](https://sdk.docs.xano.com/start/existing-workspace.md): Read a Xano workspace you already have back as Xano SDK TypeScript with init --from workspace, check the round-trip report, adopt live identities with lock import, and decide where the source of truth lives.
- [Build](https://sdk.docs.xano.com/build/overview.md): How you and your coding agent write a Xano backend in TypeScript with the Xano SDK: tables, APIs, AI agents, background work, tests, environment variables and a typed frontend.
- [Your first change](https://sdk.docs.xano.com/build/first-change.md): Add a table and two endpoints to the starter backend, deploy them to the Xano Engine, and call them with curl.
- [Data and tables](https://sdk.docs.xano.com/build/data-and-tables.md): Define tables with typed columns, foreign keys, indexes and seed rows, then read and write them from an endpoint's stack.
- [APIs and middleware](https://sdk.docs.xano.com/build/apis-and-middleware.md): Publish endpoints under an API group, take path params and validated input, require a signed-in user, and attach middleware such as a rate limit.
- [AI agents and MCP servers](https://sdk.docs.xano.com/build/ai-agents-and-mcp-servers.md): Define tools, agents, MCP servers with prompts, resources and sign-in, and knowledge items that run inside your Xano backend, and call an agent from an endpoint.
- [Tasks, triggers and realtime](https://sdk.docs.xano.com/build/tasks-triggers-realtime.md): Run a stack on a schedule with task, react to table and workspace events with triggers, and serve websocket channels with the realtime kinds.
- [Tests](https://sdk.docs.xano.com/build/tests.md): Write unit tests on an endpoint, function or middleware and workflow tests that span objects, then run them against a deployed backend or as part of a deploy.
- [Environment variables and secrets](https://sdk.docs.xano.com/build/env-and-secrets.md): Declare workspace environment variable names in code, keep their values in xano/.env, change a value on a running backend with env set, and gate hosted API docs with a token.
- [Typed frontend](https://sdk.docs.xano.com/build/typed-frontend.md): Call your endpoints from a frontend with paths, request types and response types generated from the backend, so a renamed endpoint or column is a compile error.
- [Add-ons](https://sdk.docs.xano.com/build/add-ons.md): Find, install, register and remove marketplace add-ons such as @xano-sdk/auth and @xano-sdk/zod with the xanosdk marketplace commands.
- [Run locally](https://sdk.docs.xano.com/run/overview.md): Run your Xano backend on the Xano Engine on your machine with no account, and put the same backend in Xano's cloud as an ephemeral when you need a URL to share or a release to cut.
- [The Xano Engine](https://sdk.docs.xano.com/run/xano-engine.md): Run your backend on the Xano Engine on your machine: the first deploy, the version pin in package.json, keeping rows between deploys, the local commands, overrides, disk use, and where the Engine differs today.
- [Engine MCP server](https://sdk.docs.xano.com/run/engine-mcp.md): Connect Claude Code, Cursor or Codex to the MCP server the Xano Engine serves, so your coding agent can read tables and rows, seed data, and run functions, endpoints and tests on your local backend.
- [Ephemerals](https://sdk.docs.xano.com/run/ephemerals.md): Deploy your backend to an ephemeral, a disposable Xano environment in Xano's cloud with its own URL, and list, inspect, export and delete ephemerals before they expire.
- [Frontend hosting](https://sdk.docs.xano.com/run/frontend-hosting.md): Serve a built frontend beside your backend on the Xano Engine or an ephemeral with --static, republish it alone with xanosdk publish, and render a SvelteKit app on the server on the Engine.
- [Deploy to Xano](https://sdk.docs.xano.com/ship/overview.md): How a backend you built and ran on the Xano Engine reaches production on Xano: test it on an ephemeral, cut a release, then promote it to your workspace or deploy it to a tenant.
- [Where code goes](https://sdk.docs.xano.com/ship/where-code-goes.md): Every command that writes your backend somewhere, the target it writes to, and what the write does there: replace, merge, or add a new Xano branch, with tables shared by every Xano branch and env values added but never overwritten.
- [Shipping workflow](https://sdk.docs.xano.com/ship/shipping-workflow.md): Every change gets a live preview. Every release is tested once and shipped unchanged to dev, stage, and prod. Rolling back is one command.
- [Source of truth](https://sdk.docs.xano.com/ship/source-of-truth.md): Decide whether your git repository or your Xano workspace holds the real backend, ship from that side only, and bring an emergency fix made in the Xano editor back into git with xanosdk pull.
- [Releases](https://sdk.docs.xano.com/ship/releases.md): Cut a release from an ephemeral, a Xano branch of your workspace or a throwaway tenant, choose which table rows it carries, name it safely, and list, inspect, export and delete releases.
- [Promote and go live](https://sdk.docs.xano.com/ship/promote-and-go-live.md): Land a release on a new Xano branch of your workspace with xanosdk promote, guard the switch with --expect-live, handle shared-schema and constraint refusals, and publish the frontend that belongs to the release.
- [Tenants](https://sdk.docs.xano.com/ship/tenants.md): Deploy a release to a tenant with xanosdk tenant deploy, which replaces what the tenant serves, and know what it drops, what it keeps, and how to recover when it stops partway.
- [Merge path](https://sdk.docs.xano.com/ship/merge-path.md): Merge a local build straight into your workspace or a tenant with xanosdk deploy --to, with a dry-run preview, a prune scoped to what this project landed, staging on a Xano branch, and the guard against overwriting edits made in Xano.
- [Across workspaces](https://sdk.docs.xano.com/ship/across-workspaces.md): Ship one release to another workspace or another Xano instance: sign in with a credential profile for each, copy the release with xanosdk release transfer, then promote it at the destination.
- [Govern](https://sdk.docs.xano.com/govern/overview.md): How the Xano SDK keeps shipping safe for a team and its coding agents: rules set once in the project and the pipeline, enforced on every change, and only a tested release reaching production.
- [Schema changes](https://sdk.docs.xano.com/govern/schema-changes.md): Change a table safely when every Xano branch shares the same tables: what lands without a flag, what promote refuses until you pass --allow-shared-schema-changes, and how to rename or drop a column across two releases with expand, backfill and contract.
- [Drift](https://sdk.docs.xano.com/govern/drift.md): Find out when your Xano workspace and your project have moved apart: the sync baseline in xano.lock, xanosdk workspace diff and its exit code, the 1.0.8 guard on deploy --to workspace, pulling editor changes back into git, and a scheduled drift check in CI.
- [Rollback and recovery](https://sdk.docs.xano.com/govern/rollback-and-recovery.md): Go back to the previous release on your workspace with workspace branch set-live or on a tenant with tenant deploy, restore logic after a merge with --backup-branch, roll back the frontend, and recover a tenant deploy that stopped partway or a release write whose outcome is unknown (exit 9).
- [CI/CD](https://sdk.docs.xano.com/govern/ci-cd.md): Run the Xano SDK release flow from GitHub Actions: headless credentials, npm run xano:check and --frozen-lock on every change, a preview ephemeral for each pull request, a release cut and landed on every tag, the xano.lock landing record committed back, and how to handle exit codes 2, 7 and 9.
- [Git, locks & merges](https://sdk.docs.xano.com/govern/git-and-merges.md): What to commit, how to resolve a xano.lock conflict, handling renames across branches, and the four things a reviewer has to check that a normal code review misses.
- [Agent guardrails](https://sdk.docs.xano.com/govern/agent-guardrails.md): Decide which Xano SDK commands a coding agent may run on its own and which wait for your approval, give it checks that fail loudly with export --strict and preflight, and have it read --json documents and exit codes instead of terminal text.
- [Coding agents](https://sdk.docs.xano.com/ai/coding-agents.md): Set up Claude Code, Codex, Cursor and other coding agents to write your Xano backend with the Xano SDK: install the agent skill, keep the managed AGENTS.md current, and point the agent at the SDK's own docs.
- [Docs for agents](https://sdk.docs.xano.com/ai/docs-for-agents.md): Give a coding agent these docs as llms.txt, llms-full.txt, a Markdown copy of any page, or the site's hosted MCP server, and know when to use the SDK's own in-package docs instead.
- [Troubleshooting](https://sdk.docs.xano.com/help/troubleshooting.md): Find the symptom you are seeing, from a first deploy that fails on your platform to a refused promote or an expired ephemeral, and the command that fixes it.
- [Exit codes and outcomes](https://sdk.docs.xano.com/help/exit-codes-and-outcomes.md): What each xanosdk exit code means and what to do next, the JSON failure document every failed command writes, and how to read the completed yes, no or unknown outcome of a release write.
- [Glossary](https://sdk.docs.xano.com/help/glossary.md): One plain definition for each term the Xano SDK docs and CLI use, from release, cut and landing to backend selector, sync baseline and Xano branch, each linked to the page that teaches it.
- [Reference](https://sdk.docs.xano.com/reference/index.md): What the Reference tab holds, which pages are generated from @xano/sdk 1.0.8 and which are written by hand, and a link to every reference group.
- [Authoring reference](https://sdk.docs.xano.com/reference/authoring.md): Tables and fields, the statement and value surfaces, inputs, and the request-scoped machinery around them.
- [Object kinds](https://sdk.docs.xano.com/reference/object-kinds.md): Every object kind Xano SDK can author, and how to split a workspace across microservices.
- [Config files](https://sdk.docs.xano.com/reference/config-files.md): Every file the Xano SDK reads or writes in a project and on your machine, what each one holds, and which ones to commit to git.
- [Environment & identity](https://sdk.docs.xano.com/reference/environment-variables.md): The environment variables Xano SDK reads on your machine, the workspace env vars your deployed stack reads at runtime, and how `xano.lock` pins object identity across deploys. Every build writes the lock; commit it.
- [Platforms](https://sdk.docs.xano.com/reference/platforms.md): The operating systems and CPUs the Xano Engine runs on, the Node.js version the Xano SDK needs, and what to use on a platform with no Engine build.
- [CLI overview](https://sdk.docs.xano.com/reference/cli/index.md): 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.
- [xanosdk compile](https://sdk.docs.xano.com/reference/cli/compile.md): Compile a single object def and print its JSON artifact (not type-checked — run `tsc` for that)
- [xanosdk export](https://sdk.docs.xano.com/reference/cli/export.md): Compile and write the deployable JSON bundle.
- [xanosdk routes](https://sdk.docs.xano.com/reference/cli/routes.md): List each query's verb + resolved api:<canonical>/<name>.
- [xanosdk paths](https://sdk.docs.xano.com/reference/cli/paths.md): Alias for `routes` (alias of `routes`)
- [xanosdk init](https://sdk.docs.xano.com/reference/cli/init.md): Scaffold a Xano SDK project — empty, or filled from an existing backend. In a non-empty directory, add the backend to the project there.
- [xanosdk marketplace details](https://sdk.docs.xano.com/reference/cli/marketplace-details.md): Show what an add-on installs, what it needs, and how to register it.
- [xanosdk marketplace install](https://sdk.docs.xano.com/reference/cli/marketplace-install.md): Install a marketplace module into the Xano SDK project in the current directory, by package or catalogue name (auth resolves to @xano-sdk/auth); a name the marketplace does not list exits 8.
- [xanosdk marketplace list](https://sdk.docs.xano.com/reference/cli/marketplace-list.md): List every published add-on, newest first.
- [xanosdk marketplace reinstall](https://sdk.docs.xano.com/reference/cli/marketplace-reinstall.md): Re-ask the questions for an installed toolchain module and re-apply its settings (takes the names install takes)
- [xanosdk marketplace remove](https://sdk.docs.xano.com/reference/cli/marketplace-remove.md): Uninstall a Xano SDK module and drop the settings and file lines it contributed (takes the names install takes)
- [xanosdk marketplace search](https://sdk.docs.xano.com/reference/cli/marketplace-search.md): Search add-ons by keyword across name, tagline and description.
- [xanosdk pull](https://sdk.docs.xano.com/reference/cli/pull.md): Refresh the backend of this project from a live one — rewrites the files it decodes, keeps and names files you added, and lists and confirms first.
- [xanosdk generate](https://sdk.docs.xano.com/reference/cli/generate.md): Decode a backend or a bundle .json into a Xano SDK source tree, with no project around it.
- [xanosdk deploy](https://sdk.docs.xano.com/reference/cli/deploy.md): Deploy to the Xano Engine on this machine (default) or an ephemeral (--ephemeral) → URL.
- [xanosdk env pull](https://sdk.docs.xano.com/reference/cli/env-pull.md): Fill the local .env from a backend that is running. Over an existing file it lists what changes and confirms, then rewrites the whole file; a missing file is created without asking, and identical values write nothing.
- [xanosdk env set](https://sdk.docs.xano.com/reference/cli/env-set.md): Set ONE env var on a running backend by name — creates it or replaces its value, leaves every other one alone. The value is the second argument, or stdin when omitted; it is never printed.
- [xanosdk env unset](https://sdk.docs.xano.com/reference/cli/env-unset.md): Clear ONE env var on a running backend by name, leaving every other one alone. A name it does not have is reported, not an error.
- [xanosdk secrets fill](https://sdk.docs.xano.com/reference/cli/secrets-fill.md): Mint a token for every documentation gate that has none (never replaces one)
- [xanosdk release create](https://sdk.docs.xano.com/reference/cli/release-create.md): Cut a release from a running environment, tenant, or the workspace.
- [xanosdk release delete](https://sdk.docs.xano.com/reference/cli/release-delete.md): Remove a release. Anything running it keeps running.
- [xanosdk release export](https://sdk.docs.xano.com/reference/cli/release-export.md): Write a release out as XanoScript (its `workspace` block is named after the release)
- [xanosdk release list](https://sdk.docs.xano.com/reference/cli/release-list.md): Every release in this workspace.
- [xanosdk release show](https://sdk.docs.xano.com/reference/cli/release-show.md): One release: where it came from, and what it carries.
- [xanosdk release transfer](https://sdk.docs.xano.com/reference/cli/release-transfer.md): Copy a stored release to another workspace or instance, checked by content hash.
- [xanosdk promote](https://sdk.docs.xano.com/reference/cli/promote.md): Land a release in your real workspace.
- [xanosdk publish](https://sdk.docs.xano.com/reference/cli/publish.md): Publish an already-built frontend to a static host — no compile, no backend import.
- [xanosdk preflight](https://sdk.docs.xano.com/reference/cli/preflight.md): Deploy to a throwaway tenant and verify the round-trip (needs auth)
- [xanosdk tenant delete](https://sdk.docs.xano.com/reference/cli/tenant-delete.md): Destroy a tenant and everything it serves.
- [xanosdk tenant deploy](https://sdk.docs.xano.com/reference/cli/tenant-deploy.md): Replace what a tenant serves with a release.
- [xanosdk tenant get](https://sdk.docs.xano.com/reference/cli/tenant-get.md): The URL and state of one tenant.
- [xanosdk tenant list](https://sdk.docs.xano.com/reference/cli/tenant-list.md): Every tenant under this workspace.
- [xanosdk workspace branch](https://sdk.docs.xano.com/reference/cli/workspace-branch.md): List its branches, set one live, or delete one.
- [xanosdk workspace details](https://sdk.docs.xano.com/reference/cli/workspace-details.md): Which instance and workspace am I bound to?
- [xanosdk workspace diff](https://sdk.docs.xano.com/reference/cli/workspace-diff.md): Compare it (or one of its branches) against a local compile — which objects differ, are missing, or are unexpected. Exits 2 when anything declared differs or is missing.
- [xanosdk workspace export](https://sdk.docs.xano.com/reference/cli/workspace-export.md): Write its bundle JSON.
- [xanosdk workspace reset-tables](https://sdk.docs.xano.com/reference/cli/workspace-reset-tables.md): Put named tables back to the seed rows your project compiles — every other table is left alone.
- [xanosdk ephemeral delete](https://sdk.docs.xano.com/reference/cli/ephemeral-delete.md): Tear an env down now instead of waiting for its TTL.
- [xanosdk ephemeral export](https://sdk.docs.xano.com/reference/cli/ephemeral-export.md): Write an env's bundle JSON (default: the ephemeral this project deployed to)
- [xanosdk ephemeral get](https://sdk.docs.xano.com/reference/cli/ephemeral-get.md): Show one env's URL, status, and expiry.
- [xanosdk ephemeral list](https://sdk.docs.xano.com/reference/cli/ephemeral-list.md): List the ephemeral envs under your workspace.
- [xanosdk local cache](https://sdk.docs.xano.com/reference/cli/local-cache.md): `list`: each cached engine version, its size on disk, and the engines running on it. `clear`: remove every cached engine and the runtime they unpacked, or one with `--version <v>` — any engine running on a removed version is stopped first; the next deploy fetches and restarts it.
- [xanosdk local list](https://sdk.docs.xano.com/reference/cli/local-list.md): List Xano Engines on this machine, marking the ones xanosdk started.
- [xanosdk local mcp](https://sdk.docs.xano.com/reference/cli/local-mcp.md): Print how a coding agent connects to a Xano Engine's MCP server (look at the backend, seed rows, run functions, tasks, triggers, endpoints and tests); `--stdio` runs the bridge the agent's MCP config launches (default: the engine this project deployed to)
- [xanosdk local stop](https://sdk.docs.xano.com/reference/cli/local-stop.md): Stop one Xano Engine by name, or every one xanosdk started on this machine.
- [xanosdk local token](https://sdk.docs.xano.com/reference/cli/local-token.md): Print a Xano Engine's meta API bearer — the local XANO_META_TOKEN; `--json` adds its url and workspace id. Re-run after a restart, which re-mints it (default: the engine this project deployed to)
- [xanosdk local update](https://sdk.docs.xano.com/reference/cli/local-update.md): Move this project's pinned engine to the latest release (or `--version <v>`, downgrades included), download it, and restart the project's running engine on it — the restarted engine starts empty, so the next deploy seeds it. Writes package.json: commit it.
- [xanosdk test list](https://sdk.docs.xano.com/reference/cli/test-list.md): List the tests in an environment, without running any.
- [xanosdk test run](https://sdk.docs.xano.com/reference/cli/test-run.md): Run one test by name.
- [xanosdk test run-all](https://sdk.docs.xano.com/reference/cli/test-run-all.md): Run every test in an environment and report pass/fail.
- [xanosdk tables](https://sdk.docs.xano.com/reference/cli/tables.md): List a backend's tables with their guids, for `release create --seed` (default: the backend this project last deployed to). Guids survive a redeploy, so one written down earlier keeps matching — and a rename whose xano.lock entry moves with it (`lock rename`) keeps it too; one the lock is not told a…
- [xanosdk impersonate](https://sdk.docs.xano.com/reference/cli/impersonate.md): Open a backend's dashboard in the builder as a scoped session — the url carries it, so treat it as a credential (default: the backend this project last deployed to)
- [xanosdk login](https://sdk.docs.xano.com/reference/cli/login.md): OAuth sign-in — shared cache, or --local-auth per project.
- [xanosdk logout](https://sdk.docs.xano.com/reference/cli/logout.md): Revoke the active profile and remove it from the credential file.
- [xanosdk status](https://sdk.docs.xano.com/reference/cli/status.md): Who am I, which workspace, and the env this project last deployed to.
- [xanosdk whoami](https://sdk.docs.xano.com/reference/cli/whoami.md): Show the signed-in user and instance URL.
- [xanosdk profile add](https://sdk.docs.xano.com/reference/cli/profile-add.md): Store a meta API token credential under a name — the token is read from piped stdin or the terminal, and checked against the instance.
- [xanosdk profile delete](https://sdk.docs.xano.com/reference/cli/profile-delete.md): Remove a profile, revoking its sign-in session — a meta API token stays valid until revoked at its source.
- [xanosdk profile list](https://sdk.docs.xano.com/reference/cli/profile-list.md): Every stored profile, with the default and the active one marked.
- [xanosdk profile set-default](https://sdk.docs.xano.com/reference/cli/profile-set-default.md): Set the profile THIS MACHINE falls back to when nothing else selects one.
- [xanosdk profile show](https://sdk.docs.xano.com/reference/cli/profile-show.md): What one profile addresses — never its token (default: the active one)
- [xanosdk profile use](https://sdk.docs.xano.com/reference/cli/profile-use.md): Pin THIS PROJECT to a profile, in a committed xano.profile.json.
- [xanosdk lock import](https://sdk.docs.xano.com/reference/cli/lock-import.md): Import identities from a live backend's exported bundle (`xanosdk workspace export`), so existing objects are not recreated.
- [xanosdk lock prune](https://sdk.docs.xano.com/reference/cli/lock-prune.md): Drop orphaned entries (all, or just the named keys)
- [xanosdk lock rename](https://sdk.docs.xano.com/reference/cli/lock-rename.md): Move an entry keeping its identity, so the next export renames in place.
- [xanosdk completion](https://sdk.docs.xano.com/reference/cli/completion.md): Print a shell completion script (bash, zsh, fish)
- [xanosdk version](https://sdk.docs.xano.com/reference/cli/version.md): Print the CLI version.
- [xanosdk upgrade](https://sdk.docs.xano.com/reference/cli/upgrade.md): Install the latest @xano/sdk, or report an available upgrade with --check.
- [xanosdk agent-skill install](https://sdk.docs.xano.com/reference/cli/agent-skill-install.md): Write the skill into the user-level skill directory of each detected agent; an edited copy is left alone unless --force.
- [xanosdk agent-skill status](https://sdk.docs.xano.com/reference/cli/agent-skill-status.md): Report each copy as current, stale, edited or absent.
- [xanosdk agent-skill uninstall](https://sdk.docs.xano.com/reference/cli/agent-skill-uninstall.md): Remove the copies install wrote; an edited copy is reported and kept.
- [xanosdk help](https://sdk.docs.xano.com/reference/cli/help.md): Show this help.
- [Warning and error codes](https://sdk.docs.xano.com/reference/error-codes.md): Every code the CLI and the build emit, with the first sentence of the message it comes with. Match on the code, never on the message text: messages are reworded, codes are not.
- [Coverage & agent grounding](https://sdk.docs.xano.com/reference/coverage.md): What Xano SDK covers against the engine catalog, what is deliberately out of scope, and the machine-readable grounding it ships for agents.
- [Reading a compiled bundle](https://sdk.docs.xano.com/reference/bundle.md): `@xano/sdk` writes a bundle; `@xano/sdk/bundle` reads one back. It is the surface for tools that take compiled JSON as input — a graph view, a diff, a linter, a docs generator — so none of them has to reverse-engineer the storage shape and then go quietly wrong when the engine grows a new one.
- [The marketplace](https://sdk.docs.xano.com/reference/marketplace.md): Finding published add-ons, adding one to the project you are standing in, and what the CLI does that `npm install` does not.
- [The module contract](https://sdk.docs.xano.com/reference/module-contract.md): How to build a Xano SDK add-on: the manifest fields both kinds of module declare, the `@xano/sdk/plugin` types a toolchain module compiles against, every hook and when it fires, and the shapes the SDK refuses rather than absorbs.
- [Changelog](https://sdk.docs.xano.com/changelog.md): Every @xano/sdk release, newest first, with a summary and a link to its full release notes.

## Optional

- [GitHub](https://github.com/xano-sdk/sdk)
- [npm](https://www.npmjs.com/package/@xano/sdk)
- [xano.com](https://xano.com/sdk/)


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