clickhousectl

clickhousectl은 ClickHouse용 CLI로, 로컬과 클라우드 모두를 다룹니다. ClickHouse 버전 설치와 관리, 로컬 서버 실행, 쿼리 실행, ClickHouse Cloud 설정과 클러스터 생성, ClickPipes 관리 등이 가능해요.

출처: 문서

본문

clickhousectl은 ClickHouse용 CLI로, 로컬과 클라우드 모두를 다루는 도구예요.

clickhousectl로 할 수 있는 일:

로컬 ClickHouse 버전 설치 및 관리
로컬 ClickHouse 서버 실행 및 관리
로컬 Postgres 인스턴스 실행 및 관리
ClickHouse 서버에 대한 쿼리 실행
ClickHouse Cloud 설정 및 클라우드 관리형 ClickHouse 클러스터 생성
ClickHouse Cloud Postgres 서비스 생성 및 관리
ClickHouse Cloud 리소스 관리
데이터 인제스트용 ClickPipes 생성 및 관리 (S3, Kafka, Kinesis, Postgres, MySQL, MongoDB, BigQuery)
지원되는 코딩 에이전트에 공식 ClickHouse agent skills 설치
로컬 ClickHouse 개발을 클라우드로 푸시

clickhousectl은 인간과 AI 에이전트가 ClickHouse로 개발하는 데 도움을 줍니다.

설치 (Installation)

빠른 설치 (Quick install)

curl https://clickhouse.com/cli | sh

설치 스크립트는 여러분의 OS에 맞는 올바른 버전을 다운로드해 ~/.local/bin/clickhousectl에 설치해요. 편의를 위해 chctl 별칭도 자동으로 생성돼요.

요구 사항 (Requirements)

macOS (aarch64, x86_64) 또는 Linux (aarch64, x86_64)
클라우드 명령은 ClickHouse Cloud API 키가 필요해요

로컬 (Local)

ClickHouse 버전 설치 및 관리 (Installing and managing ClickHouse versions)

clickhousectl은 builds.clickhouse.com에서 ClickHouse 바이너리를 다운로드하며, 그런 빌드를 거기서 사용할 수 없을 때 packages.clickhouse.com(Linux) 또는 GitHub releases(macOS)로 폴백해요.

# 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는 선택한 버전의 바이너리를 가리키는 ~/.local/bin/clickhouse 심링크도 만들어서, 일반 clickhouse 명령(예: clickhouse local, clickhouse client)이 PATH에 있게 해요. 건너뛰려면 --no-global을 전달하세요. 그 경로에 이미 일반 파일이 있으면 경고와 함께 남겨둬요. 활성 기본 버전의 local remove는 심링크도 지워요.

ClickHouse 바이너리 저장소 (ClickHouse binary storage)

ClickHouse 바이너리는 전역 저장소에 저장되므로 여러 프로젝트가 저장 공간을 중복하지 않고 사용할 수 있어요. 바이너리는 ~/.clickhouse/에 저장돼요:

~/.clickhouse/
├── versions/
│   └── 26.5.2.39/
│       └── clickhouse
└── default              # tracks the active version

프로젝트 초기화 (Initializing a project)

clickhousectl local init

init은 현재 작업 디렉터리를 ClickHouse와 Postgres 프로젝트 파일을 위한 표준 폴더 구조로 부트스트랩해요. 선택 사항이며, 원한다면 자신만의 폴더 구조를 사용해도 좋아요.

다음 구조를 만들어요:

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

쿼리 실행 (Running queries)

# 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

ClickHouse 서버 생성 및 관리 (Creating and managing ClickHouse servers)

ClickHouse 서버 인스턴스를 시작하고 관리해요. 각 서버는 .clickhouse/servers/<name>/data/에 자체적인 격리된 데이터 디렉터리를 가져요.

# 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

서버 이름: --name 없이 첫 서버는 "default"라고 불려요. "default"가 이미 실행 중이면 임의의 이름(예: "bold-crane")이 생성돼요. 반복해서 시작/중지할 수 있는 안정적인 신원을 원하면 --name을 사용하세요.

포트: 기본값은 HTTP 8123과 TCP 9000이에요. 이미 사용 중이면 사용 가능한 포트가 자동 할당되어 출력에 표시돼요. 명시적 포트를 설정하려면 --http-port와 --tcp-port를 사용하세요.

