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

# Command-line Interface

> Complete reference for the Xata CLI

The Xata CLI is a powerful tool for managing your Xata databases, projects, and organizations from the command line. It provides commands for authentication, project management, database operations, and more.

## Installation

```bash theme={null}
# Install using the official install script
curl -fsSL https://xata.io/install.sh | bash
```

<Tip>
  The CLI binary will be installed to `~/.config/xata/bin/`. Make sure this directory is in your PATH.
</Tip>

## Installation (Docker)

```bash theme={null}
# Pull docker image
docker pull ghcr.io/xataio/xata:latest-pg18
```

<Tip>
  The container image supports the last 3 PostgreSQL major releases: 16, 17 and 18. To select one, edit the image suffix `-pg{majorversion}`.
</Tip>

## Installation (Windows)

```bash theme={null}
# Install using npm
powershell -c "irm https://xata.io/install.ps1 | iex"
```

<Tip>
  `xata clone` currently doesn't work with the native Windows installation. We currently recommend using WSL with the Linux binaries if you need the clone functionality on Windows. Track progress [here](https://github.com/xataio/pgstream/issues/409).
</Tip>

## Basic Usage

```bash theme={null}
xata [command] [subcommand] [options]
```

### Container image

```bash theme={null}
docker run -e XATA_API_KEY=yourkey ghcr.io/xataio/xata:latest-pg18 [command] [subcommand] [options]
```

## Available Commands

### Authentication

