Skip to main content
The ClickHouse CLI (clickhousectl, alias chctl) manages ClickHouse Cloud from a terminal, a script or a coding agent. This page covers the Cloud side of the CLI. For every command group, local development and the full behaviour, see the clickhousectl reference.

​
What you can manage

The clickhousectl cloud commands cover:
  • Services: create, scale, start and stop ClickHouse Cloud services, and run SQL against them over the Query API.
  • Managed Postgres (Beta): create Postgres services, read replicas and point-in-time restores, and change their configuration.
  • ClickPipes: ingest from object storage, Kafka, Kinesis, Pub/Sub, Postgres, MySQL, MongoDB and BigQuery.
  • ClickStack: manage sources, dashboards, alerts, webhooks, saved searches and roles on a Managed ClickStack service.
  • User-defined functions: test executable UDFs locally, then deploy them to a Cloud service.
  • Backups: list backups, change the backup schedule and restore a backup into a new service.
  • Organization access: organizations, members, invitations, API keys and the activity log.
Run clickhousectl cloud <command> --help for the flags of any command and the API key permissions it needs.

​
Installation

The script installs ~/.local/bin/clickhousectl and a chctl alias. Make sure ~/.local/bin is on your PATH. For npm, pip, uv and the other install methods, see Installation.

​
Authentication

Browser OAuth login is read-only. Creating or changing resources needs an API key with a role that allows the change.
Login verifies the credentials and prints the identity. Check it any time with clickhousectl cloud auth whoami. If you belong to several organizations, add --org-id <org-id> (or --org-name <name>) to Cloud commands. In CI, set CLICKHOUSE_CLOUD_API_KEY and CLICKHOUSE_CLOUD_API_SECRET instead of logging in. See Authentication for credential precedence and logout.

​
Examples

​
Create and query a service

Creation returns before the service is running. Poll clickhousectl cloud service get "$CH_ID" until state is running. On the first API-key query, clickhousectl adds your API key to the service’s Query API endpoint, creating the endpoint if needed; no new key is created. Pass --no-auto-enable to fail instead. With OAuth, service query runs read-only SELECT statements. The Query API times out after about 30 seconds, so use clickhouse client for long queries and bulk loads.

​
Create a Managed Postgres service

Only create returns the password and connection string, so save them. Omitting --ip-allow opens ports 5432 and 6432 to all addresses. Wait for state to be running, then connect with psql using the CA certificate.

​
Inspect ClickPipes, ClickStack and backups

These read commands work with OAuth. Creating a ClickPipe or changing a ClickStack resource needs an API key; see the repository guides below.

​
Deploy a user-defined function

Test the function first with clickhousectl local udf deploy my_udf against a local server.

​
JSON output and coding agents

Cloud commands accept --json, and the CLI selects JSON automatically when it detects a coding agent. cloud service query then defaults to JSONEachRow, so scripts that parse its output should pass --format, for example --format TabSeparated. See JSON output and Exit codes. Install the ClickHouse agent skills with clickhousectl skills.

​
Learn more