전역 서버 관리: list, stop, stop-all에서 --global을 사용해 시스템 전반의 모든 프로젝트에 걸쳐 작업해요. server list --global은 Project 열과 함께 각 디렉터리가 속한 프로젝트를 나타내는 모든 실행 중 ClickHouse 서버를 보여줘요.

로컬 서버용 사용자 정의 설정 파일 (Custom config files for local servers)

로컬 서버는 합리적인 기본값으로 시작하지만, 때로는 설정을 바꿔야 할 때가 있어요. ~/.clickhouse/configs/에 설정 파일을 넣고 서버를 시작할 때 이름으로 적용하세요:

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

명명된 파일은 ClickHouse의 내장 기본값 위에 겹쳐져서(config.d를 통해) 적용되므로, 바꾸려는 설정만 담으면 되고 전체 설정을 재현할 필요가 없어요. 파일은 .xml, .yaml, .yml이 될 수 있고 확장자 있든 없든 이름으로 참조할 수 있어요.

프로젝트 로컬 데이터 디렉터리 (Project-local data directory)

모든 서버 데이터는 프로젝트 디렉터리의 .clickhouse/ 안에 살아 있어요:

.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

각 명명된 서버는 자신의 데이터 디렉터리를 가지므로 서버는 서로 완전히 격리돼요. 데이터는 재시작 사이에 유지돼요. 이름으로 서버를 중지하고 시작해 이어갈 수 있어요. clickhousectl local server remove <name>으로 서버 데이터를 영구 삭제해요.

로컬 Postgres 실행 (Running local Postgres)

ClickHouse 외에도 clickhousectl은 로컬 Postgres 인스턴스를 실행하고 관리할 수 있어요. 로컬 Postgres는 Docker 기반이므로 Docker가 설치되어 실행 중이어야 해요. 각 인스턴스는 이름과 주요 버전으로 식별되므로, 여러 Postgres 버전이 별도의 데이터 디렉터리와 함께 나란히 실행될 수 있어요.

# 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

인증 (Authentication)

API 키(권장) 또는 OAuth(브라우저 기반)로 ClickHouse Cloud에 인증해요.

ClickHouse Cloud 계정이 아직 없으면 clickhousectl cloud auth signup이 브라우저에서 가입 페이지를 열어요.

API 키/시크릿 (API key/secret, 권장)

API 키는 특히 AI 에이전트에서 CLI를 구동할 때 권장되는 인증 방식이에요. 범위가 지정된 API 키를 만들어 선택한 권한만(읽기 전용 또는 읽기/쓰기) 부여할 수 있고, 각 키는 단일 조직에 묶여요. 이는 CLI에 접근 권한을 주는 안전하고 최소 권한의 방법이에요.

# Non-interactive (CI-friendly)
clickhousectl cloud auth login --api-key YOUR_KEY --api-secret YOUR_SECRET

# Interactive prompt
clickhousectl cloud auth login --interactive

자격 증명은 .clickhouse/credentials.json(프로젝트 로컬)에 저장돼요.

환경 변수를 사용할 수도 있어요. 세션에서 내보내거나:

export CLICKHOUSE_CLOUD_API_KEY=your-key
export CLICKHOUSE_CLOUD_API_SECRET=your-secret

또는 현재 작업 디렉터리의 .env 파일에 두거나:

CLICKHOUSE_CLOUD_API_KEY=your-key
CLICKHOUSE_CLOUD_API_SECRET=your-secret

또는 어떤 명령에서든 플래그로 직접 자격 증명을 전달:

clickhousectl cloud --api-key KEY --api-secret SECRET ...

OAuth 로그인 (OAuth login)

clickhousectl cloud auth login

이것은 OAuth 장치 흐름으로 브라우저에서 인증을 엽니다. 토큰은 .clickhouse/tokens.json(프로젝트 로컬)에 저장돼요.

참고: OAuth 접근은 현재 읽기 전용이며, 여러분이 속한 모든 조직에 대한 접근을 부여해요. 쓰기 접근이 필요하거나 CLI를 단일 조직으로 한정하려면 범위가 지정된 API 키를 만드세요.

인증 상태 및 로그아웃 (Auth status and logout)

clickhousectl cloud auth status    # Show current auth state
clickhousectl cloud auth logout    # Clear all saved credentials (credentials.json & tokens.json)

