메인 콘텐츠로 건너뛰기
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 스킬 설치
  • 로컬 ClickHouse 개발 환경을 클라우드로 푸시
clickhousectl은 사람과 AI 에이전트가 ClickHouse로 개발할 수 있도록 지원합니다.

​
설치

​
빠른 설치

curl https://clickhouse.com/cli | sh
설치 스크립트는 사용 중인 OS에 맞는 버전을 다운로드한 뒤 ~/.local/bin/clickhousectl에 설치합니다. 편의를 위해 chctl alias도 자동으로 생성됩니다.

​
요구 사항

​
로컬

​
ClickHouse 버전 설치 및 관리

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는 선택한 버전의 binary를 가리키는 ~/.local/bin/clickhouse 심볼릭 링크도 생성하므로, 일반 clickhouse 명령(예: clickhouse local, clickhouse client)을 PATH에서 사용할 수 있습니다. 이 동작을 건너뛰려면 --no-global을 전달하세요. 해당 경로에 일반 파일이 이미 있으면 경고를 표시하고 그대로 둡니다. 활성 기본 버전에 local remove를 실행하면 심볼릭 링크도 제거됩니다.

​
ClickHouse 실행 파일 저장소

ClickHouse 실행 파일은 저장 공간을 중복하지 않으면서 여러 프로젝트에서 사용할 수 있도록 전역 리포지토리에 저장됩니다. 실행 파일은 ~/.clickhouse/에 저장됩니다: 
~/.clickhouse/
├── versions/
│   └── 26.5.2.39/
│       └── clickhouse
└── default              # tracks the active version

​
프로젝트 초기화

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

​
쿼리 실행

# clickhouse-client로 실행 중인 서버에 연결
clickhousectl local client                           # "default" 서버에 연결
clickhousectl local client --name dev                # "dev" 서버에 연결
clickhousectl local client --query "SHOW DATABASES"  # 쿼리 실행
clickhousectl local client --queries-file schema.sql # 파일에서 쿼리 실행
clickhousectl local client --host remote-host --port 9000  # 특정 호스트/포트에 연결

​
ClickHouse 서버 생성 및 관리

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을 지정하지 않으면 첫 번째 server의 이름은 “default”입니다. “default”가 이미 실행 중이면 임의의 이름이 생성됩니다(예: “bold-crane”). 반복해서 시작하거나 중지할 수 있는 안정적인 식별자가 필요하면 --name을 사용하세요. 포트: 기본 포트는 HTTP 8123과 TCP 9000입니다. 이 포트들이 이미 사용 중이면 사용 가능한 포트가 자동으로 할당되고 출력에 표시됩니다. 포트를 명시적으로 지정하려면 --http-port와 --tcp-port를 사용하세요. 전역 서버 관리: 시스템 전체의 모든 프로젝트에 걸쳐 작업하려면 list, stop, stop-all과 함께 --global을 사용하세요. server list --global은 실행 중인 모든 ClickHouse 서버를 표시하며, 각 서버가 어느 디렉터리에 속하는지 나타내는 Project 컬럼이 함께 표시됩니다.

​
로컬 서버용 사용자 지정 구성 파일

로컬 서버는 기본적으로 적절한 설정으로 시작되지만, 때로는 일부 설정을 변경해야 할 수 있습니다. 구성 파일을 ~/.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 형식일 수 있으며, 확장자를 포함하거나 제외한 파일 이름으로 참조할 수 있습니다.

​
프로젝트 로컬 데이터 디렉터리

모든 서버 데이터는 프로젝트 디렉터리 내 .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 실행

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

​
인증

API Key(권장) 또는 OAuth(브라우저 기반)를 사용하여 ClickHouse Cloud에 인증합니다. 아직 ClickHouse Cloud 계정이 없다면, clickhousectl cloud auth signup를 실행하면 브라우저에서 가입 페이지가 열립니다.

​
API Key/Secret (권장)

