clickhousectl is the CLI for ClickHouse: local and cloud.
With clickhousectl you can:
- Install and manage local ClickHouse versions
- Launch and manage local ClickHouse servers
- Run and manage local Postgres instances
- Execute queries against ClickHouse servers
- Set up ClickHouse Cloud and create cloud-managed ClickHouse clusters
- Create and manage ClickHouse Cloud Postgres services
- Manage ClickHouse Cloud resources
- Create and manage ClickPipes for data ingestion (S3, Kafka, Kinesis, Postgres, MySQL, MongoDB, BigQuery)
- Install the official ClickHouse agent skills into supported coding agents
- Push your local ClickHouse development to cloud
clickhousectl helps humans and AI-agents to develop with ClickHouse.
Installation
Quick install
The install script downloads the correct version for your OS and installs to ~/.local/bin/clickhousectl. A chctl alias is also created automatically for convenience.
Requirements
Local
Installing and managing ClickHouse versions
clickhousectl downloads ClickHouse binaries from builds.clickhouse.com, falling back to packages.clickhouse.com (Linux) or GitHub releases (macOS) when a build isn’t available there.
local use also creates a symlink at ~/.local/bin/clickhouse pointing to the selected version’s binary, so the plain clickhouse command (e.g. clickhouse local, clickhouse client) is on PATH. Pass --no-global to skip. If a regular file already exists at that path it is left alone with a warning. local remove of the active default version also clears the symlink.
ClickHouse binary storage
ClickHouse binaries are stored in a global repository, so they can be used by multiple projects without duplicating storage. Binaries are stored in ~/.clickhouse/:
Initializing a project
init bootstraps your current working directory with a standard folder structure for your ClickHouse and Postgres project files. It is optional; you are welcome to use your own folder structure if preferred.
It creates the following structure:
Running queries
Creating and managing ClickHouse servers
Start and manage ClickHouse server instances. Each server gets its own isolated data directory at .clickhouse/servers/<name>/data/.
Server naming: Without --name, the first server is called “default”. If “default” is already running, a random name is generated (e.g. “bold-crane”). Use --name for stable identities you can start/stop repeatedly.
Ports: Defaults are HTTP 8123 and TCP 9000. If these are already in use, free ports are automatically assigned and shown in the output. Use --http-port and --tcp-port to set explicit ports.
Global server management: Use --global with list, stop, and stop-all to operate across all projects system-wide. server list --global shows all running ClickHouse servers with a Project column indicating which directory each belongs to.
Custom config files for local servers
Local servers start with sensible defaults, but sometimes you need to flip a setting. Drop a config file into ~/.clickhouse/configs/ and apply it by name when starting a server:
The named file is overlaid on top of ClickHouse’s built-in defaults (via config.d), so it only needs to contain the settings you want to change, and there’s no need to reproduce a full config. Files can be .xml, .yaml, or .yml, and you can reference them by name with or without the extension.
Project-local data directory
All server data lives inside .clickhouse/ in your project directory:
Each named server has its own data directory, so servers are fully isolated from each other. Data persists between restarts. Stop and start a server by name to pick up where you left off. Use clickhousectl local server remove <name> to permanently delete a server’s data.
Running local Postgres
In addition to ClickHouse, clickhousectl can run and manage local Postgres instances. Local Postgres is Docker-backed, so Docker must be installed and running. Each instance is identified by its name and major version, so multiple Postgres versions can run side by side with separate data directories.
Authentication
Authenticate to ClickHouse Cloud using API keys (recommended) or OAuth (browser-based).
If you don’t have a ClickHouse Cloud account yet, clickhousectl cloud auth signup opens the sign-up page in your browser.
API key/secret (recommended)
API keys are the recommended way to authenticate, especially when driving the CLI from an AI agent. You can create scoped API keys that grant only the permissions you choose (read-only or read/write), and each key is tied to a single organization. This makes it a safe, least-privilege way to give the CLI access.
Credentials are saved to .clickhouse/credentials.json (project-local).
You can also use environment variables, either exported in your session:
Or placed in a .env file in your current working directory:
Or pass credentials directly via flags on any command:
OAuth login
This opens your browser for authentication via the OAuth device flow. Tokens are saved to .clickhouse/tokens.json (project-local).
OAuth access is currently read-only and grants access to all organizations you belong to. For write access, or to scope the CLI to a single organization, create a scoped API key instead.
Auth status and logout
Credential resolution order: CLI flags > .clickhouse/credentials.json > exported environment variables > .env file > OAuth tokens.
Debugging which credential source was used
Pass --debug to any cloud command to print the resolved credential source (and the API URL) to stderr before the command runs.
Cloud
Manage ClickHouse Cloud services via the API.
Organizations
Services
Service create options
| Option | Description |
|---|
--name | Service name (required) |
--provider | Cloud provider: aws, gcp, azure (default: aws) |
--region | Region (default: us-east-1) |
--min-replica-memory-gb | Min memory per replica in GB (8-356, multiple of 4) |
--max-replica-memory-gb | Max memory per replica in GB (8-356, multiple of 4) |
--num-replicas | Number of replicas (1-20) |
--idle-scaling | Allow scale to zero (default: true) |
--idle-timeout-minutes | Min idle timeout in minutes (>= 5) |
--ip-allow | IP CIDR to allow (repeatable, default: 0.0.0.0/0) |
--backup-id | Backup ID to restore from |
--release-channel | Release channel: slow, default, fast |
--data-warehouse-id | Data warehouse ID (for read replicas) |
--readonly | Make service read-only |
--encryption-key | Customer disk encryption key |
--encryption-role | Role ARN for disk encryption |
--enable-tde | Enable Transparent Data Encryption |
--compliance-type | Compliance: hipaa, pci |
--profile | Instance profile (enterprise) |
--tag | Attach a GA service tag (key or key=value) |
--enable-endpoint / --disable-endpoint | Toggle GA service endpoints (currently mysql) |
--private-preview-terms-checked | Accept private preview terms when required |
--enable-core-dumps | Enable or disable service core dump collection |
Query API auth modes
cloud service query is the canonical way to run SQL against a cloud service over HTTP, with no clickhouse binary and no service password required. It works with both credential modes:
- API key auth (read + write SQL): the first time
cloud service query runs against a service without a stored key, it provisions a Query API endpoint for that service and creates a dedicated API key bound to it. The key (keyId, keySecret, and endpointId) is stored in .clickhouse/credentials.json under service_query_keys.<service-id>. The key is scoped to a single service, so it can read and write (SELECT, INSERT, DDL) against that service but cannot reach any other service in the org. Pass --no-auto-enable to fail instead of provisioning.
- OAuth (
cloud auth login): the query runs as your own identity, just like the web SQL-console. Your SQL permissions on the service are read-only when using OAuth. No Query API key is provisioned or stored. --no-auto-enable has no effect in this mode.
Querying an idled service wakes it automatically in both auth modes (the first query may take a minute). A stopped service is never woken: the query fails with a hint to run cloud service start. Set CLICKHOUSE_CLOUD_QUERY_HOST to override the derived Query API host.
Query endpoint management
Private endpoint management
Backup configuration
Postgres services
clickhousectl can also create and manage ClickHouse Cloud Postgres services, mirroring the ClickHouse service commands above.
Postgres service create options
| Option | Description |
|---|
--name | Service name (required) |
--region | Region, e.g. us-east-1 (required) |
--size | Instance size, e.g. m7i.2xlarge (required) |
--provider | Cloud provider (default: aws) |
--pg-version | Major version: 18, 17 |
--ha-type | High availability: none, async, sync |
--tag | Resource tag key or key=value (repeatable) |
--pg-config-file | Path to a JSON file with a PgConfig object |
--pg-bouncer-config-file | Path to a JSON file with a PgBouncerConfig object |
Backups
ClickPipes
Manage ClickPipes for ingesting data into ClickHouse Cloud from external sources.
Creating ClickPipes
Each source type has its own subcommand under clickpipe create:
Use clickhousectl cloud clickpipe create <source> --help for the full list of options per source type.
Members
Invitations
Keys
Activity
JSON output
Use the --json flag to print JSON-formatted responses.
clickhousectl auto-detects coding-agent contexts (Claude Code, Cursor, Codex, Gemini CLI, Goose, Devin, and any tool that sets the standard AGENT env var) and emits JSON to stdout automatically without setting --json.
Exit codes
Exit codes follow the gh CLI conventions:
| Code | Meaning |
|---|
0 | Success |
1 | Error (anything not classified below) |
2 | Cancelled (user aborted) |
4 | Auth required (no credentials, 401/403, OAuth-only writes) |
Skills
Install the official ClickHouse Agent Skills from ClickHouse/agent-skills.
Non-interactive flags
| Flag | Description |
|---|
--agent <name> | Install Skills for a specific agent (can be repeated) |
--global | Use global scope; if omitted, project scope is used |
--all | Install Skills for all supported agents |
--detected-only | Install Skills for supported agents that were detected on the system |
Self-update
clickhousectl can update itself to the latest release:
The CLI also checks for updates in the background (at most once per 24 hours) and displays a notice when a newer version is available.Last modified on June 23, 2026