clickhousectl - ClickHouse Documentation

clickhousectl は、ローカル環境と Cloud の両方で ClickHouse を扱うための CLI です。 clickhousectl では、次のことができます。

ローカルの ClickHouse バージョンをインストールして管理する
ローカルの ClickHouse server を起動して管理する
ローカルの Postgres インスタンスを起動して管理する
ClickHouse server に対してクエリを実行する
ClickHouse Cloud をセットアップし、Cloud 管理の ClickHouse クラスターを作成する
ClickHouse Cloud の Postgres サービスを作成して管理する
ClickHouse Cloud のリソースを管理する
データインジェスト用の ClickPipes を作成して管理する (S3、Kafka、Kinesis、Postgres、MySQL、MongoDB、BigQuery)
対応しているコーディングエージェントに、公式の ClickHouse agent スキルをインストールする
ローカルの ClickHouse 開発環境を Cloud にプッシュする

clickhousectl は、人間と AI エージェントの両方による ClickHouse を使った開発を支援します。

インストール

クイックインストール

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

インストールスクリプトは、お使いのOSに対応した適切なバージョンをダウンロードし、~/.local/bin/clickhousectl にインストールします。利便性のため、chctl のaliasも自動的に自動的に作成されます。

要件

macOS (aarch64, x86_64) または Linux (aarch64, x86_64)
Cloud コマンドの実行には、ClickHouse Cloud APIキーが必要です

ローカル

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 は、選択したバージョンのバイナリを指す ~/.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 を指定しない場合、最初のサーバーの名前は “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 経由) ため、変更したい設定だけを含めればよく、完全な config を再現する必要はありません。ファイルは .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キー (推奨) またはOAuth (ブラウザベース) を使用して、ClickHouse Cloud に認証します。まだClickHouse Cloudのアカウントをお持ちでない場合は、clickhousectl cloud auth signup を実行すると、ブラウザでサインアップページが開きます。

API キー/シークレット (推奨)

API キーは、認証方法として推奨されています。特に、AI Agent から CLI を操作する場合に適しています。スコープ付き API キーを作成すると、選択した権限 (read-only または read/write) のみを付与でき、各キーは 1 つの組織に紐付けられます。そのため、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 ...

clickhousectl cloud auth login

これにより、OAuth デバイスフローによる認証のためにブラウザが開きます。トークンは .clickhouse/tokens.json に保存されます (プロジェクトローカル) 。

OAuth アクセスは現在 読み取り専用 で、あなたが所属するすべての組織 にアクセスできます。書き込みアクセスが必要な場合、または CLI の対象を 1 つの組織に限定する場合は、代わりにスコープ付き API キーを作成してください。

認証ステータスとログアウト

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 トークン。

使用された認証情報の取得元をデバッグする

任意の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 サービスを管理します。

組織

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-scaling`	ゼロまでのスケールを許可 (デフォルト: `true`)
`--idle-timeout-minutes`	アイドルタイムアウトの最小値 (分) (>= 5)
`--ip-allow`	許可する IP CIDR (複数回指定可能、デフォルト: `0.0.0.0/0`)
`--backup-id`	復元元の Backup ID
`--release-channel`	リリースチャネル: `slow`, `default`, `fast`
`--data-warehouse-id`	データウェアハウス ID (読み取りレプリカ用)
`--readonly`	サービスを読み取り専用にする
`--encryption-key`	顧客のディスク暗号化キー
`--encryption-role`	ディスク暗号化用のロール ARN
`--enable-tde`	透過的データ暗号化を有効にする
`--compliance-type`	コンプライアンス: `hipaa`, `pci`
`--profile`	インスタンスプロファイル (`enterprise`)
`--tag`	GA サービスタグ (`key` または `key=value`) を付与
`--enable-endpoint` / `--disable-endpoint`	GA サービスエンドポイント (現在は `mysql`) を切り替える
`--private-preview-terms-checked`	必要な場合はプライベートプレビューの利用規約に同意
`--enable-core-dumps`	サービスのコアダンプ収集を有効または無効にする

Query API の認証モード

cloud service query は、clickhouse バイナリやサービスのパスワードを使わずに、HTTP 経由で Cloud サービスに対して SQL を実行するための標準的な方法です。どちらの認証モードにも対応しています。

API キー認証 (SQL の読み取り + 書き込み) : 保存済みの API キーがないサービスに対して cloud service query を初めて実行すると、そのサービス用の Query API エンドポイントがプロビジョニングされ、それに紐づく専用の API キーが作成されます。この key (keyId、keySecret、endpointId) は、.clickhouse/credentials.json の service_query_keys.<service-id> に保存されます。この key のスコープは 1 つのサービスに限定されるため、そのサービスに対する読み取りと書き込み (SELECT、INSERT、DDL) はできますが、組織内の他のサービスにはアクセスできません。プロビジョニングせずに失敗させるには、--no-auto-enable を指定します。
OAuth (cloud auth login) : クエリは、Web の SQL コンソールと同様に、ユーザー自身の identity として実行されます。OAuth 使用時のサービス上の SQL permissions は read-only です。Query API キーがプロビジョニングまたは保存されることはありません。このモードでは --no-auto-enable は効果がありません。

idled 状態のサービスにクエリすると、どちらの認証モードでも自動的に復帰します (最初のクエリには 1 分ほどかかる場合があります) 。stopped 状態のサービスが自動的に起動されることはなく、クエリは cloud service start を実行するよう案内するヒント付きで失敗します。生成された Query API ホストを上書きするには、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>

プライベートエンドポイントの管理

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

バックアップ設定

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-file`	`PgConfig` オブジェクトを含む JSON ファイルのパス
`--pg-bouncer-config-file`	`PgBouncerConfig` オブジェクトを含む 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 は、コーディングエージェントのコンテキスト (Claude Code、Cursor、Codex、Gemini CLI、Goose、Devin、および標準の AGENT 環境変数を設定する任意のツール) を自動検出し、--json を指定しなくても JSON を stdout に自動的に出力します。

