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

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>

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>

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>

## Verify Your Setup

Check that everything is configured correctly:

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

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>

<Tip>
  See [Profiles](/xano-cli/profiles) for everything else — targeting a profile per command with `-p`, creating profiles for CI/CD, the interactive wizard, and pinning a project to a profile with a local `profile.yaml`.
</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>

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, you'll need to push 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>

<Note>
  Not seeing the data you expect? You might need to reset your sandbox by running `xano sandbox reset` and then trying the push again.
</Note>

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

Free plan users can push directly right away. If you're on a paid plan, find the "Enable Direct Workspace Push" option in your workspace settings and enable it to push without using the sandbox.

<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. Existing objects are matched by the `guid` stored in each file — there's no manifest and file paths don't matter — so re-pushing updates them in place rather than duplicating. See [How objects are identified](/xano-cli/push-pull#how-objects-are-identified-binding-local-to-remote).

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.
* **Watch for `[CRITICAL]` and `[IMPORTANT]` cues.** Destructive commands and flags carry imperative warnings in their `--help` text and descriptions so agents in auto-accept mode pause before running them:
  * **`[CRITICAL]`** — the agent must stop and confirm with you. Used for irreversible or high-blast-radius operations (e.g. `sandbox reset`, `--force` deletes, `workspace push --truncate`, `--sync --delete`).
  * **`[IMPORTANT]`** — the agent should confirm with you and prefer a `--dry-run` preview first. Used for impactful-but-reversible operations (e.g. base `workspace push` / `sandbox push`, `branch set_live`, release deploys).
* **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>

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>


## Related topics

- [Get Started](/index.md)
- [AI-Assisted Development](/getting-started-ai.md)
- [Get Started Assistant](/xano-ai/get-started-assistant.md)