> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentation for clickhousectl, the CLI for ClickHouse: local and cloud

# clickhousectl

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

<h2 id="installation">
  Installation
</h2>

<h3 id="quick-install">
  Quick install
</h3>

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

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.

<h2 id="requirements">
  Requirements
</h2>

* macOS (aarch64, x86\_64) or Linux (aarch64, x86\_64)
* Cloud commands require a [ClickHouse Cloud API key](/products/cloud/features/admin-features/api/api-overview)

<h2 id="local">
  Local
</h2>

<h3 id="installing-versions">
  Installing and managing ClickHouse versions
</h3>

`clickhousectl` downloads ClickHouse binaries from `builds.clickhouse.com`, falling back to `packages.clickhouse.com` (Linux) or [GitHub releases](https://github.com/ClickHouse/ClickHouse/releases) (macOS) when a build isn't available there.

```bash theme={null}
# Install a version
clickhousectl local install latest          # Latest release (recommended)
clickhousectl local install 26.5            # Latest 26.5.x.x
clickhousectl local install 26.5.2.39       # Exact version

# List versions
clickhousectl local list                    # Installed versions
clickhousectl local list --remote           # Available for download

# Manage default version
clickhousectl local use latest              # Latest release (installs if needed, recommended)
clickhousectl local use 26.5                # Latest 26.5.x.x (installs if needed)
clickhousectl local use 26.5.2.39           # Exact version
clickhousectl local use latest --no-global  # Set default but don't touch ~/.local/bin/clickhouse
clickhousectl local which                   # Show current default

# Remove a version
clickhousectl local remove 26.5.2.39
```

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

<h4 id="binary-storage">
  ClickHouse binary storage
</h4>

ClickHouse binaries are stored in a global repository, so they can be used by multiple projects without duplicating storage. Binaries are stored in `~/.clickhouse/`:

```bash theme={null}
~/.clickhouse/
├── versions/
│   └── 26.5.2.39/
│       └── clickhouse
└── default              # tracks the active version
```

<h3 id="initializing-project">
  Initializing a project
</h3>

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

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

```bash theme={null}
clickhouse/
├── tables/                 # Table definitions (CREATE TABLE ...)
├── materialized_views/     # Materialized view definitions
├── queries/                # Saved queries
└── seed/                   # Seed data / INSERT statements

postgres/
├── tables/                 # Table definitions (CREATE TABLE ...)
├── views/                  # View definitions
├── functions/              # Function definitions
├── queries/                # Saved queries
└── seed/                   # Seed data / INSERT statements
```

<h3 id="running-queries">
  Running queries
</h3>

```bash theme={null}
# Connect to a running server with clickhouse-client
clickhousectl local client                           # Connects to "default" server
clickhousectl local client --name dev                # Connects to "dev" server
clickhousectl local client --query "SHOW DATABASES"  # Run a query
clickhousectl local client --queries-file schema.sql # Run queries from a file
clickhousectl local client --host remote-host --port 9000  # Connect to a specific host/port
```

<h3 id="managing-servers">
  Creating and managing ClickHouse servers
</h3>

Start and manage ClickHouse server instances. Each server gets its own isolated data directory at `.clickhouse/servers/<name>/data/`.

```bash theme={null}
# Start a server (runs in background by default)
clickhousectl local server start                          # Named "default"
clickhousectl local server start --name dev               # Named "dev"
clickhousectl local server start --version stable         # Use a specific version (installs if needed, doesn't change default)
clickhousectl local server start --foreground             # Run in foreground (-F / --fg)
clickhousectl local server start --http-port 8124 --tcp-port 9001  # Explicit ports
clickhousectl local server start --config-file querylog          # Apply a named custom config

# List all servers (running and stopped)
clickhousectl local server list
clickhousectl local server list --global                  # List servers across all projects

# Stop servers
clickhousectl local server stop default                   # Stop by name
clickhousectl local server stop default --global          # Stop from any project
clickhousectl local server stop-all                       # Stop all running servers

# Remove a stopped server and its data
clickhousectl local server remove test

# Write connection env vars to a .env file
clickhousectl local server dotenv                         # From "default" server → .env
clickhousectl local server dotenv --name dev              # From "dev" server → .env
clickhousectl local server dotenv --local                 # Write to .env.local instead
```

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

<h4 id="custom-config-files">
  Custom config files for local servers
</h4>

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:

```bash theme={null}
mkdir -p ~/.clickhouse/configs
cat > ~/.clickhouse/configs/querylog.yaml <<'EOF'
query_log:
    database: system
    table: query_log
EOF

# See which configs are available
clickhousectl local server configs

# Start a server with one applied
clickhousectl local server start --config-file querylog
```

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.

<h4 id="project-local-data">
  Project-local data directory
</h4>

All server data lives inside `.clickhouse/` in your project directory:

```bash theme={null}
.clickhouse/
├── .gitignore              # auto-created, ignores everything
├── credentials.json        # cloud API credentials (if configured)
└── servers/
    ├── default/
    │   └── data/           # ClickHouse data files for "default" server
    └── dev/
        └── data/           # ClickHouse data files for "dev" server
```

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.

<h3 id="local-postgres">
  Running local Postgres
</h3>

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.

```bash theme={null}
# Optionally pre-pull a Postgres image (supports 17, 18 and tags like 18-alpine)
clickhousectl local install postgres@18

# Start an instance (defaults to postgres:18 on port 5432)
clickhousectl local postgres start
clickhousectl local postgres start --name dev --version 17 --port 5433
clickhousectl local postgres start --user app --password s3cret --database myapp
clickhousectl local postgres start -e POSTGRES_INITDB_ARGS=--data-checksums

# Connect with psql
clickhousectl local postgres client --name dev
clickhousectl local postgres client --name dev --query "SELECT 1"

# Export connection variables to a .env file
clickhousectl local postgres dotenv --name dev

# Stop (preserves data) and remove (deletes data)
clickhousectl local postgres stop dev
clickhousectl local postgres remove dev
```

<h2 id="authentication">
  Authentication
</h2>

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.

<h3 id="api-key">
  API key/secret (recommended)
</h3>

API keys are the recommended way to authenticate, especially when driving the CLI from an AI agent. You can [create scoped API keys](/products/cloud/features/admin-features/api/openapi) 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.

```bash theme={null}
# Non-interactive (CI-friendly)
clickhousectl cloud auth login --api-key YOUR_KEY --api-secret YOUR_SECRET

# Interactive prompt
clickhousectl cloud auth login --interactive
```

Credentials are saved to `.clickhouse/credentials.json` (project-local).

You can also use environment variables, either exported in your session:

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

Or placed in a `.env` file in your current working directory:

```env theme={null}
CLICKHOUSE_CLOUD_API_KEY=your-key
CLICKHOUSE_CLOUD_API_SECRET=your-secret
```

Or pass credentials directly via flags on any command:

```bash theme={null}
clickhousectl cloud --api-key KEY --api-secret SECRET ...
```

<h3 id="oauth-login">
  OAuth login
</h3>

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

This opens your browser for authentication via the OAuth device flow. Tokens are saved to `.clickhouse/tokens.json` (project-local).

<Note>
  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](#api-key) instead.
</Note>

<h3 id="auth-status">
  Auth status and logout
</h3>

```bash theme={null}
clickhousectl cloud auth status    # Show current auth state
clickhousectl cloud auth logout    # Clear all saved credentials (credentials.json & tokens.json)
```

Credential resolution order: CLI flags > `.clickhouse/credentials.json` > exported environment variables > `.env` file > OAuth tokens.

<h3 id="debug-credentials">
  Debugging which credential source was used
</h3>

Pass `--debug` to any `cloud` command to print the resolved credential source (and the API URL) to stderr before the command runs.

```bash theme={null}
clickhousectl cloud --debug service list
# [debug] auth source: credentials file (.clickhouse/credentials.json)
# [debug] api url: https://api.clickhouse.cloud/v1
# ... normal output ...
```

<h2 id="cloud">
  Cloud
</h2>

Manage ClickHouse Cloud services via the API.

<h3 id="organizations">
  Organizations
</h3>

```bash theme={null}
clickhousectl cloud org list              # List organizations
clickhousectl cloud org get <org-id>      # Get organization details
clickhousectl cloud org update <org-id> --name "Renamed Org"
clickhousectl cloud org update <org-id> \
  --remove-private-endpoint pe-1,cloud-provider=aws,region=us-east-1 \
  --enable-core-dumps false
clickhousectl cloud org prometheus <org-id> --filtered-metrics true
clickhousectl cloud org usage <org-id> \
  --from-date 2024-01-01 \
  --to-date 2024-01-31
```

<h3 id="services">
  Services
</h3>

```bash theme={null}
# List services
clickhousectl cloud service list

# Get service details
clickhousectl cloud service get <service-id>

# Create a service (minimal)
clickhousectl cloud service create --name my-service

# Create with scaling options
clickhousectl cloud service create --name my-service \
  --provider aws \
  --region us-east-1 \
  --min-replica-memory-gb 8 \
  --max-replica-memory-gb 32 \
  --num-replicas 2

# Create with specific IP allowlist
clickhousectl cloud service create --name my-service \
  --ip-allow 10.0.0.0/8 \
  --ip-allow 192.168.1.0/24

# Create from backup
clickhousectl cloud service create --name restored-service --backup-id <backup-uuid>

# Create with release channel
clickhousectl cloud service create --name my-service --release-channel fast

# Create with GA request-only extras
clickhousectl cloud service create --name my-service \
  --tag env=prod \
  --enable-endpoint mysql \
  --private-preview-terms-checked \
  --enable-core-dumps true

# Start/stop a service
clickhousectl cloud service start <service-id>
clickhousectl cloud service stop <service-id>

# Run SQL over HTTP via the Query API (no local clickhouse binary needed)
clickhousectl cloud service query --name my-service --query "SELECT 1"
clickhousectl cloud service query --id <service-id> --query "SELECT count() FROM system.tables" --format JSONEachRow
clickhousectl cloud service query --name my-service --queries-file schema.sql   # "-" reads from stdin
clickhousectl cloud service query --name my-service --database mydb --query "SHOW TABLES"
echo "SELECT 1+1" | clickhousectl cloud service query --name my-service

# Update service metadata and patches
clickhousectl cloud service update <service-id> \
  --name my-renamed-service \
  --add-ip-allow 10.0.0.0/8 \
  --remove-ip-allow 0.0.0.0/0 \
  --add-private-endpoint-id pe-1 \
  --release-channel fast \
  --enable-endpoint mysql \
  --add-tag env=staging \
  --transparent-data-encryption-key-id tde-key-1 \
  --enable-core-dumps false

# Update replica scaling
clickhousectl cloud service scale <service-id> \
  --min-replica-memory-gb 24 \
  --max-replica-memory-gb 48 \
  --num-replicas 3 \
  --idle-scaling true \
  --idle-timeout-minutes 10

# Reset password with generated credentials
clickhousectl cloud service reset-password <service-id>

# Delete a service (must be stopped first)
clickhousectl cloud service delete <service-id>

# Force delete: stops a running service then deletes
clickhousectl cloud service delete <service-id> --force
```

<h4 id="service-create-options">
  Service create options
</h4>

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

<h4 id="query-api-auth-modes">
  Query API auth modes
</h4>

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

<h4 id="query-endpoints">
  Query endpoint management
</h4>

```bash theme={null}
clickhousectl cloud service query-endpoint get <service-id>
clickhousectl cloud service query-endpoint create <service-id> \
  --role admin \
  --open-api-key key-1 \
  --allowed-origins https://app.example.com
clickhousectl cloud service query-endpoint delete <service-id>
```

<h4 id="private-endpoints">
  Private endpoint management
</h4>

```bash theme={null}
clickhousectl cloud service private-endpoint create <service-id> --endpoint-id vpce-123
clickhousectl cloud service private-endpoint get-config <service-id>
```

<h4 id="backup-config">
  Backup configuration
</h4>

```bash theme={null}
clickhousectl cloud service backup-config get <service-id>
clickhousectl cloud service backup-config update <service-id> \
  --backup-period-hours 24 \
  --backup-retention-period-hours 720 \
  --backup-start-time 02:00
```

<h3 id="postgres-services">
  Postgres services
</h3>

`clickhousectl` can also create and manage [ClickHouse Cloud Postgres](/products/managed-postgres/overview) services, mirroring the ClickHouse service commands above.

```bash theme={null}
# List and inspect
clickhousectl cloud postgres list
clickhousectl cloud postgres list --filter state=running
clickhousectl cloud postgres get <pg-id>

# Create a service
clickhousectl cloud postgres create \
  --name my-pg \
  --region us-east-1 \
  --size m7i.2xlarge \
  --pg-version 17 \
  --ha-type sync

# Update and delete
clickhousectl cloud postgres update <pg-id> --size m7i.4xlarge
clickhousectl cloud postgres update <pg-id> --add-tag env=prod --remove-tag legacy
clickhousectl cloud postgres delete <pg-id>

# Connection certificates
clickhousectl cloud postgres certs get <pg-id>                   # raw PEM to stdout
clickhousectl cloud postgres certs get <pg-id> --output ca.pem   # write to a file

# Configuration
clickhousectl cloud postgres config get <pg-id>
clickhousectl cloud postgres config replace <pg-id> --file cfg.json
clickhousectl cloud postgres config patch <pg-id> --set max_connections=500

# Reset the password
clickhousectl cloud postgres reset-password <pg-id> --generate

# Lifecycle: restart and high-availability promotion/switchover
clickhousectl cloud postgres restart <pg-id>
clickhousectl cloud postgres promote <pg-id>
clickhousectl cloud postgres switchover <pg-id>

# Read replicas and point-in-time restore
clickhousectl cloud postgres read-replica create <pg-id> --name replica-1
clickhousectl cloud postgres restore <pg-id> --name restored --restore-target 2026-04-16T12:00:00Z
```

<h4 id="postgres-create-options">
  Postgres service create options
</h4>

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

<h3 id="backups">
  Backups
</h3>

```bash theme={null}
clickhousectl cloud backup list <service-id>
clickhousectl cloud backup get <service-id> <backup-id>
```

<h3 id="clickpipes">
  ClickPipes
</h3>

Manage ClickPipes for ingesting data into ClickHouse Cloud from external sources.

```bash theme={null}
# List ClickPipes for a service
clickhousectl cloud clickpipe list <service-id>

# Get ClickPipe details
clickhousectl cloud clickpipe get <service-id> <clickpipe-id>

# Start/stop/resync a ClickPipe
clickhousectl cloud clickpipe start <service-id> <clickpipe-id>
clickhousectl cloud clickpipe stop <service-id> <clickpipe-id>
clickhousectl cloud clickpipe resync <service-id> <clickpipe-id>   # CDC pipes only

# Delete a ClickPipe
clickhousectl cloud clickpipe delete <service-id> <clickpipe-id>

# Update scaling
clickhousectl cloud clickpipe scale <service-id> <clickpipe-id> \
  --replicas 2 --cpu-millicores 250 --memory-gb 1

# Get/update settings
clickhousectl cloud clickpipe settings get <service-id> <clickpipe-id>
clickhousectl cloud clickpipe settings update <service-id> <clickpipe-id> \
  --streaming-max-insert-wait-ms 10000
```

<h4 id="creating-clickpipes">
  Creating ClickPipes
</h4>

Each source type has its own subcommand under `clickpipe create`:

```bash theme={null}
# From S3 / object storage
clickhousectl cloud clickpipe create object-storage <service-id> \
  --name my-s3-pipe \
  --source-url 'https://bucket.s3.us-east-1.amazonaws.com/data/**' \
  --format JSONEachRow \
  --database default --table events \
  --column "event_id:Int64" --column "name:String"

# From Google Cloud Storage (object storage)
clickhousectl cloud clickpipe create object-storage <service-id> \
  --name my-gcs-pipe \
  --storage-type gcs \
  --source-url 'https://storage.googleapis.com/bucket/data/**' \
  --format JSONEachRow \
  --service-account-file ./sa-key.json \
  --database default --table events \
  --column "event_id:Int64" --column "name:String"

# From Kafka / Redpanda / Confluent / MSK
clickhousectl cloud clickpipe create kafka <service-id> \
  --name my-kafka-pipe \
  --brokers 'broker:9092' --topics events \
  --format JSONEachRow \
  --kafka-type redpanda \
  --auth SCRAM-SHA-256 --username user --password pass \
  --ca-certificate ./ca.crt \
  --database default --table events \
  --column "event_id:Int64" --column "name:String"

# From Amazon Kinesis
clickhousectl cloud clickpipe create kinesis <service-id> \
  --name my-kinesis-pipe \
  --stream-name events --region us-east-1 \
  --format JSONEachRow \
  --auth IAM_USER --access-key-id AKIA... --secret-key ... \
  --database default --table events \
  --column "event_id:Int64" --column "name:String"

# From PostgreSQL (CDC)
clickhousectl cloud clickpipe create postgres <service-id> \
  --name my-pg-pipe \
  --host db.example.com --pg-database mydb \
  --username pguser --password pgpass \
  --table-mapping "public.users:public_users" \
  --table-mapping "public.orders:public_orders"

# From MySQL (CDC)
clickhousectl cloud clickpipe create mysql <service-id> \
  --name my-mysql-pipe \
  --host mysql.example.com \
  --username root --password pass \
  --table-mapping "mydb.users:mydb_users"

# From MongoDB (CDC)
clickhousectl cloud clickpipe create mongodb <service-id> \
  --name my-mongo-pipe \
  --uri 'mongodb+srv://cluster.example.net/mydb' \
  --username mongouser --password mongopass \
  --table-mapping "mydb.users:mydb_users"

# From BigQuery (snapshot)
clickhousectl cloud clickpipe create bigquery <service-id> \
  --name my-bq-pipe \
  --service-account-file ./sa-key.json \
  --staging-path gs://bucket/staging \
  --table-mapping "dataset.table:target_table"
```

Use `clickhousectl cloud clickpipe create <source> --help` for the full list of options per source type.

<h3 id="members">
  Members
</h3>

```bash theme={null}
clickhousectl cloud member list
clickhousectl cloud member get <user-id>
clickhousectl cloud member update <user-id> --role-id <role-id>
clickhousectl cloud member remove <user-id>
```

<h3 id="invitations">
  Invitations
</h3>

```bash theme={null}
clickhousectl cloud invitation list
clickhousectl cloud invitation create --email dev@example.com --role-id <role-id>
clickhousectl cloud invitation get <invitation-id>
clickhousectl cloud invitation delete <invitation-id>
```

<h3 id="keys">
  Keys
</h3>

```bash theme={null}
clickhousectl cloud key list
clickhousectl cloud key get <key-id>
clickhousectl cloud key create --name ci-key --role-id <role-id> --ip-allow 10.0.0.0/8
clickhousectl cloud key update <key-id> \
  --name renamed-key \
  --expires-at 2025-12-31T00:00:00Z \
  --state disabled \
  --ip-allow 0.0.0.0/0
clickhousectl cloud key delete <key-id>
```

<h3 id="activity">
  Activity
</h3>

```bash theme={null}
clickhousectl cloud activity list --from-date 2024-01-01 --to-date 2024-12-31
clickhousectl cloud activity get <activity-id>
```

<h3 id="json-output">
  JSON output
</h3>

Use the `--json` flag to print JSON-formatted responses.

```bash theme={null}
clickhousectl cloud --json service list
clickhousectl cloud --json service get <service-id>
```

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

<h3 id="exit-codes">
  Exit codes
</h3>

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) |

