> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # ClickHouse CLI > ClickHouse CLI를 사용하여 ClickHouse Cloud 서비스와 로컬 ClickHouse 인스턴스를 관리합니다 ClickHouse CLI(`clickhousectl`)는 ClickHouse Cloud 리소스 관리와 로컬 환경에서의 ClickHouse 개발을 위한 통합 명령줄 도구입니다. 또한 [ClickHouse Cloud Postgres](/ko/products/managed-postgres/overview) 서비스와 [ClickPipes](/ko/integrations/clickpipes) 관리도 지원합니다. 이 페이지는 `clickhousectl` 0.4.2의 명령어 체계에 대한 참고 문서입니다. 설치된 버전을 확인하려면 `clickhousectl --version`을 실행하고, 특정 명령어의 전체 플래그 목록을 보려면 `clickhousectl --help`를 실행하십시오.

설치

```bash theme={null} curl https://clickhouse.com/cli | sh ``` 편의를 위해 `chctl` 별칭이 자동으로 함께 생성됩니다. 기존 설치를 최신 버전으로 업데이트하려면: ```bash theme={null} clickhousectl update # self-update clickhousectl update --check # check for updates without installing ```

Cloud 관리

명령줄에서 직접 ClickHouse Cloud에 인증하고 서비스를 관리할 수 있습니다.

인증

```bash theme={null} # Log in with an API key (read/write access) clickhousectl cloud auth login --api-key --api-secret # Log in with the OAuth device flow (interactive; read-only access) clickhousectl cloud auth login # Show which credential source is active clickhousectl cloud auth status # Log out and clear saved credentials clickhousectl cloud auth logout # Create a new ClickHouse Cloud account clickhousectl cloud auth signup ``` API Key는 `.clickhouse/credentials.json`에 저장됩니다(프로젝트 로컬, git 추적 제외). 환경 변수를 사용할 수도 있습니다: ```bash theme={null} export CLICKHOUSE_CLOUD_API_KEY=your-key export CLICKHOUSE_CLOUD_API_SECRET=your-secret ``` 자격 증명의 precedence는 높은 순서부터 낮은 순서로 다음과 같습니다: `--api-key`/`--api-secret` 플래그, `.clickhouse/credentials.json`에 저장된 프로젝트 자격 증명, environment variables(shell, 그다음 `.env`), `cloud auth login`으로 발급받은 OAuth 토큰. OAuth 토큰은 읽기 전용입니다. 쓰기 명령어(create, delete, start, stop, update, scale)에는 API Key 인증이 필요합니다.

서비스

```bash theme={null} # List services clickhousectl cloud service list # Create a service clickhousectl cloud service create --name my-service \ --provider aws \ --region us-east-1 # Get service details clickhousectl cloud service get # Update service settings (name, IP allow list, tags, endpoints, ...) clickhousectl cloud service update --add-ip-allow 0.0.0.0/0 # Scale a service clickhousectl cloud service scale \ --min-replica-memory-gb 24 \ --max-replica-memory-gb 48 \ --num-replicas 3 # Start/stop a service clickhousectl cloud service start clickhousectl cloud service stop # Reset the default user password clickhousectl cloud service reset-password # Delete a service clickhousectl cloud service delete ```

쿼리 실행