API Key는 인증에 권장되는 방식이며, 특히 AI Agent가 CLI를 구동할 때 더욱 적합합니다. 선택한 권한만 부여하는(읽기 전용 또는 읽기/쓰기) 범위가 지정된 API Key를 생성할 수 있으며, 각 키는 하나의 조직에 연결됩니다. 따라서 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한 환경 변수도 사용할 수 있습니다: 
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 로그인

clickhousectl cloud auth login
브라우저가 열리고 OAuth 디바이스 흐름을 통해 인증이 진행됩니다. 토큰은 .clickhouse/tokens.json에 저장됩니다(프로젝트 로컬).
OAuth 액세스는 현재 읽기 전용이며 속한 모든 조직에 대한 액세스를 제공합니다. 쓰기 액세스가 필요하거나 CLI의 범위를 단일 조직으로 제한하려면 대신 범위가 지정된 API Key를 생성하세요.

​
인증 상태 및 로그아웃

clickhousectl cloud auth status    # Show current auth state
clickhousectl cloud auth logout    # Clear all saved credentials (credentials.json & tokens.json)
자격 증명 확인 우선순위: CLI 플래그 > .clickhouse/credentials.json > export로 설정된 환경 변수 > .env 파일 > OAuth 토큰.

​
사용된 자격 증명 소스 디버깅

명령이 실행되기 전에 선택된 자격 증명 소스(및 API URL)를 stderr에 출력하려면 모든 cloud 명령에 --debug를 전달하세요. 
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 서비스를 관리합니다.

​
조직

clickhousectl cloud org list              # 조직 목록 조회
clickhousectl cloud org get <org-id>      # 조직 상세 정보 조회
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

​
서비스

# 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

​
서비스 생성 옵션

옵션설명
--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-scaling0까지 스케일링 허용 (기본값: true)
--idle-timeout-minutes최소 유휴 timeout(분) (>= 5)
--ip-allow허용할 IP CIDR (반복 지정 가능, 기본값: 0.0.0.0/0)
--backup-id복원할 Backup ID
--release-channel릴리스 채널: slow, default, fast
--data-warehouse-id데이터 warehouse ID (읽기 레플리카용)
--readonly서비스를 읽기 전용으로 설정
--encryption-key고객 디스크 암호화 키
--encryption-role디스크 암호화를 위한 Role ARN
--enable-tdeTransparent Data Encryption 활성화
--compliance-type컴플라이언스: hipaa, pci
--profile인스턴스 profile (enterprise)
--tag일반 제공 서비스 tag 연결 (key 또는 key=value)
--enable-endpoint / --disable-endpoint일반 제공 서비스 endpoints 토글(현재 mysql)
--private-preview-terms-checked필요 시 비공개 프리뷰 약관 동의
--enable-core-dumps서비스 코어 dump 수집 활성화 또는 비활성화

​
Query API 인증 모드

cloud service query는 clickhouse 바이너리나 서비스 비밀번호 없이 HTTP를 통해 cloud service에 SQL을 실행하는 기본 방식입니다. 이 명령은 두 가지 자격 증명 모드를 모두 지원합니다.
  • API Key 인증 (읽기 + 쓰기 SQL): 저장된 키가 없는 서비스에 대해 cloud service query를 처음 실행하면, 해당 서비스용 Query API 엔드포인트를 Provisioning하고 여기에 연결된 전용 API Key를 생성합니다. 이 키(keyId, keySecret, endpointId)는 .clickhouse/credentials.json의 service_query_keys.<service-id> 아래에 저장됩니다. 이 키는 단일 서비스 범위로 제한되므로 해당 서비스에서는 읽기와 쓰기(SELECT, INSERT, DDL)가 가능하지만, 조직 내 다른 서비스에는 접근할 수 없습니다. Provisioning하지 않고 실패하게 하려면 --no-auto-enable을 지정하십시오.
  • OAuth (cloud auth login): 쿼리는 웹 SQL 콘솔과 마찬가지로 사용자 본인의 아이덴티티로 실행됩니다. OAuth를 사용할 때 서비스에 대한 SQL 권한은 읽기 전용입니다. Query API Key는 Provisioning되거나 저장되지 않습니다. 이 모드에서는 --no-auto-enable이 적용되지 않습니다.
