> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# clickhousectl

> Reference for clickhousectl, the CLI for ClickHouse and Postgres, from local development to ClickHouse Cloud

`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](https://clickhouse.com/docs/products/managed-postgres/overview.md) 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](https://clickhouse.com/docs/clickstack/self-configured/deployment/managed.md) 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](https://clickhouse.com/docs/products/cloud/features/cli.md).

## Installation

`clickhousectl` runs on macOS and Linux, on ARM64 and x86\_64.

```bash theme={null}
curl -fsSL https://clickhouse.com/cli | sh
```

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:

| Tool | Command |
| - | - |
| npm | `npm install -g clickhousectl` |
| uv | `uv tool install clickhousectl` |
| pipx | `pipx install clickhousectl` |
| pip | `pip install clickhousectl` |
| cargo-binstall | `cargo binstall clickhousectl` |
| Cargo, from source (Rust 1.94.1+) | `cargo install clickhousectl` |

Only the install script and npm create the `chctl` alias. To update an existing install, run `clickhousectl update` (see [Self-update](#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`:

```bash theme={null}
eval "$(clickhousectl completions bash)"   # ~/.bashrc
eval "$(clickhousectl completions zsh)"    # ~/.zshrc, after compinit
clickhousectl completions fish | source    # ~/.config/fish/config.fish
```

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](https://clickhouse.com/cloud) account. Read commands work with browser OAuth (`cloud auth login`). Creating or changing resources needs an [API key](https://clickhouse.com/docs/products/cloud/features/admin-features/api/openapi.md). See [Authentication](#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](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/local-development.md) for the full workflow.

### Install and select versions

```bash theme={null}
clickhousectl local use latest              # Install the latest ClickHouse and make it the default (recommended)
clickhousectl local install lts             # Install the latest LTS release
clickhousectl local install 26.8            # Latest 26.8.x.x release
clickhousectl local list                    # Installed versions
clickhousectl local list --remote           # Versions available for download
clickhousectl local which                   # Current default
clickhousectl local remove 26.8.1.1760      # Remove an exact installed version
clickhousectl local install --binary ~/ClickHouse/build/programs/clickhouse   # A build of your own
```

| Selector | Meaning |
| - | - |
| `latest` | Latest ClickHouse build, checked remotely on each install, use or start (recommended) |
| `stable` | Latest stable release |
| `lts` | Latest long-term support release |
| `26.8` | Latest matching release |
| `26.8.1.1760` | Exact version |

`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

```bash theme={null}
clickhousectl local init
```

`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

```bash theme={null}
clickhousectl local clickhouse start dev --version latest   # Background start; waits for readiness
clickhousectl local clickhouse start dev --no-wait          # Return after spawning
clickhousectl local clickhouse start dev --foreground       # Run in the foreground
clickhousectl local clickhouse start dev --http-port 8124 --tcp-port 9001
clickhousectl local clickhouse list                         # ClickHouse servers in this project
clickhousectl local clickhouse list --global                # Servers across all projects
clickhousectl local status                                  # Every ClickHouse server and Postgres instance in this project
clickhousectl local clickhouse stop dev
clickhousectl local clickhouse stop-all                     # Stop every ClickHouse server in this project
clickhousectl local clickhouse remove dev                   # Permanently delete a stopped server's data
```

`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

```bash theme={null}
clickhousectl local client dev                                   # Interactive session
clickhousectl local client dev --query "SELECT 1" --query "SELECT 2"
clickhousectl local client dev --queries-file schema.sql seed.sql
clickhousectl local client dev --query "SELECT version()" -- --format JSONEachRow
clickhousectl local client --host localhost --port 9000          # Connect by address
```

`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:

| Location | Applies to | When |
| - | - | - |
| `~/.clickhouse/config.d/` | Every server on this machine | Every start |
| `clickhouse/config.d/` in the project root | Every server in the project; check it in to share it | Every start |
| `~/.clickhouse/configs/` | The server you start with it | Only with `--config NAME` |

```bash theme={null}
cat > clickhouse/config.d/logging.xml <<'XML'
<clickhouse>
    <logger><level>debug</level></logger>
</clickhouse>
XML
cat > ~/.clickhouse/configs/analytics.xml <<'XML'
<clickhouse>
    <profiles>
        <default><max_threads>4</max_threads></default>
    </profiles>
</clickhouse>
XML
clickhousectl local clickhouse configs          # List both config.d directories and the named configs
clickhousectl local clickhouse stop dev
clickhousectl local clickhouse start dev --config analytics
```

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

```bash theme={null}
clickhousectl local clickhouse dotenv dev                                     # Writes .env
clickhousectl local clickhouse dotenv dev --local --user default --database analytics   # Writes .env.local
```

`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.

```bash theme={null}
clickhousectl local install postgres@18                 # Optional: pre-pull the image
clickhousectl local postgres start app --version 18
clickhousectl local postgres start app --wait-timeout 120
clickhousectl local postgres client app --query "SELECT version()"
clickhousectl local postgres client app --queries-file pg-schema.sql
clickhousectl local postgres dotenv app --local
clickhousectl local postgres list                       # Postgres instances in this project
clickhousectl local postgres stop app
clickhousectl local postgres stop-all                   # Stop every Postgres instance in this project
clickhousectl local postgres remove app                 # Permanently delete the instance and its data
```

`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](https://clickhouse.com/docs/reference/functions/regular-functions/udf.md#executable-user-defined-functions) from `clickhouse/udfs/<name>/` to a local server. `cloud udf` uploads the same directory to Cloud (see [UDFs in Cloud](#cloud-udfs)).

```bash theme={null}
clickhousectl local udf init my_udf            # udf.json and main.py (python3.11 runtime)
clickhousectl local clickhouse start
clickhousectl local udf deploy my_udf
clickhousectl local client --query "SELECT my_udf(1)"
clickhousectl local udf list
clickhousectl local udf remove my_udf
```

Every command except `init` takes `--server <name>`; without it, the [selection rule](#managing-servers) 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](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/user-defined-functions.md).

## Authentication

Cloud commands use one of two credential types:

| Credential | Capabilities | Storage |
| - | - | - |
| Browser OAuth | Your user identity: read-only Cloud operations and read-only SQL, across every organization you belong to | `~/.clickhouse/tokens.json`, global and shared across projects |
| API key | Scoped to one organization; reads and writes depend on the key's roles | `.clickhouse/credentials.json` in the project root when saved, found from any subdirectory |

If you don't have a ClickHouse Cloud account yet, `clickhousectl cloud auth signup` opens the sign-up page in your browser.

### OAuth login

```bash theme={null}
clickhousectl cloud auth login
```

This opens your browser for the OAuth device flow. Tokens are saved globally to `~/.clickhouse/tokens.json` and refreshed automatically.

> [!NOTE]
>
> OAuth is **read-only**. To create or change resources, log in with an [API key](#api-key).

### API key

[Create an API key](https://clickhouse.com/docs/products/cloud/features/admin-features/api/openapi.md) with the roles your commands need, then save it. The interactive prompt keeps the secret out of your shell history:

```bash theme={null}
clickhousectl cloud auth login --interactive
clickhousectl cloud auth login --api-key "$KEY_ID" --api-secret "$KEY_SECRET"   # Alternative
```

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:

```bash theme={null}
export CLICKHOUSE_CLOUD_API_KEY=your-api-key
export CLICKHOUSE_CLOUD_API_SECRET=your-api-secret
```

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](#local). Keep `.env` out of version control.

### Check and clear credentials

```bash theme={null}
clickhousectl cloud auth whoami          # Verify the active credentials and show the orgs they reach
clickhousectl cloud auth status          # Show configured sources and which one is active
clickhousectl cloud auth logout --oauth  # Clear OAuth tokens only
clickhousectl cloud auth logout --api-keys
clickhousectl cloud auth logout          # Clear both
```

`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:

```bash theme={null}
clickhousectl cloud clickhouse list --debug
```

### 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:

```bash theme={null}
clickhousectl cloud org list
clickhousectl cloud clickhouse list --org-id <org-id>
clickhousectl cloud clickhouse list --org-name "My Org"
```

Most resource commands take a positional ID or an exact `--name`. See [authentication and access](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/authentication.md) for permissions, restricted keys and logout cleanup.

## Cloud

Cloud commands call the [ClickHouse Cloud API](https://clickhouse.com/docs/products/cloud/features/admin-features/api/api-overview.md). 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.

```bash theme={null}
clickhousectl cloud clickhouse create --name analytics \
  --provider aws --region us-east-1 --ip-allow '203.0.113.10/32=Office'
clickhousectl cloud clickhouse create --name app-dev \
  --ip-allow 203.0.113.10/32 --dotenv .env.local          # Password goes only to the file
clickhousectl cloud clickhouse list
clickhousectl cloud clickhouse get <service-id>
clickhousectl cloud clickhouse start <service-id>
clickhousectl cloud clickhouse stop <service-id>
clickhousectl cloud clickhouse wake <service-id>             # Wake an idle service
clickhousectl cloud clickhouse reset-password <service-id>
clickhousectl cloud clickhouse delete <service-id>           # Must be stopped; --force stops it first
```

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:

```bash theme={null}
clickhousectl cloud clickhouse client <service-id>                     # Interactive clickhouse client
clickhousectl cloud clickhouse client --name analytics -q "SELECT version()"
clickhousectl cloud clickhouse dotenv <service-id> --local             # Write .env.local, without a password
```

`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`](#query-api) 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:

```bash theme={null}
clickhousectl cloud clickhouse update <service-id> --new-name analytics-prod \
  --add-ip-allow '198.51.100.0/24=VPN' --remove-ip-allow 0.0.0.0/0 --add-tag env=prod
clickhousectl cloud clickhouse update <service-id> --deletion-protection true
clickhousectl cloud clickhouse profile list --region us-east-1
clickhousectl cloud clickhouse scale <service-id> \
  --min-replica-memory-gb 8 --max-replica-memory-gb 32 --num-replicas 2
clickhousectl cloud clickhouse scale <service-id> --autoscaling-mode horizontal \
  --min-replica-memory-gb 16 --max-replica-memory-gb 16 --min-replicas 2 --max-replicas 6
clickhousectl cloud clickhouse scale <service-id> --profile v1-highmem-s
clickhousectl cloud clickhouse settings set <service-id> --setting 'enable_analyzer=1'
clickhousectl cloud clickhouse upgrade-window set <service-id> --weekday 0 --start-hour 6
```

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](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/cloud-service.md).

### Query API

`cloud clickhouse query` runs one SQL statement over HTTP, with no local `clickhouse` binary and no service password:

```bash theme={null}
clickhousectl cloud clickhouse query <service-id> --query "SELECT version()"
clickhousectl cloud clickhouse query <service-id> --queries-file query.sql --format TabSeparated
printf 'INSERT INTO trips FORMAT CSV\n' | cat - data.csv | \
  clickhousectl cloud clickhouse query <service-id>
```

* **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`](#services) 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:

```bash theme={null}
clickhousectl cloud clickhouse query-endpoint get <service-id>
clickhousectl cloud clickhouse query-endpoint create <service-id> \
  --role sql_console_read_only --allowed-origins '*'
clickhousectl cloud query-api-endpoint create <service-id> --file endpoint.json
clickhousectl cloud saved-query create <service-id> --name "Order count" \
  --sql 'SELECT count() FROM orders' --database default
```

`query-endpoint create` replaces the roles for every key bound to the endpoint. See [SQL and Query API behavior](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/query-api.md).

### Managed Postgres

`cloud postgres` (alias `cloud pg`) manages [ClickHouse Managed Postgres](https://clickhouse.com/docs/products/managed-postgres/overview.md). GCP is in private preview.

```bash theme={null}
clickhousectl cloud postgres create --name app-db \
  --provider aws --region us-east-1 --size c6gd.xlarge --pg-version 18 \
  --ip-allow '203.0.113.0/24:5432..6432=office'
clickhousectl cloud postgres get <postgres-id>
clickhousectl cloud postgres certs get <postgres-id> --output ca.pem
clickhousectl cloud postgres update <postgres-id> --size c6gd.2xlarge
clickhousectl cloud postgres update <postgres-id> --ha-type sync --standby-count 2
clickhousectl cloud postgres update <postgres-id> \
  --remove-ip-allow <rule-id> --add-ip-allow '198.51.100.7:5432'
clickhousectl cloud postgres update <postgres-id> --deletion-protection true
clickhousectl cloud postgres config patch <postgres-id> --set log_min_duration_statement=1000
clickhousectl cloud postgres reset-password <postgres-id> --generate
clickhousectl cloud postgres delete <postgres-id>       # Deletes a running service too
```

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:

```bash theme={null}
clickhousectl cloud postgres query <postgres-id> --query "SELECT version()"   # OAuth only, read-only
clickhousectl cloud postgres logs <postgres-id> \
  --from-date 2026-10-01T00:00:00Z --to-date 2026-10-02T00:00:00Z
clickhousectl cloud postgres backup list <postgres-id>
clickhousectl cloud postgres restore <postgres-id> \
  --name restored-app --restore-target 2026-10-01T12:00:00Z
clickhousectl cloud postgres read-replica create <postgres-id> --name app-db-replica
clickhousectl cloud postgres promote <replica-id>
```

`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](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/managed-postgres.md).

### 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:

```bash theme={null}
clickhousectl cloud clickpipe schema-discover object-storage <service-id> \
  --storage-type s3 --source-url 'https://example-bucket.s3.amazonaws.com/events/**' \
  --format JSONEachRow --iam-role "$S3_IAM_ROLE_ARN" --json > discovery.json
clickhousectl cloud clickpipe create object-storage <service-id> \
  --name s3-events --storage-type s3 \
  --source-url 'https://example-bucket.s3.amazonaws.com/events/**' \
  --format JSONEachRow --iam-role "$S3_IAM_ROLE_ARN" \
  --database default --table s3_events \
  --columns-from discovery.json
```

`--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:

```bash theme={null}
clickhousectl cloud postgres certs get <postgres-id> --output pg-ca.pem
clickhousectl cloud clickpipe create postgres <service-id> \
  --name orders-cdc --host "$POSTGRES_HOST" --pg-database postgres \
  --username "$POSTGRES_USERNAME" --password "$POSTGRES_PASSWORD" \
  --ca-certificate pg-ca.pem \
  --replication-mode cdc --destination-database default \
  --table-mapping public.orders:orders
clickhousectl cloud clickhouse query <service-id> \
  --query "SELECT id, status FROM default.orders FINAL WHERE _peerdb_is_deleted = 0"
```

`--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`:

```bash theme={null}
clickhousectl cloud clickpipe create kafka <service-id> \
  --name kafka-events --brokers 'broker-1.example.com:9092' --topics events \
  --format JSONEachRow --auth SCRAM-SHA-256 \
  --username "$KAFKA_USERNAME" --password "$KAFKA_PASSWORD" \
  --database default --table kafka_events \
  --column 'event_id:Int64' --column 'event_type:String' --start-paused
```

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:

```bash theme={null}
clickhousectl cloud clickpipe list <service-id>
clickhousectl cloud clickpipe get <service-id> <clickpipe-id>
clickhousectl cloud clickpipe stop <service-id> <clickpipe-id>
clickhousectl cloud clickpipe update <service-id> <clickpipe-id> --file patch.json
clickhousectl cloud clickpipe start <service-id> <clickpipe-id>
clickhousectl cloud clickpipe scale <service-id> <clickpipe-id> --replicas 2
clickhousectl cloud clickpipe settings update <service-id> <clickpipe-id> \
  --streaming-max-insert-wait-ms 5000
clickhousectl cloud clickpipe resync <service-id> <clickpipe-id>   # Postgres and MySQL pipes; re-ingests data
```

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](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/clickpipes.md) and the [ClickPipe configuration reference](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/clickpipe-configuration.md).

### ClickStack

`cloud clickstack` manages sources, dashboards, alerts, webhooks, saved searches and roles on an existing [Self-managed ClickHouse Observability](https://clickhouse.com/docs/clickstack/self-configured/deployment/managed.md) service. Resources are JSON files (`--file`, or `-` for stdin). Reads support OAuth; writes need an API key.

```bash theme={null}
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
clickhousectl cloud clickstack webhook validate <service-id> --file webhook.json
clickhousectl cloud clickstack alert create <service-id> --file alert.json
clickhousectl cloud clickstack dashboard get <service-id> <dashboard-id> --json > dashboard-before.json
```

**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](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/clickstack.md).

### 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:

```bash theme={null}
clickhousectl cloud udf deploy my_udf --service <service-id>
clickhousectl cloud clickhouse query <service-id> --query "SELECT my_udf(1)"
```

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](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/user-defined-functions.md).

### Organizations and access

```bash theme={null}
clickhousectl cloud org get --org-id <org-id>
clickhousectl cloud org update --org-id <org-id> --new-name "Renamed Org"
clickhousectl cloud org usage --org-id <org-id> --from-date 2026-09-01 --to-date 2026-09-30
clickhousectl cloud org prometheus discovery --org-id <org-id>
clickhousectl cloud org notifications --org-id <org-id> --severity warning
clickhousectl cloud activity list --from-date 2026-09-01 --to-date 2026-09-30
```

`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:

```bash theme={null}
clickhousectl cloud member list
clickhousectl cloud member update <user-id> --role-id <role-id>
clickhousectl cloud invitation create --email dev@example.com --role-id <role-id>
clickhousectl cloud org role list --org-id <org-id>
clickhousectl cloud key create --name ci-key --role-id <role-id> \
  --expires-at 2027-12-31T00:00:00Z --ip-allow '203.0.113.10/32=CI runner'
clickhousectl cloud key list --all
clickhousectl cloud key update <key-id> --new-name ci-key-old --state disabled
```

`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

```bash theme={null}
clickhousectl cloud backup list <service-id>
clickhousectl cloud backup get <service-id> <backup-id>
clickhousectl cloud clickhouse create --name restored-analytics \
  --provider aws --region us-east-1 --ip-allow 203.0.113.10/32 --backup-id <backup-id>
clickhousectl cloud clickhouse backup-config update <service-id> \
  --backup-period-hours 24 --backup-retention-period-hours 720
clickhousectl cloud backup bucket get <service-id>
```

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](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/cloud-service.md#back-up-and-restore).

## JSON output

Commands that return structured data accept `--json`, including local, Cloud, `skills`, `update` and `telemetry` commands:

```bash theme={null}
clickhousectl cloud clickhouse list --json
clickhousectl cloud key list --all --json
clickhousectl local clickhouse list --json
```

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`:

```json theme={null}
{"error":{"code":"server_not_found","message":"The selected server was not found"}}
```

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](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/automation.md) for output shapes and error codes.

## Exit codes

| Code | Meaning |
| - | - |
| `0` | Success. For asynchronous Cloud operations, the request was accepted, not completed |
| `1` | Error, including an HTTP 403 that refuses a request (code `http_4xx`) |
| `2` | Usage error, including invalid flag values and input that is checked after parsing but can never succeed; nothing is sent |
| `3` | An interactive prompt was cancelled, such as the `skills` picker |
| `4` | Authentication required or rejected, including writes attempted with OAuth |

`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](https://github.com/ClickHouse/agent-skills) into your coding agents:

```bash theme={null}
clickhousectl skills                                  # Interactive: choose scope and agents
clickhousectl skills --agent claude --agent codex     # Current project
clickhousectl skills --detected-only --global         # Agents detected in your home directory
clickhousectl skills --all
```

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

```bash theme={null}
clickhousectl search ip allow                   # Find commands and flags by keyword
clickhousectl search idle timeout --limit 10
clickhousectl feedback "cloud clickhouse create should accept a --wait flag"
```

`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](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/feedback.md).

## Self-update

```bash theme={null}
clickhousectl update --check     # Check without installing
clickhousectl update             # Install the latest release
```

`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:

```bash theme={null}
clickhousectl telemetry disable     # Persist the preference on this machine
clickhousectl telemetry status
export DO_NOT_TRACK=1               # Disable for an environment, overriding the saved preference
```

Set `CHCTL_TELEMETRY_DEBUG=1` to print the payload to stderr without sending anything. Opting out doesn't block [`feedback`](#search-and-feedback), which sends only when you run it. See [telemetry details](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/telemetry.md).
