> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xano.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started

> Install the Xano CLI and connect to your workspace in under two minutes

export const BrowserFrame = props => {
  const {url = "xano.run", maxWidth = 820, className = "", lightSrc, darkSrc, alt = "", children} = props || ({});
  const style = typeof maxWidth === "number" ? {
    maxWidth: `${maxWidth}px`,
    margin: "16px 0"
  } : {
    maxWidth,
    margin: "16px 0"
  };
  const hasSwapImages = Boolean(lightSrc && darkSrc);
  return <div className={`browser-frame ${className}`.trim()} style={style}>
      <div className="browser-frame__top">
        <div className="browser-frame__controls" aria-hidden="true">
          <span className="browser-frame__dot browser-frame__dot--red" />
          <span className="browser-frame__dot browser-frame__dot--yellow" />
          <span className="browser-frame__dot browser-frame__dot--green" />
        </div>
        <div className="browser-frame__address">{url}</div>
      </div>

      <div className="browser-frame__body">
        {hasSwapImages ? <>
            <img className="browser-frame__img--light" src={lightSrc} alt={alt} />
            <img className="browser-frame__img--dark" src={darkSrc} alt={alt} />
          </> : children}
      </div>
    </div>;
};

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:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  npm install -g @xano/cli
  ```
</BrowserFrame>

<Accordion title="Don't have npm installed? Install Node.js for Mac or Windows">
  The Xano CLI requires [Node.js](https://nodejs.org), which includes npm (the Node Package Manager). We recommend installing the **LTS (Long Term Support)** version.

  <Tabs>
    <Tab title="macOS">
      **Option 1: Official installer (easiest)**

      1. Download the macOS installer from [nodejs.org](https://nodejs.org).
      2. Open the `.pkg` file and follow the installation prompts.
      3. Once finished, open a new Terminal window and verify the install:

      <BrowserFrame url="Terminal">
        ```bash theme={null}
        node --version
        npm --version
        ```
      </BrowserFrame>

      **Option 2: Homebrew**

      If you use [Homebrew](https://brew.sh):

      <BrowserFrame url="Terminal">
        ```bash theme={null}
        brew install node
        ```
      </BrowserFrame>
    </Tab>

    <Tab title="Windows">
      **Option 1: Official installer (easiest)**

      1. Download the Windows installer (`.msi`) from [nodejs.org](https://nodejs.org).
      2. Run the installer and accept the defaults — be sure to leave **"Automatically install the necessary tools"** checked if prompted.
      3. Once finished, open a new PowerShell or Command Prompt window and verify the install:

      <BrowserFrame url="Terminal">
        ```powershell theme={null}
        node --version
        npm --version
        ```
      </BrowserFrame>

      **Option 2: winget**

      If you're on Windows 10/11 with [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/):

      <BrowserFrame url="Terminal">
        ```powershell theme={null}
        winget install OpenJS.NodeJS.LTS
        ```
      </BrowserFrame>
    </Tab>
  </Tabs>

  Once Node.js is installed, return to the `npm install -g @xano/cli` command above.
</Accordion>

Verify the installation:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano --version
  ```
</BrowserFrame>

### Updating

Already have the CLI installed? Update to the latest version:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano update
  ```
</BrowserFrame>

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano update
  ```
</BrowserFrame>

To check if an update is available without installing it:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano update --check
  ```
</BrowserFrame>

## Authentication

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

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano auth
  ```
</BrowserFrame>

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano auth
  ```
</BrowserFrame>

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.

<Tip>
  Already have an access token? Use the [Profile Wizard](/xano-cli/profiles#profile-wizard) instead for a token-based setup — useful for CI/CD environments or when you prefer non-interactive auth.
</Tip>

### Other Environments

If you're using a self-hosted or on-prem Xano instance, pass the `-o` flag with your environment URL:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano auth -o https://my-xano.my-domain.com
  ```
</BrowserFrame>

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano auth -o https://my-xano.my-domain.com
  ```
</BrowserFrame>

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:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano auth -o https://my-xano.my-domain.com --insecure
  ```
</BrowserFrame>

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano auth -o https://my-xano.my-domain.com --insecure
  ```
</BrowserFrame>

## Verify Your Setup

Check that everything is configured correctly:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano profile me
  ```
</BrowserFrame>

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano profile me
  ```
</BrowserFrame>

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

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano profile list
  ```