두 인증 모드 모두에서 idled 상태인 서비스를 쿼리하면 자동으로 다시 활성화됩니다(첫 번째 쿼리는 1분 정도 걸릴 수 있습니다). 중지된 서비스는 자동으로 다시 활성화되지 않으며, 쿼리는 cloud service start를 실행하라는 안내와 함께 실패합니다. 파생된 Query API host를 재정의하려면 CLICKHOUSE_CLOUD_QUERY_HOST를 설정하십시오.

​
쿼리 엔드포인트 관리

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

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

​
Backup 구성

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 서비스

clickhousectl로도 위의 ClickHouse 서비스 명령과 동일하게 ClickHouse Cloud Postgres 서비스를 생성하고 관리할 수 있습니다. 
# 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

​
Postgres 서비스 생성 옵션

옵션설명
--name서비스 이름(필수)
--region리전(예: us-east-1, 필수)
--size인스턴스 크기(예: m7i.2xlarge, 필수)
--provider클라우드 제공업체(기본값: aws)
--pg-version주 버전: 18, 17
--ha-type고가용성: none, async, sync
--tag리소스 태그 key 또는 key=value(반복 지정 가능)
--pg-config-filePgConfig 객체가 포함된 JSON 파일 경로
--pg-bouncer-config-filePgBouncerConfig 객체가 포함된 JSON 파일 경로

​
백업

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

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 명령으로 확인하십시오.

​
구성원

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>

​
초대

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>

​
키

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>

​
활동

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

​
JSON 출력

JSON 형식으로 응답을 출력하려면 --json 플래그를 사용하세요. 
clickhousectl cloud --json service list
clickhousectl cloud --json service get <service-id>
clickhousectl은 코딩 에이전트 Context(Claude Code, Cursor, Codex, Gemini CLI, Goose, Devin, 및 표준 AGENT env var를 설정하는 모든 도구)를 자동으로 감지하고, --json을 설정하지 않아도 JSON을 stdout으로 자동 출력합니다.

​
종료 코드

종료 코드는 gh CLI 관례를 따릅니다:
코드의미
0성공
1오류 (아래에 분류되지 않은 모든 경우)
2취소됨 (사용자가 중단함)
4인증 필요 (자격 증명 없음, 401/403, OAuth 전용 쓰기 작업)

​
Skills

ClickHouse/agent-skills에서 공식 ClickHouse Agent Skills를 설치하세요. 
# 기본값: 사람을 위한 대화형 모드, 범위 선택 후 에이전트 선택
clickhousectl skills

# 비대화형: 지원되는 모든 프로젝트 로컬 에이전트 폴더에 설치
clickhousectl skills --all

# 비대화형: 감지된 에이전트에만 설치
clickhousectl skills --detected-only

# 비대화형: 지원되는 모든 전역 에이전트 폴더에 설치
clickhousectl skills --global --all

# 비대화형: 특정 프로젝트 로컬 에이전트에 설치
clickhousectl skills --agent claude --agent codex

​
비대화형 플래그

플래그설명
--agent <name>특정 에이전트용 Skills를 설치합니다(여러 번 지정 가능)
--global전역 범위를 사용합니다. 생략하면 프로젝트 범위를 사용합니다
--all지원되는 모든 에이전트용 Skills를 설치합니다
--detected-only시스템에서 감지된 지원 에이전트용 Skills를 설치합니다

​
자체 업데이트

clickhousectl 자체를 최신 릴리스로 업데이트할 수 있습니다: 
# Update to the latest version
clickhousectl update

# Check for updates without installing
clickhousectl update --check
CLI는 백그라운드에서 업데이트를 확인하며(24시간에 최대 1회), 최신 버전을 사용할 수 있으면 알림을 표시합니다.
마지막 수정일 2026년 6월 25일