Query API를 사용해 HTTP로 Cloud 서비스에서 SQL을 실행합니다. 로컬 `clickhouse` binary나 service password는 필요하지 않습니다. `--id` 또는 `--name` 중 반드시 하나만 지정해야 합니다: ```bash theme={null} # Query by service ID or by name clickhousectl cloud service query --id -q 'SELECT 1' clickhousectl cloud service query --name my-service -q 'SELECT version()' # Run a query from a SQL file (use "-" for stdin), choosing an output format. # The file must hold a single statement clickhousectl cloud service query --id \ --queries-file report.sql --format JSONEachRow # With neither --query nor --queries-file, SQL is read from stdin echo 'SELECT 1' | clickhousectl cloud service query --id # Replace a stored Query API key that the endpoint rejects clickhousectl cloud service repair-query-key ``` API Key 인증을 사용하면 쿼리는 읽기 및 쓰기 액세스 권한으로 실행됩니다. 서비스의 query 엔드포인트가 이미 해당 키를 인가한 상태라면 인증된 키가 그대로 사용되고, 그렇지 않으면 첫 번째 쿼리가 query 엔드포인트와 서비스별 읽기/쓰기 키를 프로비저닝한 뒤 그 키를 `.clickhouse/credentials.json`에 저장합니다. 프로비저닝하지 않고 실패하도록 하려면 `--no-auto-enable`을 전달하십시오. OAuth를 사용하면 SQL이 cloud 사용자 권한으로 읽기 전용 액세스(`SELECT`만 가능)로 실행되며, 프로비저닝되는 것은 없습니다. 알아두어야 할 사항: * `service query`는 요청당 하나의 statement만 실행합니다. 다중 statement SQL은 `--query`, `--queries-file`, stdin 중 어떤 경로로 전달되든 Query API에서 거부되며 `Error: SQL error 62: Syntax error (Multi-statements are not allowed)`가 반환됩니다. 단일 statement 끝에 `;`가 붙는 것은 문제없습니다. script를 실행할 때는 `clickhousectl local use latest`를 실행한 뒤 해당 서비스에 `clickhouse client`로 접속하십시오. * `--query`와 `--queries-file`은 함께 사용할 수 없습니다(종료 코드 2). stdin은 둘 다 지정되지 않았을 때만 읽습니다. `--query`는 stdin을 읽지 않으므로, 이와 함께 데이터를 리다이렉트하거나 파이프로 전달하면 조용히 무시되는 것이 아니라 오류로 처리됩니다: `Error: --query cannot be combined with SQL or data on stdin.` 대신 `INSERT`와 해당 데이터를 하나의 single stream으로 보내거나 — `printf 'INSERT INTO t FORMAT CSV\n' | cat - data.csv | clickhousectl cloud service query --id ` — `--queries-file -`로 stdin에서 statement 전체를 읽으십시오. * 기본 출력 형식은 terminal에서는 `PrettyCompact`, 파이프로 연결된 경우 `TabSeparated`입니다. `--json`은 `JSONEachRow`를 선택하며 `--format`과 함께 사용할 수 없습니다(종료 코드 2). * 엔드포인트가 HTTP 401/403으로 거부하는 저장된 Query API 키는 자동으로 대체되지 않습니다. CLI는 거부 사유를 알리기 위해서만 해당 키의 management 레코드를 읽습니다. 이 자격 증명 하나만 `clickhousectl cloud service repair-query-key `로 교체하십시오. 이 명령은 대체된 기존 키도 함께 삭제합니다. 실행 중인 서비스에서는 새 키로 수행한 probe 쿼리가 성공해야만 0으로 종료되며, 그 결과는 `--json` 출력의 `verification` 항목에 표시됩니다. readiness 윈도우가 끝날 때까지 Query API가 여전히 키를 거부하면 명령은 1로 종료되지만 복구 자체는 유효합니다. 명령을 다시 실행하지 말고 `cloud service query`를 실행하십시오. * Query API는 약 30초 후 타임아웃됩니다. statement는 서비스에서 계속 실행되지만 결과는 유실됩니다. 더 오래 걸리는 작업에는 `clickhousectl local use latest`를 실행해 표준 `clickhouse` binary를 `PATH`에 추가한 뒤 `clickhouse client --host --secure --port 9440 --user default --password `로 연결하십시오.

서비스 엔드포인트 및 구성