<h2 id="skills">
  Skills
</h2>

Install the official ClickHouse Agent Skills from [ClickHouse/agent-skills](https://github.com/ClickHouse/agent-skills).

```bash theme={null}
# Default: interactive mode for humans, choose scope, then choose agents
clickhousectl skills

# Non-interactive: install into every supported project-local agent folder
clickhousectl skills --all

# Non-interactive: install only into detected agents
clickhousectl skills --detected-only

# Non-interactive: install into every supported global agent folder
clickhousectl skills --global --all

# Non-interactive: install into specific project-local agents
clickhousectl skills --agent claude --agent codex
```

<h3 id="non-interactive-flags">
  Non-interactive flags
</h3>

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

<h2 id="self-update">
  Self-update
</h2>

`clickhousectl` can update itself to the latest release:

```bash theme={null}
# Update to the latest version
clickhousectl update

# Check for updates without installing
clickhousectl update --check
```

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.

<h2 id="telemetry">
  Telemetry
</h2>

`clickhousectl` collects anonymous usage telemetry to help us understand how the CLI is used. It is enabled by default, but nothing is ever sent before you have been notified: on the first run, the CLI prints a notice explaining what is collected and how to turn it off, and sends nothing. Collection only starts on subsequent runs, so you always have the opportunity to opt out before anything is collected.

Each event contains only:

* The command that was run (e.g. `local start`) and the names of the flags that were used — never flag values, positional arguments, or any other user-supplied input, so queries, table names, credentials, and file paths are never collected
* The exit code (e.g. `0`, `1`, `2`, `4`) and the outcome (e.g. `ok`, `error`, `cancelled`)
* For mistyped commands, the "did you mean" suggestion the CLI showed — recorded only when it exactly matches a real command or flag name, so it can never contain what you typed
* The `clickhousectl` version, OS, architecture, and whether the CLI was invoked by an AI agent (and which agent) or in CI

Telemetry is fully anonymous: no personal data is collected, and there are no device or installation identifiers.

To turn telemetry off, either:

* Run `clickhousectl telemetry disable` (re-enable with `enable`, check with `status`)
* Set the `DO_NOT_TRACK=1` environment variable

Set `CHCTL_TELEMETRY_DEBUG=1` to print the exact payload to stderr without sending anything.