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

Every command page opens with an index of the commands on it.

xata init — Link this folder to a project and branch
xata auth — Authenticate with Xata
- xata auth login — Log in to a Xata account
- xata auth logout — Log out of the current account
- xata auth status — Display active account and authentication state
- xata auth switch — Switch to a different Xata account profile
- xata auth list — List all available Xata account profiles
- xata auth access-token — Print the current access token
- xata auth refresh-token — Print the current refresh token
xata organization — Create, list, and manage organizations
- xata organization list — List all organizations
- xata organization describe — Describe an organization
- xata organization create — Create a new organization
- xata organization delete — Delete an organization
- xata organization get — Get a field from an organization description
- xata organization members — Manage organization members
  - xata organization members list — List all members of an organization
  - xata organization members invite — Send an invitation to join an organization
  - xata organization members remove — Remove a member from an organization
- xata organization invitations — Manage organization invitations
  - xata organization invitations list — List all invitations for an organization
  - xata organization invitations get — Get details of a specific invitation
  - xata organization invitations create — Create and send an invitation to join an organization
  - xata organization invitations delete — Delete an invitation
  - xata organization invitations resend — Resend an invitation
xata project — Create, list, and manage projects
- xata project list — List all projects
- xata project describe — Describe a project
- xata project create — Create a new project
- xata project delete — Delete a project
- xata project init — Link this folder to a project and branch
- xata project get — Get a field from a project description
- xata project set — Set a field value for a project
- xata project ip-filter — Manage IP filtering for a project
  - xata project ip-filter list — Show IP filtering status and configured CIDR entries
  - xata project ip-filter enable — Enable IP filtering for a project
  - xata project ip-filter disable — Disable IP filtering for a project
  - xata project ip-filter add — Add a CIDR entry to the IP filter allow list
  - xata project ip-filter remove — Remove a CIDR entry from the IP filter allow list
xata branch — Create, list, and manage Xata branches
- xata branch list — List all branches
- xata branch describe — Describe a branch
- xata branch create — Create a new branch
- xata branch delete — Delete a branch
- xata branch logs — Retrieve the PostgreSQL logs of a branch
- xata branch url — Print URL (connection string) for a branch
- xata branch checkout — Check out a branch in this folder
- xata branch tree — List all branches as a tree
- xata branch get — Get a field from a branch description
- xata branch metrics — Show CPU, memory and disk usage for a branch
- xata branch set — Set a field value for a branch
- xata branch rotate-password — Rotate the database password for a branch
- xata branch wait-ready — Wait for a branch to be ready
- xata branch query-insights — Inspect query statistics and active queries for a branch
  - xata branch query-insights list — List historical query statistics for a branch, by total execution time
  - xata branch query-insights show — Show full query statistics for a query ID
  - xata branch query-insights active — List currently running queries for a branch
  - xata branch query-insights enable — Enable pg_stat_statements for query insights on a branch
  - xata branch query-insights reset — Reset accumulated query statistics for a branch
xata keys — Create, list, and delete API keys
- xata keys user — Manage API keys for the current user
  - xata keys user list — List all API keys of the current user
  - xata keys user create — Create a new API key
  - xata keys user delete — Delete one or more API keys
- xata keys organization — Manage API keys for an organization
  - xata keys organization list — List all API keys for an organization
  - xata keys organization create — Create a new API key
  - xata keys organization delete — Delete one or more API keys
xata roll — Run pgroll to manage PostgreSQL schema migrations
- xata roll baseline — Create a baseline migration for an existing database schema
- xata roll complete — Complete an ongoing migration with the operations present in the given file
- xata roll init — Initialize pgroll in the target database
- xata roll latest — Print the name of the latest schema version or migration
  - xata roll latest migration — Print the latest migration name
  - xata roll latest schema — Print the latest version schema name
- xata roll migrate — Apply outstanding migrations from a directory to a database
- xata roll update — Update outdated migrations in a directory
- xata roll pull — Pull migration history from the target database and write it to disk
- xata roll rollback — Roll back an ongoing migration
- xata roll start — Start a migration for the operations present in the given file
- xata roll status — Show pgroll status
- xata roll convert — Convert SQL statements to a pgroll migration
xata clone — Clone another PostgreSQL database with anonymization
- xata clone start — Snapshot a PostgreSQL database into a Xata branch
- xata clone config — Write the anonymization rules that clone start and stream apply
- xata clone stream — Stream a PostgreSQL database into a Xata branch continuously
xata status — Show the organization, project, and branch this folder uses
xata version — Get the version of the Xata CLI, pgroll and pgstream
xata checkout — Check out a branch in this folder
xata scratch — Run SQL or a Postgres client command against a temporary scratch branch
xata upgrade — Upgrade the Xata CLI
xata completions — Install or uninstall shell completions for the Xata CLI
- xata completions install — Installs bash autocomplete support for xata
- xata completions uninstall — Uninstalls bash autocomplete support for xata

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

​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

Global Flags

Required scopes

Environment Variables

Authentication & Configuration

Project & Branch Configuration

Binary Version Overrides

Clone & Stream

Networking

Examples