</BrowserFrame>

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano profile list
  ```
</BrowserFrame>

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

### Switch Default Profile

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano profile set my-profile
  ```
</BrowserFrame>

### Use a Profile for a Single Command

Override the default profile for any command with `-p`:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano workspace pull -d ./my-workspace -p staging
  ```
</BrowserFrame>

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano workspace pull -d ./my-workspace -p staging
  ```
</BrowserFrame>

You can also set the `XANO_PROFILE` environment variable:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  export XANO_PROFILE=staging
  ```
</BrowserFrame>

<Tip>
  See [Profiles](/xano-cli/profiles) for the full list of profile commands, including creating profiles manually for CI/CD, editing profile fields, and the interactive profile wizard.
</Tip>

## Your First Pull

Now that you're connected, pull your workspace down as local XanoScript files:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano workspace pull -d ./my-workspace
  ```
</BrowserFrame>

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano workspace pull -d ./my-workspace
  ```
</BrowserFrame>

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.

<Tip>
  See [Push & Pull](/xano-cli/push-pull) for the full breakdown of the directory structure and all available flags.
</Tip>

## Your First Push

<Note>
  Before pushing regularly, review the [Best Practices](#best-practices) section below — especially around using Git and understanding schema changes.
</Note>

Once you've made changes to your local XanoScript files, we recommend pushing them to your [Sandbox](/xano-cli/sandbox) first — an isolated copy of your workspace where you can safely test changes before promoting them to your live workspace:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano sandbox push -d ./my-workspace
  ```
</BrowserFrame>

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano sandbox push -d ./my-workspace
  ```
</BrowserFrame>

After pushing, review and promote the changes from the sandbox to your workspace through the browser:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano sandbox review
  ```
</BrowserFrame>

<Note>
  Sandbox access is not available on the free plan. Free users should push directly to their workspace using `xano workspace push` (shown below).
</Note>

### Pushing Directly to Your Workspace

If you're on the free plan, or prefer to push directly without using a sandbox, push to your workspace:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano workspace push -d ./my-workspace
  ```
</BrowserFrame>

The CLI will display a [push preview](/xano-cli/push-pull#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`:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano workspace push -d ./my-workspace --dry-run
  ```
</BrowserFrame>

<Tip>
  See [Push & Pull](/xano-cli/push-pull) for the full list of push options, including `--delete`, `--force`, and selective pushing. For the complete sandbox workflow, see [Sandbox](/xano-cli/sandbox).
</Tip>

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

<Snippet file="cli-git-init.mdx" />

### Work on a Non-Live Branch

We recommend developing on a [non-live branch](/xano-cli/workspaces-and-branches#create-a-branch) or a secondary workspace, and promoting to live only after testing.

### Schema Changes

<Snippet file="cli-schema-push-warning.mdx" />

### 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 -d ./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`:

```json theme={null}
{
  "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:

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

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano workspace pull -d ./my-workspace -v
  ```
</BrowserFrame>

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano workspace pull -d ./my-workspace -v
  ```
</BrowserFrame>

This shows the full URL, request headers (with the token partially masked), request body, response status, and elapsed time.

<Tip>
  For the complete list of all CLI commands and flags — including `xano branch`, `xano release`, `xano function`, and more — see the [Command Reference](/xano-cli/command-reference).
</Tip>

## What's Next

<CardGroup cols={2}>
  <Card title="Profiles" icon="user-gear" href="/xano-cli/profiles">
    Manage multiple profiles for different workspaces, branches, and environments
  </Card>

  <Card title="Push & Pull" icon="arrows-rotate" href="/xano-cli/push-pull">
    Sync XanoScript between your local filesystem and Xano
  </Card>

  <Card title="Workspaces & Branches" icon="code-branch" href="/xano-cli/workspaces-and-branches">
    Manage workspaces and branches from the CLI
  </Card>

  <Card title="Start from Scratch" icon="sparkles" href="/xano-cli/guide-from-scratch">
    Build a new Xano backend from zero using the CLI
  </Card>

  <Card title="Work from Existing" icon="download" href="/xano-cli/guide-from-existing">
    Pull down an existing workspace and develop locally
  </Card>

  <Card title="Team Workflows" icon="users" href="/xano-cli/team-workflows">
    Git branching, code review, and collaboration for teams
  </Card>

  <Card title="Command Reference" icon="rectangle-list" href="/xano-cli/command-reference">
    Complete list of all CLI commands and flags
  </Card>
</CardGroup>