```bash theme={null} # Query endpoints (used by the Query API) clickhousectl cloud service query-endpoint get clickhousectl cloud service query-endpoint create --role sql_console_admin clickhousectl cloud service query-endpoint delete # Private endpoints. --endpoint-id takes an AWS VPC endpoint ID, a GCP PSC # connection ID, or an Azure private endpoint Resource ID / resourceGuid clickhousectl cloud service private-endpoint get-config clickhousectl cloud service private-endpoint create --endpoint-id # Backup configuration clickhousectl cloud service backup-config get clickhousectl cloud service backup-config update --backup-period-hours 24 clickhousectl cloud service backup-config update \ --backup-start-time 02:00 --backup-period-hours 24 clickhousectl cloud service backup-config update --clear-backup-start-time # Prometheus metrics for a service (always raw Prometheus exposition text) clickhousectl cloud service prometheus ``` `--backup-start-time`은 반드시 정시(`HH:00`)여야 하며, API 호출 전에 CLI에서 이를 검사합니다. 또한 백업 주기가 `24`시간 또는 `48`시간이어야 합니다. 동일한 명령에서 `--backup-period-hours 24` 또는 `--backup-period-hours 48`을 전달하거나, 두 값 중 하나가 이미 저장되어 있어야 합니다. 그 외의 주기가 저장되어 있으면 CLI는 API를 호출하기 전에 `Error: the stored backup period is 12 hours, but --backup-start-time requires 24 or 48.` 메시지와 함께 요청을 거부합니다. `--clear-backup-start-time`은 저장된 시작 시간을 제거하고 해당 제한을 해제합니다. `--backup-period-hours`와 함께 사용하면 한 번의 호출로 시작 시간을 지우고 원하는 주기를 설정할 수 있습니다. 이 옵션은 `--backup-start-time`과 함께 사용할 수 없습니다.

백업

```bash theme={null} clickhousectl cloud backup list clickhousectl cloud backup get ``` 백업을 복원하려면 해당 백업으로 새 서비스를 생성하십시오: `clickhousectl cloud service create --name restored-service --backup-id `.

ClickPipes

