用途：通过官方命令行工具 clickhousectl 连接 ClickHouse 并运行查询，面向数据分析场景，覆盖认证、定位服务器和执行安全 SQL；全部经 CLI 完成，不使用 ClickHouse MCP 服务器。
主要能力：支持本地服务器、任意可达主机/端口以及 ClickHouse Cloud 三类目标。Cloud 提供两种认证：浏览器 OAuth 登录为只读，可列出与查看组织、服务等信息；API key 登录为读写，写入或首次通过 cloud service 运行 SQL 时需要。凭据按 CLI 参数、OAuth 令牌、.clickhousectl/credentials.json、环境变量顺序解析，并保存在项目本地。
使用方式：先检查 which clickhousectl，未安装则运行 curl -fsSL https://clickhouse.com/cli | sh；若命令仍找不到，执行 export PATH="$HOME/.local/bin:$PATH"。本地服务器可用 clickhousectl local server list 列出。Cloud 认证示例：clickhousectl cloud auth login（只读）或 clickhousectl cloud auth login --api-key <KEY> --api-secret <SECRET>，也可设置 CLICKHOUSE_CLOUD_API_KEY 与 CLICKHOUSE_CLOUD_API_SECRET。查询示例：clickhousectl cloud service query --name <service> -q "SHOW DATABASES"；本地示例：clickhousectl local client --name <server> -q "SHOW TABLES" 或 clickhousectl local client --host myhost --port 9000 -q "SELECT 1"。SQL 优先级为 --query > --queries-file > stdin。
适用场景与限制：先探查 schema（SHOW DATABASES、SHOW TABLES、DESCRIBE TABLE），预览用 LIMIT，优先聚合查询，按时间窗口过滤，避免 SELECT * 与意外交叉连接，大表避免无界 count()、uniqExact() 或宽范围 min/max 扫描。Cloud service query 首次使用时自动配置按服务的查询端点 API key，该配置属写入操作，只读 OAuth 不足以首次查询，可改用 API key 或加 --no-auto-enable 快速失败。切勿在对话中打印 API 密钥或密码。其他流程如本地开发、Cloud 部署迁移、SQL 最佳实践、chdb-sql 由配套官方技能处理，这些技能来自 ClickHouse/agent-skills（Apache-2.0），也可用 clickhousectl skills 或 npx skills add clickhouse/agent-skills 独立安装。