clickhousectl (chctl) is the official CLI for ClickHouse, from local development to ClickHouse Cloud.

What can the CLI do?

• ClickHouse is the open-source, column-oriented SQL database for analytics. Install and switch local versions, run isolated servers, and execute SQL.
• ClickHouse Cloud runs ClickHouse as a managed service on AWS, GCP, and Azure. Create, configure, scale, back up, and query services from the terminal.
• ClickHouse Managed Postgres runs PostgreSQL for transactional applications, with ClickHouse integration for analytics. Use Docker-backed Postgres locally, then create, monitor, configure, and restore managed services in Cloud.
• ClickPipes ingests data into ClickHouse Cloud from object storage, streams, and databases through change data capture. Create, inspect, update, scale, and troubleshoot pipelines.
• ClickStack combines ClickHouse, OpenTelemetry, and the HyperDX UI for observability. Manage sources, roles, saved searches, dashboards, alerts, and webhooks for an existing Managed ClickStack service.

The CLI also manages organization access and installs official ClickHouse skills for coding agents.

Install

Supports macOS and Linux on Apple Silicon/ARM64 and x86_64.

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

The script installs to ~/.local/bin/clickhousectl and creates the chctl alias. Ensure ~/.local/bin is on your PATH.

Other installation options:

Check for or install a CLI update:

clickhousectl update --check
clickhousectl update

Start locally

Use the latest channel for the rolling master build of ClickHouse. A bare server start installs latest if no version or default is available.

clickhousectl local server start dev --version latest
clickhousectl local client dev --query "SELECT version()"
clickhousectl local server stop dev

Run these from the same project directory. Each named server has isolated data under .clickhouse/; stopping preserves it for the next start.

For local Postgres, start Docker first:

clickhousectl local postgres start dev
clickhousectl local postgres client dev --query "SELECT version()"
clickhousectl local postgres stop dev

Continue with local development for SQL files, version selection, configuration, and cleanup.

Connect to ClickHouse Cloud

Create a ClickHouse Cloud account if needed to get $300 in free trial credits, then sign in:

clickhousectl cloud auth signup
clickhousectl cloud auth login

Browser OAuth is read-only. Creating or changing resources requires an API key with the appropriate roles. Use either an interactive prompt or a .env file to supply your API key.

To save the key interactively without putting its secret in shell history:

clickhousectl cloud auth login --interactive

Alternatively, create a .env file in your project with your keys:

CLICKHOUSE_CLOUD_API_KEY=your-api-key
CLICKHOUSE_CLOUD_API_SECRET=your-api-secret

Keep .env out of version control by adding it to .gitignore.

OAuth tokens are global (~/.clickhouse/tokens.json); saved API keys are project-local (.clickhouse/credentials.json). For CI, inject CLICKHOUSE_CLOUD_API_KEY and CLICKHOUSE_CLOUD_API_SECRET through your secret manager. See authentication and permissions for precedence, organization selection, and logout.

Create and query ClickHouse

Create a ClickHouse Cloud service. Save the initial password shown at creation; it is only returned once.

# Output will contain the service ID
clickhousectl cloud service create --name analytics \
  --provider aws --region us-east-1

Creation returns before provisioning finishes. Queries use OAuth for read-only SQL or an API key for permitted reads and writes. On first use, API-key queries can bind the caller's key to the service's Query API endpoint; use --no-auto-enable to require an existing binding.

The Query API may time out while SQL continues running. Check the outcome before retrying a write. Use a native client for long queries and bulk loads. Named endpoint lists return one page; pass pagination.nextCursor from JSON output to query-api-endpoint list --cursor to continue. See create and operate a Cloud service and SQL and Query API behavior.

Create ClickHouse Managed Postgres

clickhousectl cloud postgres create --name app-db \
  --provider aws --region us-east-1 --size c6gd.xlarge --pg-version 18
clickhousectl cloud postgres get <postgres-id>
clickhousectl cloud postgres certs get <postgres-id> --output ca.pem

Save any initial password and connection string, wait for state=running, then connect with psql using verified TLS. The ClickHouse Managed Postgres guide covers that flow, configuration changes, read-only OAuth queries, and recovery. ClickHouse Managed Postgres commands are beta.

Ingest with ClickPipes

Use ClickPipes to replicate database changes or load files into ClickHouse Cloud. Both examples require API-key authentication and a running ClickHouse destination.

Replicate ClickHouse Managed Postgres into ClickHouse

Start with the analytics ClickHouse service and app-db ClickHouse Managed Postgres service created above. Use their returned IDs below, and wait until both report state=running:

clickhousectl cloud service get <service-id>
clickhousectl cloud postgres get <postgres-id>
clickhousectl cloud postgres certs get <postgres-id> --output ca.pem

