Get Started

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

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. Always review what you’re about to push before running xano workspace push.We recommend working on a non-live branch or a secondary workspace when developing with the CLI, and promoting to live only after testing.

Use Git to Protect Your Work

Because the CLI syncs schema definitions that directly affect your database, you should treat your local XanoScript files with the same care as production infrastructure code:

Initialize a git repository in your workspace directory so every change is tracked.
Review diffs before pushing — run git diff (or use your IDE’s diff viewer) to inspect exactly what has changed since your last push. Pay close attention to table schema modifications.
Commit before pushing — create a git commit before running xano workspace push so you have a known-good snapshot to revert to if something goes wrong.
Be especially careful with schema changes — renaming or removing columns or changing field types can cause data loss. Double-check these changes and consider backing up critical data first.

You can pull a local copy of your database records at any time with xano workspace pull ./my-workspace --records. This is a quick way to snapshot your data before pushing schema changes.

Xano maintains rolling backups of your instance on all paid plans. Read more about restoring backups.

Installation

Install the CLI globally via npm:

Terminal

npm install -g @xano/cli

Verify the installation:

Terminal

xano --version

Authentication

The fastest way to get started is with browser-based authentication:

Terminal

xano auth

This opens your browser to the Xano login page. After signing in, you’ll be guided through selecting:

Instance — the Xano instance to connect to
Workspace — the workspace you want to work in (optional)
Branch — the branch to target (optional)
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.

Other Environments

If you’re using a self-hosted Xano instance or a non-production environment, pass the -o flag with your environment URL:

Self-Hosted
Beta

Terminal

xano auth -o https://my-xano.my-domain.com

Terminal

xano auth -o https://beta.xano.io

The -o (origin) flag tells the CLI where to direct the authentication flow. This is the URL where your Xano account management UI is hosted. 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:

Terminal

xano auth -o https://my-xano.my-domain.com --insecure

Profile Wizard

The profile wizard provides a step-by-step, interactive setup using an access token instead of browser-based login. This is useful for CI/CD environments, self-hosted instances, or when you prefer token-based auth.

Terminal

xano profile wizard

Enter your access token

You’ll be prompted to enter your Xano access token (input is hidden for security).You can generate an access token from your Xano account settings under API Access.

Select your instance

The CLI fetches all instances associated with your account. Choose the one you want to work with.

? Select an instance:
❯ My Production Instance (us-east-1)
  My Staging Instance (eu-west-1)

Name your profile

Give this profile a name. This lets you maintain multiple profiles for different environments.

? Profile name: (default)

Select a workspace

Choose a workspace from your instance, or skip to configure later.

? Select a workspace:
❯ My App Backend
  Marketing Site API
  (skip)

Select a branch

If you selected a workspace, you’ll be asked to choose a branch. Skip to use the live branch.

? Select a branch:
❯ v1 (live)
  v2-development
  (skip)

The profile is saved and set as your default. You can create additional profiles to quickly switch between workspaces, branches, or instances.

Wizard for Other Environments

For self-hosted or beta environments, pass the -o flag:

Terminal

xano profile wizard -o https://my-xano.my-domain.com

You can also pre-set the profile name:

Terminal

xano profile wizard -n production -o https://my-xano.my-domain.com

Managing Profiles

Profiles let you store multiple configurations and quickly switch between them.

List Profiles

Terminal

xano profile list

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

Terminal

xano profile list -d

Create a Profile Manually

For scripting or CI/CD, create a profile directly without the interactive wizard:

Terminal

xano profile create my-profile \
  -t YOUR_ACCESS_TOKEN \
  -i https://your-instance.xano.io \
  -w WORKSPACE_ID \
  -b BRANCH_LABEL \
  --default

Flag	Description
`-t`	Access token (required)
`-i`	Instance origin URL (required)
`-a`	Account origin URL (for self-hosted)
`-w`	Workspace ID
`-b`	Branch label
`-k, --insecure`	Skip TLS certificate verification (for self-signed certs)
`--default`	Set as the default profile

