Skip to main content
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

# Install using the official install script
curl -fsSL https://xata.io/install.sh | bash
The CLI binary will be installed to ~/.config/xata/bin/. Make sure this directory is in your PATH.

​
Installation (Windows)

# Install using npm
powershell -c "irm https://xata.io/install.ps1 | iex"
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.

​
Basic Usage

xata [command] [subcommand] [options]

​
Available Commands

​
Authentication

​
Organization Management

​
Project Management

​
Branch Management

​
API Key Management

​
Schema Migrations

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

​
Database Synchronization

  • clone start - Clone a PostgreSQL database with anonymization
  • clone config - Configure transforms for the clone command
  • clone stream - Start a continuous data stream using logical replication

​
Utility Commands

​
Global Flags

​
-h, --help
boolean
Print help information and exit
​
-v, --version
boolean
Print version information and exit
​
--json
boolean
Output in JSON format (where applicable)

​
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.
​
XATA_API_KEY
string
API key used to authenticate with Xata. In CI/CD environments, set this as a secret. Applies to all commands that require authentication.
​
XATA_API_ENVIRONMENT
string
Select the Xata API environment. Typically not needed unless instructed by Xata support. Applies to all commands.
​
XATA_CONFIG_DIR
string
Override the directory where the CLI stores its configuration files. Applies to all commands.

​
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.
​
XATA_ORGANIZATIONID
string
Your Xata organization ID.
​
XATA_PROJECTID
string
Your Xata project ID.
​
XATA_BRANCHID
string
The ID of the target branch.
​
XATA_BRANCHNAME
string
The name of the target branch.
​
XATA_DATABASENAME
string
The database name (default: xata).

​
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.
​
XATA_PGROLL_BINARY_VERSION
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.
​
XATA_PGSTREAM_BINARY_VERSION
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.

​
Clone & Stream

​
XATA_CLI_SOURCE_POSTGRES_URL
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.

​
Networking

​
XATA_PRIVATE_BRANCH_TIMEOUT
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.

​
Examples

# 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