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

> 로컬 및 클라우드용 ClickHouse CLI인 clickhousectl 문서

# clickhousectl

`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로 개발할 수 있도록 지원합니다.

<div id="installation">
  ## 설치
</div>

<div id="quick-install">
  ### 빠른 설치
</div>

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

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

<div id="requirements">
  ## 요구 사항
</div>

* macOS (aarch64, x86\_64) 또는 Linux (aarch64, x86\_64)
* Cloud 명령에는 [ClickHouse Cloud API Key](/ko/products/cloud/features/admin-features/api/api-overview)가 필요합니다

<div id="local">
  ## 로컬
</div>

<div id="installing-versions">
  ### ClickHouse 버전 설치 및 관리
</div>

`clickhousectl`은 `builds.clickhouse.com`에서 ClickHouse 바이너리를 다운로드하며, 해당 위치에서 빌드를 사용할 수 없으면 `packages.clickhouse.com`(Linux) 또는 [GitHub releases](https://github.com/ClickHouse/ClickHouse/releases)(macOS)에서 대신 다운로드합니다.

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

<div id="binary-storage">
  #### ClickHouse 실행 파일 저장소
</div>

ClickHouse 실행 파일은 저장 공간을 중복하지 않으면서 여러 프로젝트에서 사용할 수 있도록 전역 리포지토리에 저장됩니다. 실행 파일은 `~/.clickhouse/`에 저장됩니다:

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

<div id="initializing-project">
  ### 프로젝트 초기화
</div>

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

`init`은 현재 작업 디렉터리에 ClickHouse 및 Postgres 프로젝트 파일을 위한 표준 폴더 구조를 설정합니다. 이 작업은 선택 사항이므로, 필요하면 자체 폴더 구조를 사용해도 됩니다.

다음과 같은 구조가 생성됩니다:

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

<div id="running-queries">
  ### 쿼리 실행
</div>

```bash theme={null}
# 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  # 특정 호스트/포트에 연결
```

<div id="managing-servers">
  ### ClickHouse 서버 생성 및 관리
</div>

ClickHouse 서버 인스턴스를 시작하고 관리합니다. 각 서버에는 `.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
```

**서버 이름 지정:** `--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 컬럼이 함께 표시됩니다.

<div id="custom-config-files">
  #### 로컬 서버용 사용자 지정 구성 파일
</div>

로컬 서버는 기본적으로 적절한 설정으로 시작되지만, 때로는 일부 설정을 변경해야 할 수 있습니다. 구성 파일을 `~/.clickhouse/configs/`에 넣고 서버를 시작할 때 이름으로 적용하세요:

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

지정한 파일은 **ClickHouse에 내장된 기본 설정 위에 덮어써집니다** (`config.d`를 통해). 따라서 변경하려는 설정만 포함하면 되며, 전체 구성을 다시 작성할 필요는 없습니다. 파일은 `.xml`, `.yaml` 또는 `.yml` 형식일 수 있으며, 확장자를 포함하거나 제외한 파일 이름으로 참조할 수 있습니다.

<div id="project-local-data">
  #### 프로젝트 로컬 데이터 디렉터리
</div>

모든 서버 데이터는 프로젝트 디렉터리 내 `.clickhouse/`에 저장됩니다:

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

이름이 지정된 각 서버는 자체 데이터 디렉터리를 사용하므로 서버끼리는 완전히 격리됩니다. 데이터는 재시작 후에도 유지됩니다. 서버 이름으로 서버를 중지했다가 다시 시작하면 중단한 지점부터 작업을 이어갈 수 있습니다. 서버 데이터를 영구적으로 삭제하려면 `clickhousectl local server remove <name>`를 사용하십시오.

<div id="local-postgres">
  ### 로컬 Postgres 실행
</div>

ClickHouse뿐만 아니라 `clickhousectl`로 로컬 Postgres 인스턴스도 실행하고 관리할 수 있습니다. 로컬 Postgres는 Docker를 기반으로 하므로 Docker가 설치되어 있고 실행 중이어야 합니다. 각 인스턴스는 이름과 주 버전으로 식별되므로 여러 Postgres 버전을 각각 별도의 데이터 디렉터리로 나란히 실행할 수 있습니다.

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

