Skip to main content
The Xano CLI (@xano/cli) lets you manage your Xano workspaces, push and pull XanoScript, and work with branches — all from your terminal.

​
Installation

Install the CLI globally via npm: Verify the installation:

​
Updating

Already have the CLI installed? Update to the latest version: To check if an update is available without installing it:

​
Authentication

The fastest way to get started is with browser-based authentication: This opens your browser to the Xano login page. After signing in, you’ll be guided through selecting:
  1. Instance — the Xano instance to connect to
  2. Workspace — the workspace you want to work in (optional)
  3. Branch — the branch to target (optional)
  4. Profile name — a name for this configuration (defaults to “default”)
Your credentials are saved to ~/.xano/credentials.yaml and the profile is set as your default.
Already have an access token? Use the Profile Wizard instead for a token-based setup — useful for CI/CD environments or when you prefer non-interactive auth.

​
Other Environments

If you’re using a self-hosted Xano instance or a non-production environment, pass the -o flag with your environment URL:
The -o (origin) flag tells the CLI where to direct the authentication flow. For self-hosted instances, the CLI automatically detects that the origin is the instance itself and skips the instance selection step. If your self-hosted instance uses a self-signed TLS certificate, add the --insecure (-k) flag to skip certificate verification:

​
Verify Your Setup

Check that everything is configured correctly: This calls the Xano API and returns a summary of your current setup, including:
  • CLI Information — your active profile name and CLI version
  • Account — your authenticated user details
  • Instance — the connected instance, along with the workspace and branch your profile targets (if set)
Use -o json for the full JSON response.

​
Managing Profiles

Profiles let you store multiple configurations and quickly switch between them. Each profile saves an access token, instance, workspace, and branch — so you can target different environments without re-authenticating.

​
List Profiles

Add -d for full details including origin URLs, workspace IDs, and masked tokens.

​
Switch Default Profile

​
Use a Profile for a Single Command

Override the default profile for any command with -p: You can also set the XANO_PROFILE environment variable:
See Profiles for the full list of profile commands, including creating profiles manually for CI/CD, editing profile fields, and the interactive profile wizard.

​
Your First Pull

Now that you’re connected, pull your workspace down as local XanoScript files: This creates a directory of .xs files organized by type — tables, APIs, functions, tasks, and more. You can edit these files locally, track them with Git, and push changes back to Xano.
See Push & Pull for the full breakdown of the directory structure and all available flags.

​
Your First Push

Before pushing regularly, review the Best Practices section below — especially around using Git and understanding schema changes.
Once you’ve made changes to your local XanoScript files, push them back to Xano: The CLI will display a push preview showing exactly what will be created, updated, or deleted. Review the preview carefully, then confirm to apply the changes. If you want to see what would happen without applying anything, use --dry-run:
See Push & Pull for the full list of push options, including --delete, --force, and selective pushing.

​
Best Practices

​
Use Git to Protect Your Work

Because the CLI syncs schema definitions that directly affect your database, treat your local XanoScript files like production infrastructure code:
  • Initialize a git repository in your workspace directory so every change is tracked.
  • Review diffs before pushing — run git diff to inspect what has changed since your last push.
  • Commit before pushing — create a git commit before running xano workspace push so you have a known-good snapshot to revert to.

​
Work on a Non-Live Branch

We recommend developing on a non-live branch or a secondary workspace, and promoting to live only after testing.

​
Schema Changes

Pushing changes can modify your database schema.When you push XanoScript that alters table structures, such as removing or renaming columns or changing field types, those changes are applied directly to your Xano workspace. Unaudited changes can result in data loss. You can snapshot your data beforehand by pulling with --records. See Managing Data for details.Every push automatically shows a push preview of exactly what will be created, updated, or deleted, including destructive schema change, before prompting for confirmation. Always review the preview before proceeding.Xano maintains rolling backups of your instance on all paid plans. Read more about restoring backups.

​
Using the CLI with AI Agents

If you’re using an AI agent — like Claude Code or another tool that can execute terminal commands — be deliberate about what permissions you grant it.
  • Review commands before they run. Read carefully, especially if a command includes flags like --delete, --force, or --records.
  • Use --dry-run for safe previews. Running xano workspace push ./my-workspace --dry-run shows the full push preview then exits without applying anything.
  • Restrict agent permissions when in doubt. You can add a deny rule to Claude Code’s .claude/settings.json:
{
  "permissions": {
    "deny": ["Bash(xano workspace push*)"]
  }
}
This prevents the agent from running push commands automatically. Note that --dry-run is safe to allow since it never applies changes.

​
Global Flags

These flags are available on all CLI commands:
FlagEnv VariableDescription
-p, --profileXANO_PROFILEUse a specific profile (overrides default)
-v, --verboseXANO_VERBOSEShow detailed request/response information for troubleshooting

​
Verbose Mode

When something isn’t working as expected, add -v to any command to see the underlying HTTP request and response: This shows the full URL, request headers (with the token partially masked), request body, response status, and elapsed time.
For the complete list of all CLI commands and flags — including xano branch, xano release, xano function, and more — see the Command Reference.

​
What’s Next

Profiles

Manage multiple profiles for different workspaces, branches, and environments

Push & Pull

Sync XanoScript between your local filesystem and Xano

Workspaces & Branches

Manage workspaces and branches from the CLI

Start from Scratch

Build a new Xano backend from zero using the CLI

Work from Existing

Pull down an existing workspace and develop locally

Command Reference

Complete list of all CLI commands and flags