자격 증명 해석 순서: CLI 플래그 > .clickhouse/credentials.json > 내보낸 환경 변수 > .env 파일 > OAuth 토큰.

어떤 자격 증명 소스가 사용됐는지 디버깅하기

cloud 명령에 --debug를 전달하면 명령 실행 전에 해석된 자격 증명 소스(및 API URL)를 stderr로 출력해요.

clickhousectl cloud --debug service list
# [debug] auth source: credentials file (.clickhouse/credentials.json)
# [debug] api url: https://api.clickhouse.cloud/v1
# ... normal output ...

클라우드 (Cloud)

API를 통해 ClickHouse Cloud 서비스를 관리해요.

조직 (Organizations)

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

서비스 (Services)

# 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

서비스 생성 옵션 (Service create options)

옵션	설명
`--name`	서비스 이름 (필수)
`--provider`	클라우드 제공자: `aws`, `gcp`, `azure` (기본: `aws`)
`--region`	리전 (기본: `us-east-1`)
`--min-replica-memory-gb`	복제본당 최소 메모리 GB (8-356, 4의 배수)
`--max-replica-memory-gb`	복제본당 최대 메모리 GB (8-356, 4의 배수)
`--num-replicas`	복제본 수 (1-20)
`--idle-scaling`	0으로 스케일 허용 (기본: `true`)
`--idle-timeout-minutes`	최소 유휴 타임아웃(분) (>= 5)
`--ip-allow`	허용할 IP CIDR (반복 가능, 기본: `0.0.0.0/0`)
`--backup-id`	복원할 백업 ID
`--release-channel`	릴리스 채널: `slow`, `default`, `fast`
`--data-warehouse-id`	데이터 웨어하우스 ID (읽기 복제본용)
`--readonly`	서비스를 읽기 전용으로 만들기
`--encryption-key`	고객 디스크 암호화 키
`--encryption-role`	디스크 암호화용 Role ARN
`--enable-tde`	투명 데이터 암호화 활성화
`--compliance-type`	규정 준수: `hipaa`, `pci`
`--profile`	인스턴스 프로필 (엔터프라이즈)
`--tag`	GA 서비스 태그 첨부 (`key` 또는 `key=value`)
`--enable-endpoint` / `--disable-endpoint`	GA 서비스 엔드포인트 토글 (현재 `mysql`)
`--private-preview-terms-checked`	필요할 때 비공개 프리뷰 조건 수락
`--enable-core-dumps`	서비스 코어 덤프 수집 활성화 또는 비활성화

Query API 인증 모드 (Query API auth modes)

cloud service query는 clickhouse 바이너리도 서비스 비밀번호도 없이 HTTP로 클라우드 서비스에 대해 SQL을 실행하는 표준적인 방법이에요. 두 자격 증명 모드 모두에서 동작해요:

API 키 인증 (읽기 + 쓰기 SQL): 저장된 키 없이 cloud service query가 서비스에 처음 실행되면, 그 서비스에 Query API 엔드포인트를 프로비저닝하고 그것에 바인딩된 전용 API 키를 만들어요. 키(keyId, keySecret, endpointId)는 .clickhouse/credentials.json의 service_query_keys.<service-id> 아래에 저장돼요. 키는 단일 서비스로 범위가 지정되므로 그 서비스에 대해 읽기와 쓰기(SELECT, INSERT, DDL)를 할 수 있지만 조직의 다른 어떤 서비스에도 닿지 못해요. 프로비저닝 대신 실패하게 하려면 --no-auto-enable을 전달하세요.
OAuth (cloud auth login): 쿼리는 웹 SQL 콘솔처럼 여러분 자신의 신원으로 실행돼요. OAuth를 사용할 때 서비스에 대한 여러분의 SQL 권한은 읽기 전용이에요. Query API 키는 프로비저닝되거나 저장되지 않아요. --no-auto-enable은 이 모드에서 효과가 없어요.

idle 상태의 서비스를 쿼리하면 두 인증 모드 모두에서 자동으로 깨어나요(첫 쿼리는 1분 걸릴 수 있어요). 중지된 서비스는 결코 깨어나지 않아요. 쿼리는 cloud service start를 실행하라는 힌트와 함께 실패해요. 파생된 Query API 호스트를 재정의하려면 CLICKHOUSE_CLOUD_QUERY_HOST를 설정하세요.

