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

# ClickHouse CLI

> Use the ClickHouse CLI (clickhousectl) to create and manage ClickHouse Cloud services, Managed Postgres, ClickPipes and ClickStack from a terminal

The ClickHouse CLI (`clickhousectl`, alias `chctl`) manages ClickHouse Cloud from a terminal, a script or a coding agent. This page covers the Cloud side of the CLI. For every command group, local development and the full behaviour, see the [clickhousectl reference](https://clickhouse.com/docs/concepts/features/interfaces/cli.md).

## What you can manage

The `clickhousectl cloud` commands cover:

* **Services:** create, scale, start and stop ClickHouse Cloud services, and run SQL against them over the Query API.
* **[Managed Postgres](https://clickhouse.com/docs/products/managed-postgres/overview.md) (Beta):** create Postgres services, read replicas and point-in-time restores, and change their configuration.
* **[ClickPipes](https://clickhouse.com/docs/integrations/clickpipes/home.md):** ingest from object storage, Kafka, Kinesis, Pub/Sub, Postgres, MySQL, MongoDB and BigQuery.
* **[ClickStack](https://clickhouse.com/docs/clickstack/overview.md):** manage sources, dashboards, alerts, webhooks, saved searches and roles on a [Managed ClickStack](https://clickhouse.com/docs/clickstack/deployment/managed.md) service.
* **User-defined functions:** test executable UDFs locally, then deploy them to a Cloud service.
* **Backups:** list backups, change the backup schedule and restore a backup into a new service.
* **Organization access:** organizations, members, invitations, API keys and the activity log.

Run `clickhousectl cloud <command> --help` for the flags of any command and the API key permissions it needs.

## Installation

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

The script installs `~/.local/bin/clickhousectl` and a `chctl` alias. Make sure `~/.local/bin` is on your `PATH`. For npm, pip, uv and the other install methods, see [Installation](https://clickhouse.com/docs/concepts/features/interfaces/cli.md#installation).

## Authentication

Browser OAuth login is read-only. Creating or changing resources needs an [API key](https://clickhouse.com/docs/products/cloud/features/admin-features/api/openapi.md) with a role that allows the change.

```bash theme={null}
# Read-only: OAuth device flow in your browser
clickhousectl cloud auth login

# Read and write: prompts for the API key and secret, keeping the secret out of shell history
clickhousectl cloud auth login --interactive

# Alternative for scripts
clickhousectl cloud auth login --api-key <key> --api-secret <secret>
```

Login verifies the credentials and prints the identity. Check it any time with `clickhousectl cloud auth whoami`. If you belong to several organizations, add `--org-id <org-id>` (or `--org-name <name>`) to Cloud commands. In CI, set `CLICKHOUSE_CLOUD_API_KEY` and `CLICKHOUSE_CLOUD_API_SECRET` instead of logging in. See [Authentication](https://clickhouse.com/docs/concepts/features/interfaces/cli.md#authentication) for credential precedence and logout.

## Examples

### Create and query a service

```bash theme={null}
# Create a service. Save the initial password; it is printed only once.
# Omitting --ip-allow allows all addresses (0.0.0.0/0).
clickhousectl cloud service create --name analytics \
  --provider aws --region us-east-1 \
  --ip-allow '203.0.113.10/32=Office'

# Look up the service ID, then run SQL over the Query API
CH_ID=$(clickhousectl cloud service get --name analytics --json | jq -r .id)
clickhousectl cloud service query "$CH_ID" --query "SELECT version()"
```

Creation returns before the service is running. Poll `clickhousectl cloud service get "$CH_ID"` until `state` is `running`.

On the first API-key query, clickhousectl adds your API key to the service's Query API endpoint, creating the endpoint if needed; no new key is created. Pass `--no-auto-enable` to fail instead. With OAuth, `service query` runs read-only `SELECT` statements. The Query API times out after about 30 seconds, so use `clickhouse client` for long queries and bulk loads.

### Create a Managed Postgres service

```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.10/32:5432=Office'
clickhousectl cloud postgres get <postgres-id>
clickhousectl cloud postgres certs get <postgres-id> --output ca.pem
```

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

### Inspect ClickPipes, ClickStack and backups

```bash theme={null}
clickhousectl cloud clickpipe list "$CH_ID"
clickhousectl cloud clickstack source list <clickstack-service-id>
clickhousectl cloud backup list "$CH_ID"
```

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

### Deploy a user-defined function

```bash theme={null}
# Uploads clickhouse/udfs/my_udf/, waits for the build, then attaches that version to the service
clickhousectl cloud udf deploy my_udf --service "$CH_ID"
```

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

## JSON output and coding agents

Cloud commands accept `--json`, and the CLI selects JSON automatically when it detects a coding agent. `cloud service query` then defaults to `JSONEachRow`, so scripts that parse its output should pass `--format`, for example `--format TabSeparated`. See [JSON output](https://clickhouse.com/docs/concepts/features/interfaces/cli.md#json-output) and [Exit codes](https://clickhouse.com/docs/concepts/features/interfaces/cli.md#exit-codes). Install the ClickHouse agent skills with `clickhousectl skills`.

## Learn more

* [clickhousectl reference](https://clickhouse.com/docs/concepts/features/interfaces/cli.md): every command group, local development, skills, self-update and telemetry.
* Repository guides:
  * [ClickHouse Cloud services](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/cloud-service.md)
  * [ClickHouse Managed Postgres](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/managed-postgres.md)
  * [ClickPipes](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/clickpipes.md)
  * [ClickStack](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/clickstack.md)
  * [User-defined functions](https://github.com/ClickHouse/clickhousectl/blob/main/docs/guides/user-defined-functions.md)
* Repository references: [authentication and access](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/authentication.md), [SQL and the Query API](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/query-api.md), [ClickPipe configuration](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/clickpipe-configuration.md) and [automation and output contracts](https://github.com/ClickHouse/clickhousectl/blob/main/docs/reference/automation.md).
