Command-line Interface

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 (Docker)

# Pull docker image
docker pull ghcr.io/xataio/xata:latest-pg18

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

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]

Container image

docker run -e XATA_API_KEY=yourkey ghcr.io/xataio/xata:latest-pg18 [command] [subcommand] [options]

Available Commands

Authentication

auth login - Log in to your Xata account
auth logout - Log out of the current account
auth status - Display active account and authentication state
auth switch - Switch to a different Xata account profile
auth access-token - Print the current access token
auth refresh-token - Print the current refresh token

Organization Management

organization list - List all organizations
organization describe - Describe an organization
organization create - Create a new organization
organization delete - Delete an organization
organization get - Get a field from an organization description

Project Management

init - Link a project to the current folder
project list - List all projects
project describe - Describe a project
project create - Create a new project
project delete - Delete a project
project init - Link a project to the folder
project get - Get a field from a project description
project set - Set a field value for a project

Branch Management

branch list - List all branches
branch describe - Describe a branch
branch create - Create a new branch
branch delete - Delete a branch
branch url - Print URL (connection string) for a branch
branch checkout - Checkout a branch
branch tree - List all branches as a tree
branch get - Get a field from a branch description
branch set - Set a field value for a branch
branch wait-ready - Wait for a branch to be ready
branch metrics - Show CPU, memory, disk, and other instance metrics for a branch
branch logs - Show PostgreSQL server logs for a branch
branch query-insights - Show slow queries, query statistics, and currently running queries for a branch
branch rotate-password - Rotate the database password for a branch

API Key Management

keys user list - List API keys for the current user
keys user create - Create an API key for the current user
keys user delete - Delete an API key for the current user
keys organization list - List API keys for an organization
keys organization create - Create an API key for an organization
keys organization delete - Delete an API key for an organization

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

status - Get the status of the Xata CLI
version - Get the version of the Xata CLI and pgroll
checkout - Checkout a branch
upgrade - Upgrade the Xata CLI
completions install - Install shell completions
completions uninstall - Uninstall shell completions

Global Flags

boolean

Print help information and exit

boolean

Print version information and exit

boolean

Output in JSON format (where applicable)

Required scopes

Most commands work with a key scoped to branch:read. These need more:

Command	Scope	Why
`branch logs`	`logs:read`	Reads server logs through the Xata API
`branch url`	`credentials:read`	Reads connection details from the credentials endpoint
`branch rotate-password`	`credentials:read`	Reads the current username before rotating
`branch query-insights`	`credentials:read`	Opens a direct PostgreSQL connection to the branch
`roll url`	`credentials:read`	Reads connection details from the credentials endpoint
`project init`	`credentials:read`	Reads connection details from the credentials endpoint
`clone start`, `stream`	`credentials:read`	Connects to the source and target branches

A key that only has branch:read returns a 401 on the commands above. Scopes are set when you create the key, so a key created before a scope existed does not have it. See API keys for how to create and scope one.

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.

string

API key used to authenticate with Xata. In CI/CD environments, set this as a secret. Applies to all commands that require authentication.

string

Select the Xata API environment. Typically not needed unless instructed by Xata support. Applies to all commands.

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.

Earlier CLI versions used names without an underscore between words (for example XATA_ORGANIZATIONID, XATA_PROJECTID, XATA_BRANCHID, XATA_BRANCHNAME, XATA_DATABASENAME). These legacy names are still supported, but the snake_case names below are preferred and take precedence when both are set.

string

Your Xata organization ID.

string

Your Xata project ID.

string

The ID of the target branch.

string

The name of the target branch.

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.

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.

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

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

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_ORGANIZATION_ID="your-org-id"
export XATA_PROJECT_ID="your-project-id"
export XATA_BRANCH_ID="your-branch-id"
xata roll migrate --complete

​Installation

​Installation (Docker)

​Installation (Windows)

​Basic Usage

​Container image

​Available Commands

​Authentication

​Organization Management

​Project Management

​Branch Management

​API Key Management

​Schema Migrations

​Database Synchronization

​Utility Commands

​Global Flags

​Required scopes

​Environment Variables

​Authentication & Configuration

​Project & Branch Configuration

​Binary Version Overrides

​Clone & Stream

​Networking

​Examples

Installation

Installation (Docker)

Installation (Windows)

Basic Usage

Container image

Available Commands

Authentication

Organization Management

Project Management

Branch Management

API Key Management

Schema Migrations

Database Synchronization

Utility Commands

Global Flags

Required scopes

Environment Variables

Authentication & Configuration

Project & Branch Configuration

Binary Version Overrides

Clone & Stream

Networking

Examples