쿼리 엔드포인트 관리 (Query endpoint management)

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>

프라이빗 엔드포인트 관리 (Private endpoint management)

clickhousectl cloud service private-endpoint create <service-id> --endpoint-id vpce-123
clickhousectl cloud service private-endpoint get-config <service-id>

백업 구성 (Backup configuration)

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

Postgres 서비스 (Postgres services)

clickhousectl은 위의 ClickHouse 서비스 명령을 반영해 ClickHouse Cloud Postgres 서비스도 생성하고 관리할 수 있어요. GCP는 비공개 프리뷰 상태이며, GCP 리전과 인스턴스 크기와 함께 --provider gcp를 전달하세요.

# List and inspect
clickhousectl cloud postgres list
clickhousectl cloud postgres list --filter state=running
clickhousectl cloud postgres get <pg-id>

# Create a service on AWS (the default provider)
clickhousectl cloud postgres create \
  --name my-pg \
  --region us-east-1 \
  --size m7i.2xlarge \
  --pg-version 17 \
  --ha-type sync

# Create a service on GCP (private preview); region and size use GCP names
clickhousectl cloud postgres create \
  --name my-pg \
  --provider gcp \
  --region us-central1 \
  --size c4-standard-4 \
  --pg-version 18

# 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

Postgres 서비스 생성 옵션 (Postgres service create options)

옵션	설명
`--name`	서비스 이름 (필수)
`--region`	리전, 예: AWS의 `us-east-1` 또는 GCP의 `us-central1` (필수)
`--size`	인스턴스 크기, 예: AWS의 `m7i.2xlarge` 또는 GCP의 `c4-standard-4` (필수)
`--provider`	클라우드 제공자: `aws`, `gcp` (기본: `aws`)
`--pg-version`	주요 버전: `18`, `17`
`--ha-type`	고가용성: `none`, `async`, `sync`
`--tag`	리소스 태그 `key` 또는 `key=value` (반복 가능)
`--pg-config-file`	`PgConfig` 객체가 있는 JSON 파일 경로
`--pg-bouncer-config-file`	`PgBouncerConfig` 객체가 있는 JSON 파일 경로

백업 (Backups)

clickhousectl cloud backup list <service-id>
clickhousectl cloud backup get <service-id> <backup-id>

ClickPipes

외부 소스에서 ClickHouse Cloud로 데이터를 인제스트하는 ClickPipes를 관리해요.

# 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

ClickPipes 만들기 (Creating ClickPipes)

각 소스 유형은 clickpipe create 아래에 고유한 하위 명령이 있어요:

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

소스 유형별 옵션 전체 목록은 clickhousectl cloud clickpipe create <source> --help를 사용하세요.

멤버 (Members)

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>

초대 (Invitations)

clickhousectl cloud invitation list
clickhousectl cloud invitation create --email [email protected] --role-id <role-id>
clickhousectl cloud invitation get <invitation-id>
clickhousectl cloud invitation delete <invitation-id>

키 (Keys)

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>

활동 (Activity)

clickhousectl cloud activity list --from-date 2024-01-01 --to-date 2024-12-31
clickhousectl cloud activity get <activity-id>

JSON 출력 (JSON output)

--json 플래그를 사용해 JSON 형식의 응답을 출력해요.

clickhousectl cloud --json service list
clickhousectl cloud --json service get <service-id>

clickhousectl은 코딩 에이전트 컨텍스트(Claude Code, Cursor, Codex, Gemini CLI, Goose, Devin, 그리고 표준 AGENT 환경 변수를 설정하는 어떤 도구)를 자동 감지하고, --json을 설정하지 않아도 stdout으로 JSON을 자동으로 내보내요.

종료 코드 (Exit codes)

종료 코드는 gh CLI 규칙을 따릅니다:

코드	의미
`0`	성공
`1`	오류 (아래에 분류되지 않은 모든 것)
`2`	취소됨 (사용자가 중단)
`4`	인증 필요 (자격 증명 없음, 401/403, OAuth 전용 쓰기)

스킬 (Skills)

ClickHouse/agent-skills에서 공식 ClickHouse Agent Skills를 설치해요.

# 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

비대화형 플래그 (Non-interactive flags)