Edit a Profile

Update any field on an existing profile:

Terminal

xano profile edit my-profile -w NEW_WORKSPACE_ID

To clear a field, use the corresponding --remove-* flag:

Terminal

xano profile edit my-profile --remove-branch

You can also enable or disable insecure mode (self-signed certificate support) on an existing profile:

Terminal

xano profile edit my-profile --insecure
xano profile edit my-profile --remove-insecure

When a profile has insecure mode enabled, all commands using that profile automatically skip TLS certificate verification.

Get Default Profile

Print the name of the current default profile:

Terminal

xano profile get

Switch Default Profile

Terminal

xano profile set my-profile

Print Access Token

Output the access token for the default profile (useful for piping to other commands):

Terminal

xano profile token

Print Workspace ID

Output the workspace ID for the default profile:

Terminal

xano profile workspace

Change Workspace Interactively

Switch the workspace on a profile by selecting from a list of available workspaces:

Terminal

xano profile workspace set

To target a specific profile:

Terminal

xano profile workspace set -p production

Delete a Profile

Terminal

xano profile delete my-profile

Add -f to skip the confirmation prompt.

Using a Profile for a Single Command

Override the default profile for any command with -p:

Terminal

xano workspace list -p staging

You can also set the XANO_PROFILE environment variable:

Terminal

export XANO_PROFILE=staging
xano workspace list

Global Flags

These flags are available on all CLI commands:

Flag	Env Variable	Description
`-p, --profile`	`XANO_PROFILE`	Use a specific profile (overrides default)
`-v, --verbose`	`XANO_VERBOSE`	Show 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:

Terminal

xano workspace pull ./my-workspace -v

This shows the full URL, request headers (with the token partially masked), request body, response status, and elapsed time — making it much easier to diagnose issues.

Verify Your Setup

Check that your profile is configured correctly:

Terminal

xano profile me

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.

Updating the CLI

Update to the latest version:

Terminal

xano update

To check if an update is available without installing it:

Terminal

xano update --check

What’s Next

Workspaces & Branches

Manage workspaces and branches from the CLI

Push & Pull

Sync XanoScript between your local filesystem and Xano

Start from Scratch

Build a new Xano backend from zero using the CLI

Work from Existing

Pull down an existing workspace and develop locally

Getting Started

Core Concepts

Commands

Guides

Use Git to Protect Your Work

Installation

Authentication

Other Environments

Profile Wizard

Wizard for Other Environments

Managing Profiles

List Profiles

Create a Profile Manually

Edit a Profile

Get Default Profile

Switch Default Profile

Print Access Token

Print Workspace ID

Change Workspace Interactively

Delete a Profile

Using a Profile for a Single Command

Global Flags

Verbose Mode

Verify Your Setup

Updating the CLI

What’s Next

Workspaces & Branches

Push & Pull

Start from Scratch

Work from Existing

Getting Started

Core Concepts

Commands

Guides

​Use Git to Protect Your Work

​Installation

​Authentication

​Other Environments

​Profile Wizard

​Wizard for Other Environments

​Managing Profiles

​List Profiles

​Create a Profile Manually

​Edit a Profile

​Get Default Profile

​Switch Default Profile

​Print Access Token

​Print Workspace ID

​Change Workspace Interactively

​Delete a Profile

​Using a Profile for a Single Command

​Global Flags

​Verbose Mode

​Verify Your Setup

​Updating the CLI

​What’s Next

Workspaces & Branches

Push & Pull

Start from Scratch

Work from Existing

Use Git to Protect Your Work

Installation

Authentication

Other Environments

Profile Wizard

Wizard for Other Environments

Managing Profiles

List Profiles

Create a Profile Manually

Edit a Profile

Get Default Profile

Switch Default Profile

Print Access Token

Print Workspace ID

Change Workspace Interactively

Delete a Profile

Using a Profile for a Single Command

Global Flags

Verbose Mode

Verify Your Setup

Updating the CLI

What’s Next