clickhousectl

clickhousectl 是 ClickHouse 的命令行客户端，适用于本地和云端。

使用 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

安装脚本会下载适用于你所用操作系统的正确版本，并将其安装到 ~/.local/bin/clickhousectl。为方便使用，还会自动创建一个 chctl 别名。

要求

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 可显式指定端口。

**全局服务器管理：**将 --global 与 list、stop 和 stop-all 一起使用，即可在整个系统范围内跨所有项目执行操作。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 密钥 (推荐) 或 OAuth (基于浏览器) 对 ClickHouse Cloud 进行身份验证。

如果您还没有 ClickHouse Cloud 账户，clickhousectl cloud auth signup 会在浏览器中打开注册页面。

API 密钥/Secret (推荐)

API 密钥是推荐的身份验证方式，尤其是在通过 AI 智能体驱动命令行客户端时。你可以创建有范围限制的 API 密钥，只授予你选择的权限 (只读或读/写) ，并且每个密钥都绑定到单个组织。这使其成为一种安全且遵循最小权限原则的方式，可为命令行客户端提供访问权限。

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

clickhousectl cloud auth login

这会打开浏览器，通过 OAuth device flow 进行身份验证。令牌会保存到 .clickhouse/tokens.json (仅限当前项目目录) 。

认证状态与退出登录

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 服务。

组织

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`	用于磁盘加密的 Role ARN
`--enable-tde`	启用 Transparent Data Encryption
`--compliance-type`	合规要求：`hipaa`、`pci`
`--profile`	实例 profile (`enterprise`)
`--tag`	添加 GA 服务标签 (`key` 或 `key=value`)
`--enable-endpoint` / `--disable-endpoint`	启用或禁用 GA 服务端点 (当前为 `mysql`)
`--private-preview-terms-checked`	在需要时接受私有预览条款
`--enable-core-dumps`	启用或禁用服务 core dump 收集

Query API 认证模式

cloud service query 是通过 HTTP 对云服务运行 SQL 的标准方式，无需 clickhouse 可执行文件，也无需服务密码。它支持两种凭据模式：

API key 认证 (读 + 写 SQL) ：当 cloud service query 首次对某个尚未存储 key 的服务运行时，它会为该服务配置一个 Query API 端点，并创建一个绑定到该端点的专用 API key。该 key (keyId、keySecret 和 endpointId) 会存储在 .clickhouse/credentials.json 的 service_query_keys.<service-id> 下。该 key 的作用域仅限于单个服务，因此它可以对该服务执行读写操作 (SELECT、INSERT、DDL) ，但无法访问该组织中的任何其他服务。传入 --no-auto-enable 可让命令在不进行配置的情况下直接失败。
OAuth (cloud auth login) ：查询会以你自己的身份运行，就像 Web SQL Console 一样。使用 OAuth 时，你在该服务上的 SQL 权限为只读。不会配置或存储 Query API key。--no-auto-enable 在此模式下不起作用。

对处于休眠状态的服务发起查询时，这两种认证模式都会自动将其唤醒 (首次查询可能需要一分钟) 。已停止 的服务永远不会被唤醒：查询会失败，并提示运行 cloud service start。设置 CLICKHOUSE_CLOUD_QUERY_HOST 可覆盖自动推导出的 Query API 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>

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 Cloud Postgres 服务，其用法与上面的 ClickHouse 服务命令类似。

# 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 文件路径

Backup

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 会自动检测编码 agent 上下文 (Claude Code、Cursor、Codex、Gemini CLI、Goose、Devin，以及任何设置了标准 AGENT 环境变量的工具) ，并自动将 JSON 输出到 stdout，无需设置 --json。

退出代码

退出代码遵循 gh 命令行客户端的约定：

代码	含义
`0`	成功
`1`	错误 (不属于以下分类的任何情况)
`2`	已取消 (用户中止)
`4`	需要认证 (无凭据、401/403、仅限 OAuth 写入)

技能

从 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>`	为指定智能体安装技能 (可重复使用)
`--global`	使用全局作用域；如省略，则使用项目作用域
`--all`	为所有受支持的智能体安装技能
`--detected-only`	为系统中已检测到的受支持智能体安装技能

自行更新

clickhousectl 可以自行更新到最新版本：

# Update to the latest version
clickhousectl update

# Check for updates without installing
clickhousectl update --check

命令行客户端还会在后台检查更新 (最多每 24 小时检查一次) ，并在有新版本可用时显示通知。

遥测

clickhousectl 会收集匿名使用遥测数据，以帮助我们了解命令行客户端的使用方式。该功能默认启用，但在通知您之前绝不会发送任何数据：首次运行时，命令行客户端会显示一则说明，告知会收集哪些信息以及如何关闭此功能，并且不会发送任何数据。仅从后续运行开始收集，因此您始终可以在收集任何信息前选择退出。

每个事件仅包含：

所运行的命令 (例如 local start) 和所用标志的名称——绝不包含标志值、位置参数或任何其他用户提供的输入，因此不会收集查询、表名、凭据或文件路径
退出代码 (例如 0、1、2、4) 和结果 (例如 ok、error、cancelled)
对于输错的命令，命令行客户端显示的“您是否想要”建议——仅当该建议与实际命令或标志名称完全匹配时才会记录，因此绝不会包含您输入的内容
clickhousectl 版本、操作系统、架构，以及命令行客户端是否由 AI 智能体调用 (以及具体是哪个智能体) 或在 CI 中调用

遥测数据完全匿名：不会收集个人数据，也没有设备或安装标识符。

若要关闭遥测功能，请执行以下任一操作：

运行 clickhousectl telemetry disable (使用 enable 重新启用，使用 status 查看状态)
设置 DO_NOT_TRACK=1 环境变量

设置 CHCTL_TELEMETRY_DEBUG=1 可将确切载荷输出到 stderr，而不会发送任何数据。