* [auth login](/cli/auth#login) - Log in to your Xata account
* [auth logout](/cli/auth#logout) - Log out of the current account
* [auth status](/cli/auth#status) - Display active account and authentication state
* [auth switch](/cli/auth#switch) - Switch to a different Xata account profile
* [auth access-token](/cli/auth#access-token) - Print the current access token
* [auth refresh-token](/cli/auth#refresh-token) - Print the current refresh token

### Organization Management

* [organization list](/cli/organization#list) - List all organizations
* [organization describe](/cli/organization#describe) - Describe an organization
* [organization create](/cli/organization#create) - Create a new organization
* [organization delete](/cli/organization#delete) - Delete an organization
* [organization get](/cli/organization#get) - Get a field from an organization description

### Project Management

* [init](/cli/init#init) - Link a project to the current folder
* [project list](/cli/project#list) - List all projects
* [project describe](/cli/project#describe) - Describe a project
* [project create](/cli/project#create) - Create a new project
* [project delete](/cli/project#delete) - Delete a project
* [project init](/cli/project#init) - Link a project to the folder
* [project get](/cli/project#get) - Get a field from a project description
* [project set](/cli/project#set) - Set a field value for a project

### Branch Management

* [branch list](/cli/branch#list) - List all branches
* [branch describe](/cli/branch#describe) - Describe a branch
* [branch create](/cli/branch#create) - Create a new branch
* [branch delete](/cli/branch#delete) - Delete a branch
* [branch url](/cli/branch#url) - Print URL (connection string) for a branch
* [branch checkout](/cli/branch#checkout) - Checkout a branch
* [branch tree](/cli/branch#tree) - List all branches as a tree
* [branch get](/cli/branch#get) - Get a field from a branch description
* [branch set](/cli/branch#set) - Set a field value for a branch
* [branch wait-ready](/cli/branch#wait-ready) - Wait for a branch to be ready

### API Key Management

* [keys user list](/cli/keys#list) - List API keys for the current user
* [keys user create](/cli/keys#create) - Create an API key for the current user
* [keys user delete](/cli/keys#delete) - Delete an API key for the current user
* [keys organization list](/cli/keys#list) - List API keys for an organization
* [keys organization create](/cli/keys#create) - Create an API key for an organization
* [keys organization delete](/cli/keys#delete) - Delete an API key for an organization

### Schema Migrations

* [roll baseline](/cli/roll#baseline) - Create a baseline migration for an existing database schema
* [roll complete](/cli/roll#complete) - Complete an ongoing migration
* [roll init](/cli/roll#init) - Initialize pgroll in the target database
* [roll latest](/cli/roll#latest) - Print the name of the latest schema version or migration
* [roll migrate](/cli/roll#migrate) - Apply outstanding migrations from a directory to a database
* [roll update](/cli/roll#update) - Update outdated migrations in a directory
* [roll pull](/cli/roll#pull) - Pull migration history from the target database and write it to disk
* [roll rollback](/cli/roll#rollback) - Roll back an ongoing migration
* [roll start](/cli/roll#start) - Start a migration
* [roll status](/cli/roll#status) - Show pgroll status
* [roll convert](/cli/roll#convert) - Convert SQL statements to a pgroll migration

### Database Synchronization

* [clone start](/cli/clone#start) - Clone a PostgreSQL database with anonymization
* [clone config](/cli/clone#config) - Configure transforms for the clone command
* [clone stream](/cli/clone#stream) - Start a continuous data stream using logical replication

### Utility Commands

* [status](/cli/status#status) - Get the status of the Xata CLI
* [version](/cli/version#version) - Get the version of the Xata CLI and pgroll
* [checkout](/cli/checkout#checkout) - Checkout a branch
* [upgrade](/cli/upgrade#upgrade) - Upgrade the Xata CLI
* [completions install](/cli/completions#install) - Install shell completions
* [completions uninstall](/cli/completions#uninstall) - Uninstall shell completions

## Global Flags

<ParamField path="-h, --help" type="boolean">
  Print help information and exit
</ParamField>

<ParamField path="-v, --version" type="boolean">
  Print version information and exit
</ParamField>

<ParamField path="--json" type="boolean">
  Output in JSON format (where applicable)
</ParamField>

## Environment Variables

The Xata CLI can be configured using environment variables. These are useful for CI/CD pipelines, automation workflows, and advanced configuration.

### Authentication & Configuration

These variables apply globally to all CLI commands.

<ParamField path="XATA_API_KEY" type="string">
  API key used to authenticate with Xata. In CI/CD environments, set this as a secret. Applies to all commands that require authentication.
</ParamField>

<ParamField path="XATA_API_ENVIRONMENT" type="string">
  Select the Xata API environment. Typically not needed unless instructed by Xata support. Applies to all commands.
</ParamField>

<ParamField path="XATA_CONFIG_DIR" type="string">
  Override the directory where the CLI stores its configuration files. Applies to all commands.
</ParamField>

### Project & Branch Configuration

These environment variables override the project and branch configuration normally stored in local config files. They apply to all commands that require project or branch context and are especially useful in CI/CD workflows where the CLI is not initialized interactively.

<ParamField path="XATA_ORGANIZATIONID" type="string">
  Your Xata organization ID.
</ParamField>

<ParamField path="XATA_PROJECTID" type="string">
  Your Xata project ID.
</ParamField>

<ParamField path="XATA_BRANCHID" type="string">
  The ID of the target branch.
</ParamField>

<ParamField path="XATA_BRANCHNAME" type="string">
  The name of the target branch.
</ParamField>

<ParamField path="XATA_DATABASENAME" type="string">
  The database name (default: `xata`).
</ParamField>

### Binary Version Overrides

The CLI ships with pinned versions of the `pgroll` and `pgstream` binaries. These environment variables allow you to override the pinned version, for example to test a newer release or to pin a specific version in your CI/CD pipeline. The CLI will automatically download the specified version if it is not already present locally.

<ParamField path="XATA_PGROLL_BINARY_VERSION" type="string">
  Override the pinned `pgroll` binary version used by the CLI. If not set, the CLI uses its built-in default. Applies to all `xata roll` subcommands, `xata version`, and `xata upgrade`.
</ParamField>

<ParamField path="XATA_PGSTREAM_BINARY_VERSION" type="string">
  Override the pinned `pgstream` binary version used by the CLI. If not set, the CLI uses its built-in default. Applies to all `xata stream` subcommands, all `xata clone` subcommands, `xata version`, and `xata upgrade`.
</ParamField>

### Clone & Stream

<ParamField path="XATA_CLI_SOURCE_POSTGRES_URL" type="string">
  Source PostgreSQL URL. Can be used instead of the `--source-url` flag. Applies to `xata clone start`, `xata clone stream`, and `xata stream destroy`.
</ParamField>

### Networking

<ParamField path="XATA_PRIVATE_BRANCH_TIMEOUT" type="string">
  Timeout in milliseconds for the private branch reachability check (default: `1000`). Set to `0` to disable the check entirely. Applies to all `xata roll` and `xata clone` subcommands.
</ParamField>

### Examples

```bash theme={null}
# Override the pgroll binary version for a single command
XATA_PGROLL_BINARY_VERSION=0.16.2 xata roll status

# Set environment variables for a CI/CD pipeline
export XATA_API_KEY="your-api-key"
export XATA_ORGANIZATIONID="your-org-id"
export XATA_PROJECTID="your-project-id"
export XATA_BRANCHID="your-branch-id"
xata roll migrate --complete
```