Set POSTGRES_HOST, POSTGRES_USERNAME, and POSTGRES_PASSWORD from the ClickHouse Managed Postgres connection details saved at creation. Use the direct Postgres endpoint, not PgBouncer. For this quickstart, use the initial database user; ClickHouse Managed Postgres already has logical replication enabled.

Create a sample table and a publication using psql. The cloud postgres query command only supports read-only SQL through OAuth, so it cannot run these setup statements:

PGPASSWORD="$POSTGRES_PASSWORD" psql \
  "host=$POSTGRES_HOST port=5432 dbname=postgres user=$POSTGRES_USERNAME sslmode=verify-full sslrootcert=ca.pem" \
  -v ON_ERROR_STOP=1 <<'SQL'
CREATE TABLE public.orders (id bigint PRIMARY KEY, status text NOT NULL);
INSERT INTO public.orders VALUES (1, 'new');
CREATE PUBLICATION clickpipes_demo FOR TABLE public.orders;
SQL

Create a ClickPipe to copy the existing rows and continuously replicate inserts, updates, and deletes. The CA file keeps certificate verification enabled:

clickhousectl cloud clickpipe create postgres <service-id> \
  --name orders-cdc --host "$POSTGRES_HOST" --pg-database postgres \
  --username "$POSTGRES_USERNAME" --password "$POSTGRES_PASSWORD" \
  --ca-certificate ca.pem --publication-name clickpipes_demo \
  --replication-mode cdc --destination-database default \
  --table-mapping public.orders:orders

Use the returned ClickPipe ID to check its state, then query the current rows in ClickHouse after the initial load:

clickhousectl cloud clickpipe get <service-id> <clickpipe-id>
clickhousectl cloud service query <service-id> \
  --query "SELECT id, status FROM default.orders FINAL WHERE _peerdb_is_deleted = 0"

To check ongoing CDC, run UPDATE public.orders SET status = 'paid' WHERE id = 1; in Postgres and repeat the ClickHouse query. Replication is asynchronous, so allow time for the change to arrive.

Load files from S3

For a private bucket, set S3_IAM_ROLE_ARN to a role configured to let ClickPipes read your objects. Replace the example URL, discover the schema, then choose the columns to ingest. This example expects event_id and event_type fields in JSONEachRow files:

S3_URL='https://example-bucket.s3.amazonaws.com/events/**'
clickhousectl cloud clickpipe schema-discover object-storage <service-id> \
  --storage-type s3 --source-url "$S3_URL" --format JSONEachRow \
  --iam-role "$S3_IAM_ROLE_ARN"

clickhousectl cloud clickpipe create object-storage <service-id> \
  --name s3-events --storage-type s3 --source-url "$S3_URL" \
  --format JSONEachRow --iam-role "$S3_IAM_ROLE_ARN" \
  --database default --table s3_events \
  --column 'event_id:Int64' --column 'event_type:String'

This starts a one-time load of the matching objects. Check the returned ClickPipe ID and verify the loaded data:

clickhousectl cloud clickpipe get <service-id> <clickpipe-id>
clickhousectl cloud service query <service-id> --query "SELECT count() FROM default.s3_events"

See the ClickPipes guide for source permissions and networking, other sources, continuous S3 ingestion, monitoring, and safe updates.

Configure ClickStack

Use an existing Managed ClickStack service and a complete dashboard definition:

clickhousectl cloud clickstack source list <service-id>
clickhousectl cloud clickstack dashboard validate <service-id> --file dashboard.json
clickhousectl cloud clickstack dashboard create <service-id> --file dashboard.json

All ClickStack updates replace the complete resource. The ClickStack guide includes a dashboard definition and a review-before-replace workflow.

Use with coding agents and scripts

Install official ClickHouse skills into the current project, or add --global for your home directory:

clickhousectl skills --agent claude --agent codex

The common .agents/skills/ directory is always included. Run skills without flags for interactive selection; unattended installs require --agent, --all, or --detected-only.

Structured commands support --json and select it automatically for detected coding agents. SQL and native clients retain command-specific formats. Always check the exit status and distinguish an accepted request from a completed operation. See automation and output contracts.

Documentation

Telemetry

The CLI collects anonymous command usage and bounded failure categories, never argument values, SQL, credentials, or an installation/device ID. The first-run notice sends nothing; collection starts on a following run unless disabled.

clickhousectl telemetry disable
clickhousectl telemetry status

DO_NOT_TRACK=1 also disables collection. See telemetry details and controls.

Contribute

See CONTRIBUTING.md for setup, checks, and documentation placement, and CLI development for the code layout and test workflows.