ClickHouse CLI - ClickHouse Documentation

The ClickHouse CLI (clickhousectl) is a unified command-line tool for managing ClickHouse Cloud resources and local development with ClickHouse. It also manages ClickHouse Cloud Postgres services.

Installation

curl https://clickhouse.com/cli | sh

A chctl alias is also created automatically for convenience.

Cloud management

Authenticate with ClickHouse Cloud and manage your services directly from the command line.

Authentication

clickhousectl cloud auth

This prompts for your API key and secret, and saves them to .clickhouse/credentials.json (project-local, git-ignored). You can also use environment variables:

export CLICKHOUSE_CLOUD_API_KEY=your-key
export CLICKHOUSE_CLOUD_API_SECRET=your-secret

Services

# List services
clickhousectl cloud service list

# Create a service
clickhousectl cloud service create --name my-service \
  --provider aws \
  --region us-east-1

# Get service details
clickhousectl cloud service get <service-id>

# Scale a service
clickhousectl cloud service scale <service-id> \
  --min-replica-memory-gb 24 \
  --max-replica-memory-gb 48 \
  --num-replicas 3

# Start/stop a service
clickhousectl cloud service start <service-id>
clickhousectl cloud service stop <service-id>

# Delete a service
clickhousectl cloud service delete <service-id>

Postgres services (beta)

Create and manage ClickHouse Cloud Postgres services.

# List Postgres services
clickhousectl cloud postgres list

# Create a Postgres service
clickhousectl cloud postgres create \
  --name my-pg \
  --region us-east-1 \
  --size c6gd.xlarge \
  --pg-version 18

# Get service details
clickhousectl cloud postgres get <pg-id>

# Update a service
clickhousectl cloud postgres update <pg-id> --size c6gd.2xlarge --add-tag env=prod

# Reset the password
clickhousectl cloud postgres reset-password <pg-id> --generate

# Read replicas and point-in-time restore
clickhousectl cloud postgres read-replica create <pg-id> --name replica-1
clickhousectl cloud postgres restore <pg-id> --name restored --restore-target 2026-04-16T12:00:00Z

# Delete a service
clickhousectl cloud postgres delete <pg-id>

Organizations

clickhousectl cloud org list
clickhousectl cloud org get <org-id>

API keys

clickhousectl cloud key list
clickhousectl cloud key create --name ci-key --role-id <role-id>
clickhousectl cloud key delete <key-id>

Members and invitations

clickhousectl cloud member list
clickhousectl cloud invitation create --email dev@example.com --role-id <role-id>

Backups

clickhousectl cloud backup list <service-id>
clickhousectl cloud backup get <service-id> <backup-id>

JSON output

Use the --json flag to get JSON-formatted responses from any cloud command:

clickhousectl cloud --json service list

Local development

The CLI also manages local ClickHouse installations and servers. See the clickhousectl (CLI) page for getting started with local development.

Requirements

macOS (aarch64, x86_64) or Linux (aarch64, x86_64)
Cloud commands require a ClickHouse Cloud API key

​Installation

​Cloud management

​Authentication

​Services

​Postgres services (beta)

​Organizations

​API keys

​Members and invitations

​Backups

​JSON output

​Local development

​Requirements