Skip to main content
clickhousectl (alias chctl) is the official CLI for ClickHouse, from local development to ClickHouse Cloud. It works for people at a terminal, for scripts, and for coding agents. With clickhousectl you can:
  • Install and switch local ClickHouse versions, run isolated local servers, and execute SQL
  • Run Docker-backed Postgres locally
  • Create, configure, scale, back up and query ClickHouse Cloud services
  • Create, monitor, configure and restore ClickHouse Managed Postgres services
  • Create and operate ClickPipes from object storage, Kafka, Kinesis, Pub/Sub, Postgres, MySQL, MongoDB and BigQuery
  • Manage sources, dashboards, alerts, webhooks, saved searches and roles on a Self-managed ClickHouse Observability service
  • Develop executable UDFs locally and deploy them to ClickHouse Cloud
  • Manage organization members, invitations, API keys and roles
  • Install the official ClickHouse agent skills into coding agents
This page shows representative examples. clickhousectl <command> --help is the authoritative reference for every command and flag. Most commands’ help ends with a CONTEXT FOR AGENTS block; for Cloud commands it also lists the API-key permissions they need. For task walkthroughs, follow the guide links in each section. For a Cloud-focused overview, see ClickHouse CLI.

Installation

clickhousectl runs on macOS and Linux, on ARM64 and x86_64.
The script installs ~/.local/bin/clickhousectl and creates the chctl alias. Make sure ~/.local/bin is on your PATH. You can also install it with a package manager: Only the install script and npm create the chctl alias. To update an existing install, run clickhousectl update (see Self-update); for npm, uv, pipx and pip installs it prints the package manager’s upgrade command instead.

Shell completions

To complete commands, flags, local server names and installed versions with Tab, add one line to your shell startup file. It registers both clickhousectl and chctl:
Completion runs the installed CLI on each Tab press, so it stays current after update.

Requirements

  • Docker, for local Postgres only
  • For Cloud commands, a ClickHouse Cloud account. Read commands work with browser OAuth (cloud auth login). Creating or changing resources needs an API key. See Authentication.

Local

A directory containing .clickhouse/ is a project root, as a directory containing .git/ is for Git. Local commands use the nearest one at or above the current directory, so they work from any subdirectory of the project; outside any project they use the current directory. Set CLICKHOUSECTL_PROJECT_DIR to name the project root explicitly, for example in a script or CI job. Each project keeps its server data in .clickhouse/, while ClickHouse binaries are shared globally in ~/.clickhouse/. See the local development guide for the full workflow.

Install and select versions

local use installs the version if needed, sets it as the default for future server starts, and symlinks it to ~/.local/bin/clickhouse, so clickhouse client and clickhouse local are on your PATH. Pass --no-global to skip the symlink. If a regular file already exists at that path, it is left alone. local remove refuses the default version or one used by a running server in any project. --force stops those servers and removes the version, clearing the default and the symlink. local install --binary <path> copies a ClickHouse binary you built and installs it under the version it reports, so you can select it with local use or --version like any other install. A rebuild usually reports the same version, so pass --force to replace the installed copy.

Initialize a project

init marks the current directory (or CLICKHOUSECTL_PROJECT_DIR, when set) as the project root. It creates a git-ignored .clickhouse/ directory for runtime data, plus scaffolds you can commit: clickhouse/ (tables/, materialized_views/, queries/, seed/, udfs/, config.d/) and postgres/ (tables/, views/, functions/, queries/, seed/). Re-running it only creates what is missing, so run it once after cloning a project. A server start without init still works and creates .clickhouse/ in the current directory.

Run local servers

local ch is short for local clickhouse, and the earlier name local server still works as an alias. Each named server has its own data in .clickhouse/servers/<name>/data/, and stopping a server keeps it for the next start. A start without a name uses default; if default is already running, a new name is generated. Default ports are HTTP 8123 and TCP 9000, with free ports assigned when those are taken. Commands that act on an existing server (stop, client, dotenv, local client and local udf --server) select default when you omit the name, else the project’s only server of that engine. With several servers and none named default, they fail with server_selection_required and list the names. remove never guesses: without a name it removes only default. Scripts should pass names explicitly. --version chooses a version for that start without changing the default. A bare start with no version and no default installs latest without making it the default; run local use latest first to make it the default.

Run SQL with the local client

local client connects to a named server with the same ClickHouse binary that runs it; without a name, it follows the selection rule above. Arguments after -- go to clickhouse client unchanged. Output and exit status come from clickhouse client, even in JSON mode, so set the SQL output format yourself when scripting.

Custom server configuration

Partial XML or YAML configs override the built-in defaults from three locations:
Each start merges them in table order, later files winning, so a file only needs the settings you change. Edits and a dropped --config take effect on the next start. Managed data paths and ports always win over config values.

