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

> clickhousectl 文档：用于本地和云端 ClickHouse 的 命令行客户端

# 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 进行开发。

<div id="installation">
  ## 安装
</div>

<div id="quick-install">
  ### 快速安装
</div>

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

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

<div id="requirements">
  ## 要求
</div>

* macOS (aarch64、x86\_64) 或 Linux (aarch64、x86\_64)
* Cloud 命令需要 [ClickHouse Cloud API 密钥](/zh/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` 还会在 `~/.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`，第一个服务器的名称为 "default"。如果 "default" 已在运行，则会生成一个随机名称 (例如 "bold-crane") 。如果需要可反复启动/停止的固定标识，请使用 `--name`。

\*\*端口：\*\*默认端口为 HTTP 8123 和 TCP 9000。如果这些端口已被占用，系统会自动分配空闲端口并在输出中显示。使用 `--http-port` 和 `--tcp-port` 可显式指定端口。

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

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

<div id="api-key">
  ### API 密钥/Secret (推荐)
</div>

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

```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` 中 (仅当前项目) 。

你也可以使用环境变量，可以在你的会话中导出：

```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 device flow 进行身份验证。令牌会保存到 `.clickhouse/tokens.json` (仅限当前项目目录) 。

<Note>
  OAuth 访问当前仅为 **只读**，并且可访问 **你所属的所有组织**。如果需要写入权限，或希望将命令行客户端限定为单个组织，请改为[创建一个有作用域的 API 密钥](#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` > 已导出的环境变量 > `.env` 文件 > OAuth 令牌。

<div id="debug-credentials">
  ### 调试所使用的凭证来源
</div>

为任意 `cloud` 命令添加 `--debug`，即可在命令运行前将解析后的凭证来源 (以及 API URL) 打印到 stderr。

```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`                           | 允许缩容为零 (默认：`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 收集                |

<div id="query-api-auth-modes">
  #### Query API 认证模式
</div>

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

<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">
  #### 专用终结点管理
</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 Cloud Postgres](/zh/products/managed-postgres/overview) 服务，其用法与上面的 ClickHouse 服务命令类似。

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

<div id="exit-codes">
  ### 退出代码
</div>

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

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

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

<div id="self-update">
  ## 自行更新
</div>

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

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

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

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