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

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

# clickhousectl

export const galaxyOnClick = eventName => () => {
  try {
    if (typeof window !== "undefined" && window.galaxy && eventName) {
      window.galaxy.track(eventName, {
        interaction: "click"
      });
    }
  } catch (e) {}
};

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <Icon />
                <span>Beta</span>
            </a>;
  }
  return <div className="betaBadge">
            <Icon />
            <span>
                Beta feature. 
                <u>
                    <a href="/docs/beta-and-experimental-features#beta-features">
                        Learn more.
                    </a>
                </u>
            </span>
        </div>;
};

`clickhousectl`은 로컬과 클라우드용 ClickHouse CLI입니다.

`clickhousectl`로 다음 작업을 수행할 수 있습니다:

* 로컬 ClickHouse 버전 설치 및 관리
* 로컬 ClickHouse 서버 실행 및 관리
* ClickHouse 서버에서 쿼리 실행
* ClickHouse Cloud를 설정하고 클라우드 관리형 ClickHouse 클러스터 생성
* ClickHouse Cloud 리소스 관리
* 지원되는 코딩 에이전트에 공식 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`은 [GitHub 릴리스](https://github.com/ClickHouse/ClickHouse/releases)에서 ClickHouse 바이너리를 다운로드합니다.

```bash theme={null}
# 버전 설치
clickhousectl local install stable          # 최신 안정 릴리스
clickhousectl local install lts             # 최신 LTS 릴리스
clickhousectl local install 26.3            # 최신 26.3.x.x
clickhousectl local install 26.3.4.3        # 특정 버전

# 버전 목록 조회
clickhousectl local list                    # 설치된 버전
clickhousectl local list --remote           # 다운로드 가능한 버전

# 기본 버전 관리
clickhousectl local use stable              # 최신 안정 버전 (필요 시 설치)
clickhousectl local use lts                 # 최신 LTS (필요 시 설치)
clickhousectl local use 26.3                # 최신 26.3.x.x (필요 시 설치)
clickhousectl local use 26.3.4.3            # 특정 버전
clickhousectl local which                   # 현재 기본 버전 표시

# 버전 제거
clickhousectl local remove 26.3.4.3
```

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

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

```bash theme={null}
~/.clickhousectl/
├── versions/
│   └── 26.3.4.3/
│       └── clickhouse
└── default              # 현재 활성 버전을 추적
```

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

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

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

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

```bash theme={null}
clickhouse/
├── tables/                 # 테이블 정의 (CREATE TABLE ...)
├── materialized_views/     # Materialized view 정의
├── queries/                # 저장된 쿼리
└── seed/                   # 시드 데이터 / INSERT 문
```

<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 서버 인스턴스를 시작하고 관리합니다. 각 서버에는 `.clickhousectl/servers/<name>/data/` 아래에 서로 격리된 자체 데이터 디렉터리가 할당됩니다.

```bash theme={null}
# 서버 시작 (기본적으로 백그라운드에서 실행)
clickhousectl local server start                          # "default"로 명명
clickhousectl local server start --name dev               # "dev"로 명명
clickhousectl local server start --foreground             # 포그라운드에서 실행 (-F / --fg)
clickhousectl local server start --http-port 8124 --tcp-port 9001  # 포트 직접 지정
clickhousectl local server start -- --config-file=/path/to/config.xml

# 모든 서버 목록 조회 (실행 중 및 중지된 서버 포함)
clickhousectl local server list

# 서버 중지
clickhousectl local server stop default                   # 이름으로 중지
clickhousectl local server stop-all                       # 실행 중인 모든 서버 중지

# 중지된 서버 및 해당 데이터 삭제
clickhousectl local server remove test
```

**서버 이름 지정:** `--name`을 지정하지 않으면 첫 번째 server의 이름은 "default"입니다. "default"가 이미 실행 중이면 임의의 이름이 생성됩니다(예: "bold-crane"). 반복해서 시작하거나 중지할 수 있는 안정적인 식별자가 필요하면 `--name`을 사용하세요.

**포트:** 기본 포트는 HTTP 8123과 TCP 9000입니다. 이 포트들이 이미 사용 중이면 사용 가능한 포트가 자동으로 할당되고 출력에 표시됩니다. 포트를 명시적으로 지정하려면 `--http-port`와 `--tcp-port`를 사용하세요.

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

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

```bash theme={null}
.clickhousectl/
├── .gitignore              # 자동 생성됨, 모든 항목 무시
├── credentials.json        # Cloud API 자격 증명 (설정된 경우)
└── servers/
    ├── default/
    │   └── data/           # "default" 서버의 ClickHouse 데이터 파일
    └── dev/
        └── data/           # "dev" 서버의 ClickHouse 데이터 파일
```

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

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

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

<div id="oauth-login">
  ### OAuth 로그인(권장)
</div>

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

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

<div id="api-key">
  ### API Key/Secret
</div>

```bash theme={null}
# 비대화형 (CI 환경에 적합)
clickhousectl cloud auth login --api-key YOUR_KEY --api-secret YOUR_SECRET

# 대화형 프롬프트
clickhousectl cloud auth login --interactive
```

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

환경 변수도 사용할 수 있습니다:

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

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

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

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

```bash theme={null}
clickhousectl cloud auth status    # 현재 인증 상태 표시
clickhousectl cloud auth logout    # 저장된 모든 자격 증명 삭제 (credentials.json & tokens.json)
```

자격 증명 확인 우선순위: CLI 플래그 > OAuth 토큰 > `.clickhousectl/credentials.json` > 환경 변수.

<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}
# 서비스 목록 조회
clickhousectl cloud service list

# 서비스 상세 정보 조회
clickhousectl cloud service get <service-id>

# 서비스 생성 (최소 옵션)
clickhousectl cloud service create --name my-service

# 스케일링 옵션을 지정하여 생성
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

# 특정 IP 허용 목록을 지정하여 생성
clickhousectl cloud service create --name my-service \
  --ip-allow 10.0.0.0/8 \
  --ip-allow 192.168.1.0/24

# Backup에서 생성
clickhousectl cloud service create --name restored-service --backup-id <backup-uuid>

# release channel을 지정하여 생성
clickhousectl cloud service create --name my-service --release-channel fast

# 서비스 시작/중지
clickhousectl cloud service start <service-id>
clickhousectl cloud service stop <service-id>

# clickhouse-client로 Cloud 서비스에 연결
clickhousectl cloud service client --name my-service --password secret
clickhousectl cloud service client --id <service-id> -q "SELECT 1" --password secret

# CLICKHOUSE_PASSWORD 환경 변수 사용 (스크립트/에이전트 환경에 권장)
CLICKHOUSE_PASSWORD=secret clickhousectl cloud service client \
  --name my-service -q "SELECT count() FROM system.tables"

# 서비스 메타데이터 및 패치 업데이트
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 \
  --release-channel fast

# 레플리카 스케일링 업데이트
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

# 자동 생성된 자격 증명으로 비밀번호 재설정
clickhousectl cloud service reset-password <service-id>

# 서비스 삭제 (사전에 중지 필요)
clickhousectl cloud service delete <service-id>

# 강제 삭제: 실행 중인 서비스를 중지한 후 삭제
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`             |

<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="backups">
  ### 백업
</div>

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

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

<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를 설치합니다   |