Write connection details to a dotenv file

dotenv reads the running server’s actual ports and writes CLICKHOUSE_HOST, CLICKHOUSE_PORT and CLICKHOUSE_HTTP_PORT, plus the user, password and database when you pass them. Other lines in an existing file are kept. Load the file with your application’s dotenv loader; never eval the printed preview.

Local Postgres

Local Postgres runs in Docker, so Docker must be running. Postgres 17 and 18 are supported, including image tags such as 18-alpine; new instances default to 18.
local pg is short for local postgres. An instance is identified by its name and major version. Resuming a stopped instance reuses its original port, user, password and database, so creation flags have no effect on a resume. A random password is generated unless you pass one. .env.local contains the password, so keep it out of version control.

Local UDFs

local udf deploys executable UDFs from clickhouse/udfs/<name>/ to a local server. cloud udf uploads the same directory to Cloud (see UDFs in Cloud).
Every command except init takes --server <name>; without it, the selection rule picks the server. deploy validates udf.json the same way Cloud does. On a running server, it reloads functions and confirms the function loaded. The native runtime deploys locally only on Linux amd64 or arm64 hosts. See the user-defined functions guide.

Authentication

Cloud commands use one of two credential types: If you don’t have a ClickHouse Cloud account yet, clickhousectl cloud auth signup opens the sign-up page in your browser.

OAuth login

This opens your browser for the OAuth device flow. Tokens are saved globally to ~/.clickhouse/tokens.json and refreshed automatically.
OAuth is read-only. To create or change resources, log in with an API key.

API key

Create an API key with the roles your commands need, then save it. The interactive prompt keeps the secret out of your shell history:
Login verifies the key and prints the identity it belongs to. A key the API rejects is not saved, and the command exits 4. If the API is unreachable, the key is saved with a warning. For CI and other automation, inject the key through your secret manager instead of saving it:
For development, the CLI also reads these variables from a .env file in the current directory or, when that has none, in the project root. Keep .env out of version control.

Check and clear credentials

whoami works with either credential type and exits 4 if the credentials are rejected. status can exit 0 even when no credentials work, so use whoami to test access. Logout does not unset environment variables or edit .env.

Credential precedence

The first available source wins:
  1. --api-key and --api-secret flags
  2. .clickhouse/credentials.json in the project root
  3. Exported environment variables
  4. Variables from .env in the current directory, else in the project root
  5. Global OAuth tokens
Pass --debug to any cloud command to print the selected credential source and API URL to stderr:

Select an organization

Organization-scoped commands pick the organization automatically only when your credentials reach exactly one. Otherwise pass --org-id, or --org-name with the exact name; without either, the command exits 2 and lists each organization’s ID and name:
Most resource commands take a positional ID or an exact --name. See authentication and access for permissions, restricted keys and logout cleanup.

Cloud

Cloud commands call the ClickHouse Cloud API. Create and update requests return once the API accepts them, so poll get until a resource reaches the state you need.

Services

cloud clickhouse manages ClickHouse Cloud services. cloud ch is short for it, and the earlier name cloud service still works as an alias.
Save the initial password shown at creation; it is returned only once. With --dotenv [file] (default .env), it is written only to that file, not to the terminal or JSON output. Creation returns before provisioning finishes, so repeat get until the state is running. Omitting --ip-allow allows all IPs (0.0.0.0/0). Entries accept IP_OR_CIDR=DESCRIPTION. --region accepts any region ID, including private regions, and Cloud validates it. Restore a backup into a new service with --backup-id, or place a service in BYOC infrastructure with --byoc-id. Connect to a running service:
client opens clickhouse client over the native TLS protocol and signs you in through a browser as your Cloud user, so no service password is needed. It uses an installed ClickHouse 25.12 or newer (clickhousectl local install latest) and needs a person at the browser, so use query in CI and agents. dotenv writes CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_HTTP_PORT, CLICKHOUSE_USER and CLICKHOUSE_SECURE, replacing only those keys, so a password written by create --dotenv is kept. Update, scale and configure a service:
Memory per replica is a multiple of 4 GB, at most 120 GB on unpaid and 356 GB on paid services, with up to 50 replicas. Organization and warehouse limits can lower these. Horizontal autoscaling needs its organization feature. scale --profile changes the instance profile on Enterprise and BYOC organizations. update changes only the flags you pass. Deletion protection (create --deletion-protection, or update --deletion-protection true|false) makes delete refuse the service with error code deletion_protected, even with --force; turn it off before deleting. Other service command groups are settings (list, get, schema, set, unset), scaling-schedule, upgrade-window, replica-aware-routing (Beta), jwt-provider (Beta, Enterprise tier), snapshot (Beta), private-endpoint, query-endpoint, backup-config and prometheus. See create and operate a Cloud service.