<div id="authentication">
  ## 인증
</div>

API Key(권장) 또는 OAuth(브라우저 기반)를 사용하여 ClickHouse Cloud에 인증합니다.

아직 ClickHouse Cloud 계정이 없다면, `clickhousectl cloud auth signup`를 실행하면 브라우저에서 가입 페이지가 열립니다.

<div id="api-key">
  ### API Key/Secret (권장)
</div>

API Key는 인증에 권장되는 방식이며, 특히 AI Agent가 CLI를 구동할 때 더욱 적합합니다. 선택한 권한만 부여하는(읽기 전용 또는 읽기/쓰기) [범위가 지정된 API Key를 생성](/ko/products/cloud/features/admin-features/api/openapi)할 수 있으며, 각 키는 하나의 조직에 연결됩니다. 따라서 CLI에 안전하게 액세스 권한을 부여할 수 있는 최소 권한 방식입니다.

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

자격 증명은 `.clickhouse/credentials.json`(프로젝트 로컬)에 저장됩니다.

세션에서 export한 환경 변수도 사용할 수 있습니다:

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

또는 현재 작업 디렉터리의 `.env` 파일에 넣을 수 있습니다:

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

또는 어떤 명령에서든 플래그로 자격 증명을 직접 전달할 수 있습니다:

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

<div id="oauth-login">
  ### OAuth 로그인
</div>

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

브라우저가 열리고 OAuth 디바이스 흐름을 통해 인증이 진행됩니다. 토큰은 `.clickhouse/tokens.json`에 저장됩니다(프로젝트 로컬).

