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

​
Other Environments

If you’re using a self-hosted Xano instance or a non-production environment, pass the -o flag with your environment URL:
Terminal
xano auth -o https://my-xano.my-domain.com
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.

​
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
1

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

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)
3

Name your profile

Give this profile a name. This lets you maintain multiple profiles for different environments.
? Profile name: (default)
4

Select a workspace

Choose a workspace from your instance, or skip to configure later.
? Select a workspace:
❯ My App Backend
  Marketing Site API
  (skip)
5

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
FlagDescription
-tAccess token (required)
-iInstance origin URL (required)
-aAccount origin URL (for self-hosted)
-wWorkspace ID
-bBranch label
--defaultSet 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

​
Switch Default Profile

Terminal
xano profile set_default my-profile

​
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:
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:
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 your authenticated account information. Use -o json for the full JSON response.

​
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