Query API

cloud clickhouse query runs one SQL statement over HTTP, with no local clickhouse binary and no service password:
  • OAuth runs the query as your identity, with read-only SQL access. Nothing is bound to the service.
  • API key: the query always uses the active API key. If needed, clickhousectl adds that key to the service’s Query API endpoint, creating the endpoint with sql_console_admin roles if none exists. Existing roles, origins and other key bindings are kept, and no new key is created. Pass --no-auto-enable to fail instead.
Binding is a write, so a read-only API key cannot bind itself: the query exits 1 with query_key_bind_forbidden and nothing changes. Bind it once with a key that has write access, using query-endpoint create <service-id> --role <role> --open-api-key <key-id> (plus --allowed-origins '*' when the service has no endpoint yet). The Query API accepts one statement per request. It can time out after about 30 seconds while the SQL keeps running, so check the result before retrying a write. Use cloud clickhouse client for multi-statement scripts, bulk loads and long queries. The service IP allowlist restricts direct connections, not the proxied Query API route. Querying an idle service wakes it; a stopped service must be started with cloud clickhouse start. Manage the service’s Query API endpoint, named SQL endpoints and saved queries:
query-endpoint create replaces the roles for every key bound to the endpoint. See SQL and Query API behavior.

Managed Postgres

cloud postgres (alias cloud pg) manages ClickHouse Managed Postgres. GCP is in private preview.
AWS sizes include m6gd.large, c6gd.xlarge and r6gd.xlarge. On GCP, pass --provider gcp with a GCP region and a size such as c4-standard-lssd-4. Save the password and connection string from create. Later get responses never return credentials, and reset-password is the only way to get new ones. Connect with psql using sslmode=verify-full and the CA file. Omitting access flags on create allows all IPv4 and IPv6 addresses on Postgres (5432) and PgBouncer (6432). Pass one --ip-allow IP_OR_CIDR:PORTS[=DESCRIPTION] per rule, or --block-public-access for no rules. Once you pass a rule, only the listed rules apply. --standby-count sets the number of hot standbys on create or update: --ha-type none takes 0, async takes 1, and sync takes 1 or 2. With deletion protection on, the API rejects delete until you set --deletion-protection false, in organizations that have the feature. For private connectivity on AWS, private-endpoint (create, get, update, delete) manages a PrivateLink endpoint service (Beta); approve each VPC endpoint with private-endpoint update --add-vpc-endpoint before it can connect. Monitor and recover:
cloud postgres query accepts only OAuth, so it fails while a higher-priority API key source is active. metrics, slow-queries and prometheus cover monitoring; logs, metrics, slow-queries and backup list also accept --name in place of the ID. restore copies the source’s current IPv4 access rules onto the restored service unless you pass --ip-allow or --block-public-access. Restores and replicas return without a password. promote and switchover return once accepted; after a promote, poll postgres get --json until the replica reports isPrimary: true. See the Managed Postgres guide.

ClickPipes

cloud clickpipe ingests data from object storage, Kafka, Kinesis, Pub/Sub, Postgres, MySQL, MongoDB and BigQuery. Creation and schema discovery need an API key and a running destination service. Each source has its own clickpipe create <source> subcommand; run it with --help for its flags. Load files from S3 with an IAM role. Discover the schema first, review it, then create the pipe from the saved discovery output:
--columns-from turns the discovered fields into destination columns, so edit the file first to drop fields you don’t want. Object storage, Kafka, Kinesis and Pub/Sub creates need --columns-from, at least one --column name:type, or both; --column adds columns to those from the file. Replicate Postgres with CDC. TLS is verified by default; for a Managed Postgres source, export its CA and pass it:
--table-mapping creates ReplacingMergeTree tables, so read current state with FINAL WHERE _peerdb_is_deleted = 0. Postgres and MySQL creates take --use-json-native-format true to store JSON columns as native ClickHouse JSON instead of String (ClickHouse 25.3+, with the feature enabled for the organization). A Kafka pipe follows the same pattern as object storage: run clickpipe schema-discover kafka with the same source flags, then pass the columns with --column or --columns-from:
BigQuery pipes run a snapshot by default. For CDC, pass --replication-mode cdc, a --replication-method, and a per-table watermark column or events function in --table-mapping-json; schedule syncs with --sync-cron or --sync-interval-seconds. Operate existing pipes:
CDC pipes must be Paused before update: stop the pipe, poll get until it is Paused, then update it. The service can resume the pipe as part of the update, so run start only if get still shows Paused. --start-paused is available for object storage, Kafka, Kinesis and Pub/Sub. Other command groups are cdc-scaling, context get (GCP workload-identity readiness and principal) and reverse-private-endpoint. See the ClickPipes guide and the ClickPipe configuration reference.

ClickStack