플래그	설명
`--agent <name>`	특정 에이전트용 스킬 설치 (반복 가능)
`--global`	전역 범위 사용; 생략하면 프로젝트 범위 사용
`--all`	지원되는 모든 에이전트용 스킬 설치
`--detected-only`	시스템에서 감지된 지원 에이전트용 스킬 설치

자체 업데이트 (Self-update)

clickhousectl은 최신 릴리스로 자체 업데이트할 수 있어요:

# Update to the latest version
clickhousectl update

# Check for updates without installing
clickhousectl update --check

CLI는 백그라운드에서 업데이트도 확인하고(24시간에 최대 한 번) 최신 버전이 있으면 알림을 표시해요.

텔레메트리 (Telemetry)

clickhousectl은 CLI가 어떻게 사용되는지 이해하기 위해 익명 사용 텔레메트리를 수집해요. 기본적으로 활성화되어 있지만, 통지받기 전에는 아무것도 보내지 않아요. 첫 실행에서 CLI는 무엇을 수집하고 어떻게 끄는지 설명하는 알림을 출력하며 아무것도 보내지 않아요. 수집은 후속 실행에서만 시작되므로, 어떤 것이든 수집되기 전에 항상 거부할 기회가 있어요.

각 이벤트에는 다음만 포함돼요:

실행된 명령(예: local start)과 사용된 플래그의 이름 — 결코 플래그 값, 위치 인수 또는 다른 사용자가 제공한 입력은 아니므로 쿼리, 테이블 이름, 자격 증명, 파일 경로는 절대 수집되지 않아요
종료 코드(예: 0, 1, 2, 4)와 결과(예: ok, error, cancelled)
잘못 입력된 명령의 경우 CLI가 보여준 "did you mean" 제안 — 실제 명령이나 플래그 이름과 정확히 일치할 때만 기록되므로 여러분이 입력한 내용을 절대 포함할 수 없어요
clickhousectl 버전, OS, 아키텍처, 그리고 AI 에이전트가 CLI를 호출했는지(그리고 어떤 에이전트인지) 또는 CI에서 호출했는지 여부

텔레메트리는 완전히 익명이에요. 개인 데이터는 수집되지 않으며 기기나 설치 식별자도 없어요.

텔레메트리를 끄려면 다음 중 하나:

clickhousectl telemetry disable 실행 (enable로 다시 켜고 status로 확인)
DO_NOT_TRACK=1 환경 변수 설정

CHCTL_TELEMETRY_DEBUG=1을 설정하면 아무것도 보내지 않고 정확한 페이로드를 stderr로 출력해요.

clickhousectl

clickhousectl

본문

설치 (Installation)

빠른 설치 (Quick install)

요구 사항 (Requirements)

로컬 (Local)

ClickHouse 버전 설치 및 관리 (Installing and managing ClickHouse versions)

ClickHouse 바이너리 저장소 (ClickHouse binary storage)

프로젝트 초기화 (Initializing a project)

쿼리 실행 (Running queries)

ClickHouse 서버 생성 및 관리 (Creating and managing ClickHouse servers)

로컬 서버용 사용자 정의 설정 파일 (Custom config files for local servers)

프로젝트 로컬 데이터 디렉터리 (Project-local data directory)

로컬 Postgres 실행 (Running local Postgres)

인증 (Authentication)

API 키/시크릿 (API key/secret, 권장)

OAuth 로그인 (OAuth login)

인증 상태 및 로그아웃 (Auth status and logout)

어떤 자격 증명 소스가 사용됐는지 디버깅하기

클라우드 (Cloud)

조직 (Organizations)

서비스 (Services)

서비스 생성 옵션 (Service create options)

Query API 인증 모드 (Query API auth modes)

쿼리 엔드포인트 관리 (Query endpoint management)

프라이빗 엔드포인트 관리 (Private endpoint management)

백업 구성 (Backup configuration)

Postgres 서비스 (Postgres services)

Postgres 서비스 생성 옵션 (Postgres service create options)

백업 (Backups)

ClickPipes

ClickPipes 만들기 (Creating ClickPipes)

멤버 (Members)

초대 (Invitations)

키 (Keys)

활동 (Activity)

JSON 출력 (JSON output)

종료 코드 (Exit codes)

스킬 (Skills)

비대화형 플래그 (Non-interactive flags)

자체 업데이트 (Self-update)

텔레메트리 (Telemetry)

더 알아보기 (Learn more)