終了コード

終了コードは gh CLI の慣例に従います。

Code	Meaning
`0`	成功
`1`	エラー (以下のいずれにも分類されないもの)
`2`	キャンセル (ユーザーによる中止)
`4`	認証が必要 (認証情報なし、401/403、OAuth 専用の書き込み)

スキル

公式の ClickHouse Agent スキルは、ClickHouse/agent-skills からインストールしてください。

# デフォルト: 人間向けの対話型モード。スコープを選択し、次にエージェントを選択する
clickhousectl skills

# 非対話型: サポートされているすべてのプロジェクトローカルエージェントフォルダにインストール
clickhousectl skills --all

# 非対話型: 検出されたエージェントのみにインストール
clickhousectl skills --detected-only

# 非対話型: サポートされているすべてのグローバルエージェントフォルダにインストール
clickhousectl skills --global --all

# 非対話型: 特定のプロジェクトローカルエージェントにインストール
clickhousectl skills --agent claude --agent codex

非対話型フラグ

フラグ	説明
`--agent <name>`	特定のエージェント向けのスキルをインストールします (繰り返し指定可能)
`--global`	グローバルスコープを使用します。省略した場合はプロジェクトスコープが使用されます
`--all`	サポートされているすべてのエージェント向けのスキルをインストールします
`--detected-only`	システム上で検出された、サポート対象のエージェント向けのスキルをインストールします

セルフアップデート

clickhousectl は自身を最新リリースに更新できます。

# Update to the latest version
clickhousectl update

# Check for updates without installing
clickhousectl update --check

CLI はバックグラウンドで更新の有無も確認し (24 時間に 1 回まで) 、新しいバージョンが利用可能な場合は通知を表示します。

​インストール

​クイックインストール

​要件

​ローカル

​ClickHouse バージョンのインストールと管理

​ClickHouseバイナリの保存先

​プロジェクトを初期化する

​クエリを実行する

​ClickHouse サーバーの作成と管理

​ローカルサーバー向けのカスタム設定ファイル

​プロジェクトローカルのデータディレクトリ

​ローカルのPostgresを実行する

​認証

​API キー/シークレット (推奨)

​OAuthログイン

​認証ステータスとログアウト

​使用された認証情報の取得元をデバッグする

​Cloud

​組織

​サービス

​サービス作成オプション

​Query API の認証モード

​クエリエンドポイントの管理

​プライベート エンドポイントの管理

​バックアップ設定

​Postgres サービス

​Postgres サービスの作成オプション

​バックアップ

​ClickPipes

​ClickPipes の作成

​メンバー

​招待

​キー

​アクティビティ

​JSON 出力

​終了コード

​スキル

​非対話型フラグ

​セルフアップデート

インストール

クイックインストール

要件

ローカル

ClickHouse バージョンのインストールと管理

ClickHouseバイナリの保存先

プロジェクトを初期化する

クエリを実行する

ClickHouse サーバーの作成と管理

ローカルサーバー向けのカスタム設定ファイル

プロジェクトローカルのデータディレクトリ

ローカルのPostgresを実行する

認証

API キー/シークレット (推奨)

OAuthログイン

認証ステータスとログアウト

使用された認証情報の取得元をデバッグする

Cloud

組織

サービス

サービス作成オプション

Query API の認証モード

クエリエンドポイントの管理

プライベートエンドポイントの管理

バックアップ設定

Postgres サービス

Postgres サービスの作成オプション

バックアップ

ClickPipes

ClickPipes の作成

メンバー

招待

キー

アクティビティ

JSON 出力

終了コード

スキル

非対話型フラグ

セルフアップデート