<Note>
  OAuth 액세스는 현재 **읽기 전용**이며 **속한 모든 조직에** 대한 액세스를 제공합니다. 쓰기 액세스가 필요하거나 CLI의 범위를 단일 조직으로 제한하려면 대신 [범위가 지정된 API Key를 생성하세요](#api-key).
</Note>

<div id="auth-status">
  ### 인증 상태 및 로그아웃
</div>

```bash theme={null}
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 토큰.

<div id="debug-credentials">
  ### 사용된 자격 증명 소스 디버깅
</div>

명령이 실행되기 전에 선택된 자격 증명 소스(및 API URL)를 stderr에 출력하려면 모든 `cloud` 명령에 `--debug`를 전달하세요.

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

<div id="cloud">
  ## Cloud
</div>

API를 사용해 ClickHouse Cloud 서비스를 관리합니다.

<div id="organizations">
  ### 조직
</div>

```bash theme={null}
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
```

<div id="services">
  ### 서비스
</div>

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

<div id="service-create-options">
  #### 서비스 생성 옵션
</div>

| 옵션                                         | 설명                                            |
| ------------------------------------------ | --------------------------------------------- |
| `--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`                   | 최소 유휴 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-tde`                             | Transparent 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 수집 활성화 또는 비활성화                    |

<div id="query-api-auth-modes">
  #### Query API 인증 모드
</div>

`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`를 설정하십시오.

<div id="query-endpoints">
  #### 쿼리 엔드포인트 관리
</div>

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

<div id="private-endpoints">
  #### Private Endpoint 관리
</div>

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

<div id="backup-config">
  #### Backup 구성
</div>

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

<div id="postgres-services">
  ### Postgres 서비스
</div>

`clickhousectl`로도 위의 ClickHouse 서비스 명령과 동일하게 [ClickHouse Cloud Postgres](/ko/products/managed-postgres/overview) 서비스를 생성하고 관리할 수 있습니다.

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

<div id="postgres-create-options">
  #### Postgres 서비스 생성 옵션
</div>

| 옵션                         | 설명                                    |
| -------------------------- | ------------------------------------- |
| `--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-file`         | `PgConfig` 객체가 포함된 JSON 파일 경로         |
| `--pg-bouncer-config-file` | `PgBouncerConfig` 객체가 포함된 JSON 파일 경로  |

<div id="backups">
  ### 백업
</div>

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

<div id="clickpipes">
  ### ClickPipes
</div>

외부 소스의 데이터를 ClickHouse Cloud로 수집하는 ClickPipes를 관리합니다.

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

<div id="creating-clickpipes">
  #### ClickPipes 생성
</div>

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

각 소스 유형별 전체 옵션 목록은 `clickhousectl cloud clickpipe create <source> --help` 명령으로 확인하십시오.

<div id="members">
  ### 구성원
</div>

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

<div id="invitations">
  ### 초대
</div>

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

<div id="keys">
  ### 키
</div>

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

<div id="activity">
  ### 활동
</div>

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

<div id="json-output">
  ### JSON 출력
</div>

JSON 형식으로 응답을 출력하려면 `--json` 플래그를 사용하세요.

```bash theme={null}
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으로 자동 출력합니다.

<div id="exit-codes">
  ### 종료 코드
</div>

종료 코드는 `gh` CLI 관례를 따릅니다:

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

<div id="skills">
  ## Skills
</div>

[ClickHouse/agent-skills](https://github.com/ClickHouse/agent-skills)에서 공식 ClickHouse Agent Skills를 설치하세요.

```bash theme={null}
# 기본값: 사람을 위한 대화형 모드, 범위 선택 후 에이전트 선택
clickhousectl skills

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

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

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

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

<div id="non-interactive-flags">
  ### 비대화형 플래그
</div>

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

<div id="self-update">
  ## 자체 업데이트
</div>

`clickhousectl` 자체를 최신 릴리스로 업데이트할 수 있습니다:

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

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

CLI는 백그라운드에서 업데이트를 확인하며(24시간에 최대 1회), 최신 버전을 사용할 수 있으면 알림을 표시합니다.

<div id="telemetry">
  ## 텔레메트리
</div>

`clickhousectl`은 CLI 사용 방식을 파악하기 위해 익명의 사용 텔레메트리를 수집합니다. 기본적으로 활성화되어 있지만, 사용자에게 안내하기 전에는 어떠한 정보도 전송하지 않습니다. 처음 실행하면 CLI가 수집하는 항목과 비활성화 방법을 설명하는 안내를 표시하며, 이때는 아무것도 전송하지 않습니다. 수집은 이후 실행부터 시작되므로, 정보가 수집되기 전에 언제든지 거부할 수 있습니다.

각 이벤트에는 다음 항목만 포함됩니다.

* 실행한 명령(예: `local start`)과 사용한 플래그 이름 — 플래그 값, 위치 인수 또는 사용자가 제공한 기타 입력은 절대 포함되지 않으므로 쿼리, 테이블 이름, 자격 증명, 파일 경로는 수집되지 않습니다.
* 종료 코드(예: `0`, `1`, `2`, `4`)와 결과(예: `ok`, `error`, `cancelled`)
* 잘못 입력한 명령에 대해 CLI가 표시한 "혹시 다음을 찾으셨나요?" 제안 — 실제 명령 또는 플래그 이름과 정확히 일치할 때만 기록되므로 입력한 내용이 포함될 수 없습니다.
* `clickhousectl` 버전, OS, 아키텍처, 그리고 CLI가 AI Agent에 의해 호출되었는지(어떤 agent인지 포함) 또는 CI에서 호출되었는지 여부

텔레메트리는 완전히 익명으로 처리됩니다. 개인 데이터는 수집되지 않으며, 기기나 설치 식별자도 수집하지 않습니다.

텔레메트리를 비활성화하려면 다음 중 하나를 수행하세요.

* `clickhousectl telemetry disable`을 실행합니다(`enable`로 다시 활성화하고 `status`로 확인).
* `DO_NOT_TRACK=1` 환경 변수를 설정합니다.

아무것도 전송하지 않고 정확한 payload를 stderr에 출력하려면 `CHCTL_TELEMETRY_DEBUG=1`을 설정하세요.