cloud clickstack manages sources, dashboards, alerts, webhooks, saved searches and roles on an existing Self-managed ClickHouse Observability service. Resources are JSON files (--file, or - for stdin). Reads support OAuth; writes need an API key.
Every ClickStack update replaces the complete resource. Save the current state with get --json and send the full definition, not only the changed fields. See the ClickStack guide.

UDFs in Cloud

cloud udf manages organization-scoped executable UDFs, their versions and their service attachments. deploy uploads the directory you tested with local udf, waits for the build, attaches that version and waits until it is deployed:
To run each step yourself, use udf create, udf version create, udf attach (with --wake for an idle service), udf detach and udf delete. These return once accepted; poll udf get and udf attachment get. Reads support OAuth; writes need an API key. See the user-defined functions guide.

Organizations and access

cloud org subcommands take --org-id, never a positional ID. org usage covers at most 31 days. org also has quota, balance, notification-types, role (custom organization roles), preview (list and toggle preview features, Beta) and byoc (BYOC infrastructure, including byoc access to control when ClickHouse personnel may access it, Beta). Notifications are Beta. Manage members, invitations and API keys:
member notification-settings (Beta) lists and updates a member’s own notification overrides. Omitting --ip-allow on key create denies all network access, unlike service creation. The secret is shown only once. key list returns one page unless you pass --all. On key update, omitted flags keep their settings, while --clear-expiry, --clear-roles and --clear-ip-allow remove them.

Backups

Restoring always creates a new service. cloud backup bucket (get, create, update, delete) configures a bring-your-own backup bucket from a provider-specific JSON file. See the backup section of the Cloud service guide.

JSON output

Commands that return structured data accept --json, including local, Cloud, skills, update and telemetry commands:
When the CLI detects a coding agent (such as Claude Code, Cursor, Codex, Gemini CLI, Goose or Devin, or any tool that sets AI_AGENT), it selects JSON automatically. SQL and native clients keep their own formats: cloud clickhouse query returns JSONEachRow in JSON mode, and local client output is always native. Scripts that parse query output should pass --format explicitly. To keep human output under a detected agent, set CLICKHOUSECTL_AUTO_JSON=0; an explicit --json still selects JSON. Asynchronous Cloud commands, such as clickhouse create, postgres create and clickpipe start, add a next object to their JSON output naming the poll to run: command (with resolved IDs and --org-id), the field to watch, the until values that mean done, fail_on values and a suggested interval_seconds. The command still returns as soon as the API accepts the request. In JSON mode, runtime errors go to stderr as an object with a stable code and a message:
Branch on error.code, not on the message. Usage errors stay as text, with exit code 2, and nothing is sent. See automation and output contracts for output shapes and error codes.

Exit codes

local client, local postgres client and other native-client handoffs pass the client’s own exit status through.

Agent skills

Install the official ClickHouse agent skills into your coding agents:
Skills install into the current project by default, or into your home directory with --global. The shared .agents/skills/ directory is always included. Without a terminal, you must pass --agent, --all or --detected-only. Run clickhousectl skills --help for the supported agent names.

Search and feedback

search <words> matches command names, descriptions, flags and agent context, and lists the best-matching commands (default 5). A search with no match exits 0 with no results. feedback sends a short message (at most 500 characters) to the clickhousectl team, with no prompt or confirmation. Use it to say what the CLI could not do or what you expected. Put options such as --json before the message, and don’t include credentials, SQL, hostnames or personal data. With Cloud credentials, the message carries the IDs of the organizations they belong to. See what feedback sends.

Self-update

update replaces installs from the install script, a download or Cargo. For npm, uv, pipx and pip installs, it exits 1 and prints the package manager’s upgrade command to run instead. The CLI also checks for updates in the background, at most once every 24 hours (a failed check is retried after an hour), and prints a notice when a newer version is available. Set CLICKHOUSECTL_NO_UPDATE_CHECK=1 to turn off the check and the notice.

Telemetry

clickhousectl collects anonymous usage data to guide development. The first run shows a notice and sends nothing; collection starts on a following run unless you disable it. Each event contains:
  • The command path and the names of explicitly passed flags and arguments, never their values
  • The outcome and exit code
  • For a mistyped command, the command or flag name the CLI suggested, never what you typed
  • For runtime failures, bounded categories: failure stage and kind, an allowlisted HTTP status, and retry, provisioning-state and duration categories
  • The CLI version, OS and architecture, whether it runs in CI, and the detected coding agent
Argument values, SQL, credentials, resource identifiers, arguments after -- and error messages are never recorded. There is no installation or device ID. To opt out:
Set CHCTL_TELEMETRY_DEBUG=1 to print the payload to stderr without sending anything. Opting out doesn’t block feedback, which sends only when you run it. See telemetry details.