Cloud 서비스로 데이터를 수집하는 [ClickPipes](/ko/integrations/clickpipes)를 관리합니다. 대부분의 명령어는 서비스 ID를 첫 번째 인수로 받습니다. ```bash theme={null} # List pipes and get details clickhousectl cloud clickpipe list clickhousectl cloud clickpipe get # Create a pipe. Sources: object-storage, kafka, kinesis, pubsub, # postgres, mysql, mongodb, bigquery clickhousectl cloud clickpipe create object-storage \ --name my-pipe \ --source-url 'https://bucket.s3.us-east-1.amazonaws.com/data/*.json' \ --format JSONEachRow \ --database default \ --table events # A Postgres pipe needs at least one --table-mapping or --table-mapping-json clickhousectl cloud clickpipe create postgres \ --name my-cdc-pipe \ --host pg.example.com \ --pg-database appdb \ --username replicator \ --password \ --table-mapping public.orders:orders \ --sync-interval-seconds 30 \ --ca-certificate ./source-ca.pem # Lifecycle clickhousectl cloud clickpipe start clickhousectl cloud clickpipe stop clickhousectl cloud clickpipe resync # CDC pipes only clickhousectl cloud clickpipe delete # Scaling and settings. scale requires at least one of # --replicas, --cpu-millicores, or --memory-gb clickhousectl cloud clickpipe scale --replicas 2 clickhousectl cloud clickpipe settings get clickhousectl cloud clickpipe settings update # Discover a source schema without creating a pipe (beta) clickhousectl cloud clickpipe schema-discover kafka [options] clickhousectl cloud clickpipe schema-discover kinesis [options] clickhousectl cloud clickpipe schema-discover object-storage [options] clickhousectl cloud clickpipe schema-discover pubsub [options] # Reverse private endpoints: AWS PrivateLink, Amazon MSK multi-VPC, # Google Private Service Connect clickhousectl cloud clickpipe reverse-private-endpoint list clickhousectl cloud clickpipe reverse-private-endpoint get clickhousectl cloud clickpipe reverse-private-endpoint create \ --type VPC_ENDPOINT_SERVICE \ --description 'kafka source' \ --vpc-endpoint-service-name clickhousectl cloud clickpipe reverse-private-endpoint update \ --custom-private-dns-mapping pg.internal.example.com clickhousectl cloud clickpipe reverse-private-endpoint delete ``` 알아두어야 할 사항: * `clickpipe create postgres`는 `--table-mapping `(반복 지정 가능, 플래그당 테이블 1개) 또는 `--table-mapping-json ` 중 하나가 필요하며, 두 옵션을 함께 사용할 수도 있습니다. JSON 형식은 API의 테이블 매핑 객체를 그대로 받으며, `excludedColumns`, `sortingKeys`, `partitionByExpr`, `partitionKey`, `tableEngine`을 설정할 수 있는 유일한 방법입니다. `partitionKey`는 병렬 처리를 위해 초기 스냅샷을 분할하는 값이며, 대상 테이블의 `PARTITION BY`와는 무관하다는 점에 유의하십시오. `PARTITION BY`에 해당하는 것은 `partitionByExpr`입니다. `--iam-role`은 `--auth IAM_ROLE`과 함께 사용해야 하며 기본 인증에서는 거부됩니다. `--replication-slot-name`은 `--replication-mode cdc_only`에서만 유효합니다. * Postgres CDC 설정은 파이프 생성 시 적용됩니다: `--sync-interval-seconds`, `--pull-batch-size`, `--initial-load-parallelism`, `--snapshot-rows-per-partition`, `--snapshot-parallel-tables`, `--allow-nullable-columns`, `--enable-failover-slots`, `--delete-on-merge`. 이후에 변경할 수 있는 것은 sync interval과 pull batch 크기뿐이며, 스냅샷 및 초기 로드 설정은 변경할 수 없습니다. * 모든 `clickpipe create` 하위 명령에서 `--role `은 반복 지정할 수 있으며, 파이프의 대상 사용자에게 부여할 ClickHouse 역할을 지정합니다. 이 옵션은 해당 사용자가 원래 받게 될 역할을 대체합니다. `--role`을 지정하지 않으면 사용자는 `clickpipes_system`과 `default_role`을 갖고, `--role my_role`을 지정하면 `clickpipes_system`과 `my_role`을 갖습니다. 해당 역할은 대상 데이터베이스에서 테이블을 생성할 수 있어야 하며, 읽기 전용 역할을 사용하면 `Not enough privileges` 오류로 생성이 실패합니다. API가 예약한 이름인 `clickpipes`와 `clickpipes_system`은 거부됩니다. * Postgres 소스에서는 TLS와 certificate verification이 기본적으로 활성화되어 있습니다. 공개적으로 신뢰되는 소스 체인은 CA 파일이 필요하지 않지만, 비공개 또는 자체 서명된 소스 CA를 사용하는 경우 `--ca-certificate `로 해당 PEM bundle을 전달하십시오. ClickHouse Cloud Postgres 소스라면 `clickhousectl cloud postgres certs get`으로 해당 bundle을 가져올 수 있습니다. 호스트명 검증에는 `--host`가 사용되며, `--tls-host `으로 재정의할 수 있습니다. * Kafka 및 Kinesis 파이프에서는 `--auth`를 생략하면 credential 플래그를 통해 값이 추론되며, credential 플래그를 전혀 지정하지 않으면 인증 정보가 전송되지 않습니다. * `clickpipe settings`는 스트리밍(Kafka, Kinesis) 및 객체 스토리지 파이프의 수집 설정만 다루며, Kafka 전용 설정은 Kafka가 아닌 파이프에서는 제외됩니다. 데이터베이스 CDC 파이프(Postgres, MySQL, MongoDB, BigQuery)에는 수집 설정이 없습니다. 이러한 파이프에 `settings get`을 실행하면 종료 코드 1로 종료되며 `clickhousectl cloud clickpipe get `를 안내합니다. 이 명령에서 sync interval과 pull batch 크기를 확인할 수 있습니다. * 파이프는 `Ready` 상태에 도달한 Reverse Private Endpoint만 사용할 수 있습니다. AWS PrivateLink 엔드포인트는 소스를 소유한 account에서 연결 요청이 수락될 때까지 `PendingAcceptance` 상태로 유지됩니다. Kafka 파이프는 `--reverse-private-endpoint-id`(반복 지정 가능)로 엔드포인트를 ID로 참조하며, Postgres 및 MySQL CDC 파이프는 엔드포인트의 `dnsNames` 중 하나를 `--host`로 전달합니다. * Google Cloud Pub/Sub 파이프는 제한 미리 보기 상태입니다. 파이프를 생성하기 전에 지원팀에 문의하여 조직에 해당 기능을 활성화하십시오. `--service-account-file`은 GCP service account JSON 키의 경로를 받으며, `-`를 지정하면 stdin에서 키를 읽습니다. 키를 인라인으로 지정하는 것은 허용되지 않으므로 프로세스 목록과 셸 기록에 노출되지 않습니다.

Postgres 서비스(베타)

[ClickHouse Cloud Postgres](/ko/products/managed-postgres/overview) 서비스를 생성하고 관리합니다. ```bash theme={null} # List Postgres services, optionally filtering client-side. # Filter keys: state, region, name, provider, isPrimary clickhousectl cloud postgres list clickhousectl cloud postgres list --filter state=running --filter isPrimary=true # Create a Postgres service clickhousectl cloud postgres create \ --name my-pg \ --region us-east-1 \ --size m7i.2xlarge \ --pg-version 18 # Get service details clickhousectl cloud postgres get # Update a service clickhousectl cloud postgres update --size m7i.4xlarge --add-tag env=prod # Reset the password (exactly one of --password or --generate) clickhousectl cloud postgres reset-password --generate # Runtime configuration (postgresql.conf + PgBouncer) and CA certificates. # config patch takes exactly one of --set (repeatable) or --file clickhousectl cloud postgres config get clickhousectl cloud postgres config patch --set max_connections=500 clickhousectl cloud postgres config replace --file config.json clickhousectl cloud postgres certs get # Read replicas, failover, and point-in-time restore clickhousectl cloud postgres read-replica create --name replica-1 clickhousectl cloud postgres promote --wait clickhousectl cloud postgres switchover --wait clickhousectl cloud postgres restore --name restored --restore-target 2026-04-16T12:00:00Z # Restart a service clickhousectl cloud postgres restart # Delete a service clickhousectl cloud postgres delete ``` 알아두어야 할 사항: * `--provider`의 기본값은 `aws`이며, `gcp`도 사용할 수 있습니다. GCP에서는 `c4-standard-4`와 같은 머신 크기를 지정합니다. `--size`는 CLI가 아니라 Cloud API에서 검사하므로, 지원되지 않는 크기는 서버에서만 거부됩니다. * 역할 변경은 최종적 일관성을 따르며, API는 `promote`와 `switchover`를 실제로 적용하기 전에 먼저 응답을 반환합니다. 따라서 종료 코드 0만으로는 역할이 변경되었다고 단정할 수 없습니다. 두 명령 모두 `--wait`를 지원하여 target이 새 역할을 보고할 때까지 폴링하며, `--wait-timeout `(기본값 300)으로 폴링 시간을 제한할 수 있습니다. 이전 프라이머리가 그 후 몇 분 동안 계속 `isPrimary=true`를 보고할 수 있으므로, `clickhousectl cloud postgres list --filter isPrimary=true`로 프라이머리 service가 정확히 하나인지 확인하십시오. * `postgres delete`는 `running`을 포함한 모든 state에서 동작하므로, service를 먼저 중지할 필요가 없습니다.

조직

```bash theme={null} clickhousectl cloud org list clickhousectl cloud org get clickhousectl cloud org update --name new-name clickhousectl cloud org prometheus clickhousectl cloud org usage --from-date 2026-08-01 --to-date 2026-08-31 ```

API Keys

```bash theme={null} clickhousectl cloud key list clickhousectl cloud key get clickhousectl cloud key create --name ci-key --role-id clickhousectl cloud key update clickhousectl cloud key delete ```

구성원 및 초대

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

활동 로그(Activity log)

```bash theme={null} clickhousectl cloud activity list --from-date 2026-08-01 --to-date 2026-08-31 clickhousectl cloud activity get ```

JSON 출력

`--json` 플래그를 사용하면 모든 cloud 명령의 응답을 JSON 포맷으로 받을 수 있습니다: ```bash theme={null} clickhousectl cloud service list --json ``` `org prometheus` 및 `service prometheus` 명령어는 예외입니다. 이 명령어들은 항상 raw Prometheus exposition 텍스트를 출력하며, `--json`은 별도 알림 없이 무시합니다.

로컬 개발

CLI는 로컬 ClickHouse 설치본, 로컬 서버, Docker 기반 로컬 Postgres 인스턴스도 관리합니다. 로컬 개발을 시작하려면 [clickhousectl (CLI)](/ko/get-started/setup/self-managed/clickhousectl) 페이지를 참조하십시오. ```bash theme={null} # Manage installed ClickHouse versions. install also accepts stable, lts, # a partial version like 25.12, an exact version, or a Postgres image # selector like postgres@18 clickhousectl local install latest clickhousectl local list clickhousectl local use clickhousectl local which clickhousectl local remove # Scaffold a project (.clickhouse/ plus clickhouse/ and postgres/ directories) clickhousectl local init # Manage local server instances (data persists in .clickhouse/servers/) clickhousectl local server start [name] clickhousectl local server list # --global lists servers across projects clickhousectl local server stop [name] clickhousectl local server stop-all clickhousectl local server remove [name] clickhousectl local server configs # named overlays for `server start --config` clickhousectl local server dotenv # Connect to a running server with clickhouse-client clickhousectl local client -q 'SELECT 1;' clickhousectl local client --host db.example.com --port 9000 --version 25.12 # Local Postgres instances (requires Docker) clickhousectl local postgres start --name clickhousectl local postgres client clickhousectl local postgres stop [name] clickhousectl local postgres stop-all clickhousectl local postgres remove [name] clickhousectl local postgres dotenv ``` 알아두어야 할 사항: * `local` 명령어는 프로젝트 범위로 동작합니다. 현재 작업 디렉터리 바로 아래의 `.clickhouse` 디렉터리만 사용하며, 상위 디렉터리는 탐색하지 않습니다. 실행하기 전에 프로젝트 루트로 이동하십시오. * `clickhousectl local use`는 `~/.local/bin/clickhouse`에 대한 심볼릭 링크도 생성하므로 `clickhouse client`, `clickhouse benchmark`, `clickhouse format` 같은 표준 하위 명령어를 바로 사용할 수 있습니다. 심볼릭 링크 생성을 건너뛰려면 `--no-global`을 전달하십시오. * `local remove`는 설치된 정확한 버전을 인수로 받습니다. 어떤 프로젝트에서든 실행 중인 서버가 사용하는 버전이거나 현재 기본값으로 지정된 버전은 제거하지 않습니다. `--force`를 사용하면 해당 서버를 중지하고 기본값과 전역 심볼릭 링크를 해제합니다. * 이름을 지정하지 않으면 `local server stop`은 `default`가 있을 경우 이를 중지하고, 없으면 알려진 유일한 서버를 중지합니다. 기본값이 아닌 서버가 여러 개 있으면 이름을 입력하도록 요구합니다. 이름 없이 실행한 `local server remove`는 기존 `default`만 선택하며, 사용자 정의 서버를 임의로 선택하지 않습니다. * `local client`는 직접 호스트/포트 모드에서 설치된 클라이언트 버전을 선택할 수 있도록 `-v`/`--version`을 지원하고, `-q`를 반복해 여러 쿼리를 지정할 수 있으며, `--queries-file`에는 여러 경로를 지정할 수 있습니다. `--query`와 `--queries-file`을 함께 사용하면 사용법 오류가 발생합니다. * `local postgres start`는 PostgreSQL이 연결을 수락할 때까지 대기하며, 대기 시간은 `--wait-timeout` 초(기본값 60, 최대 600)로 제한됩니다. `--port`를 생략하면 5432가 사용 가능할 때 이를 사용하고, 그렇지 않으면 포트를 자동으로 선택합니다. 명시적으로 요청한 포트가 이미 사용 중이면 거부됩니다.

기타 명령어

```bash theme={null} # Install the ClickHouse agent skills into supported coding agents clickhousectl skills --agent claude # Manage anonymous usage telemetry: command name, flag and argument names # (never their values). Opt out with DO_NOT_TRACK=1 clickhousectl telemetry status clickhousectl telemetry disable clickhousectl telemetry enable ```

요구 사항

* macOS (aarch64, x86\_64) 또는 Linux (aarch64, x86\_64) * Cloud 명령을 실행하려면 쓰기 액세스를 위한 [ClickHouse Cloud API Key](/ko/products/cloud/features/admin-features/api/openapi)가 필요합니다. OAuth 로그인은 읽기 전용입니다 * `clickhousectl local postgres`를 실행하려면 Docker가 필요합니다