CloudQuery 6.50 常用 CLI 命令详解

一、概述

本文逐条拆解 CloudQuery CLI 6.50.0 的全部子命令：用法、参数、真实回显与退出码。实验环境为 Ubuntu 22.04 服务器（root@cq-server）+ PostgreSQL 16 数据库服务器（10.89.62.2，口令 q1w2e3r4），项目目录 /opt/cloudquery-demo，配置与插件均为 registry: local 自编译二进制（构建过程见《CloudQuery 6.50 安装部署指南》）；文中所有输出为实测回显。

先看 6.50 的完整命令清单（cloudquery 裸跑，实测原文）：

CloudQuery CLI

High performance data integration at scale.

Usage:
  cloudquery [command]

Available Commands:
  addon           Addon commands
  init            Generate a configuration file for a sync
  login           Login to CloudQuery Hub.
  logout          Log out of CloudQuery Hub.
  migrate         Update schema of your destinations based on the latest changes in sources from your configuration
  plugin          Plugin commands
  switch          Switches between teams.
  sync            Sync resources from configured source plugins to destinations
  tables          Generate documentation for all supported tables of source plugins specified in the spec(s)
  test-connection Test plugin connections to sources and/or destinations
  upgrade         Plugin upgrade commands
  validate-config Validate config

注意：6.50 没有 doctor 子命令（主 help 的 Available Commands 里不存在，CHANGELOG 全文检索亦无）。老文档里常见的 cloudquery doctor 职责在 v6 时代已由 test-connection（连通性）+ validate-config（配置合法性）两个命令分担，见第4节/第5节。

日常使用频率排序：sync > migrate/test-connection > init/validate-config/tables，其余（login/logout/switch/upgrade/plugin/addon）按需。背景与选型见《CloudQuery 6.50 介绍与选型指南》；spec 文件字段逐项解释见《CloudQuery 6.50 配置参数详解》。

二、全局 flags

所有子命令共享以下全局参数（实测 --help 的 Global Flags 段原文归纳）：

flag	默认	说明
`--cq-dir string`	`.cq`	CLI 工作目录，存放从 Hub 下载的插件缓存等
`--invocation-id uuid`	自动生成	调用 ID，用于 OpenTelemetry 关联及 sync summary 的 `sync_id`
`--log-console`	false	日志同时打到控制台
`--log-file-name string`	`cloudquery.log`	日志文件名
`--log-file-overwrite`	false	每次运行覆盖日志而非追加（适合不支持 append 的文件系统）
`--log-format string`	`text`	日志格式：`json` 或 `text`
`--log-level string`	`info`	日志级别：trace/debug/info/warn/error
`--no-log-file`	false	不写日志文件
`--telemetry-level string`	`all`	遥测级别：none/errors/stats/all
`-v, --version`	—	打印版本

两个实用组合（实测）：

# 排障：JSON 日志 + 提高级别 + 同时上屏
cloudquery sync local_sync.yml --log-format json --log-level debug --log-console

# 干净环境跑批：不落日志文件
cloudquery sync local_sync.yml --no-log-file

--telemetry-level none 可关闭用量上报；离线自托管场景建议加上（配合 local registry，见第7节排障实录引用）。

三、init —— 生成配置脚手架

cloudquery init 从 Hub 插件目录拉模板生成 spec 文件。help 明确它按认证状态分三种模式（实测 help 原文归纳）：

模式	触发条件	行为
AI 辅助	已 `cloudquery login` 且未指定 `--source/--destination`	交互式 AI 会话，选插件、生成配置、测连接
基础交互	传 `--disable-ai`，或 AI 不可用时回退	搜索式插件选择器，按默认模板生成配置
非交互	同时指定 `--source` 与 `--destination`	直接生成配置文件，无提示

专属 flags：--source、--destination、--spec-path（输出路径）、--yes（全默认）、--disable-ai、--disable-platform（跳过 Platform 脚手架）、--resume-conversation。

实测负例——插件名写错（files/postgres 不是目录名）：

root@cq-server:/opt/cloudquery-demo# cloudquery init --source files --destination postgres --spec-path connection.yml --disable-ai
Fetching plugins...
Error: source plugin "cloudquery/files" not found, destination plugin "cloudquery/postgres" not found. Run cloudquery init without --source and --destination flags to use interactive mode

实测正例（正确短名 file/postgresql）：

root@cq-server:/opt/cloudquery-demo# cloudquery init --source file --destination postgresql --spec-path connection.yml --disable-ai
Spec file created successfully at connection.yml

Next steps:
  1. Edit connection.yml and configure the source and destination plugins
  2. Run cloudquery sync connection.yml to sync data
  3. See https://docs.cloudquery.io for more information

坑点两条：一是 --source/--destination 只认 Hub 目录短名（完整清单可查 https://api.cloudquery.io/plugins）；二是 init 生成的模板默认 registry: cloudquery，直接 sync 会撞 Hub 登录墙（见第9节），离线环境需手改成本地插件写法。

四、validate-config —— 配置静态校验

校验 spec 的结构与插件参数合法性，不连接数据库、不跑同步。6.50 的 help 明确：registry: cloudquery 插件的 JSON Schema 直接从 Hub API 拉取（无需下载插件二进制、公开插件无需鉴权）；local/grpc/docker registry 则本地拉起插件取 schema。help 原话强调它比 sync 内建校验更严格："a config passing here will also pass sync's validation"。

实测正例：

root@cq-server:/opt/cloudquery-demo# cloudquery validate-config local_sync.yml
Loading spec(s) from local_sync.yml

退出码 0，无输出即通过。实测负例（只有 source 没有 destination）：

root@cq-server:/opt/cloudquery-demo# cloudquery validate-config bad.yml
Loading spec(s) from bad.yml
Error: failed to load spec(s) from bad.yml. Error: expecting at least one destination

退出码 1。文件不存在时同样报错退出 1：

root@cq-server:/opt/cloudquery-demo# cloudquery sync no_such_file.yml
Loading spec(s) from no_such_file.yml
Error: failed to load spec(s) from no_such_file.yml. Error: open no_such_file.yml: no such file or directory

专属 flag：--license（传离线许可证文件时绕过 Hub API、改本地拉起插件）。CI/GitOps 里把 validate-config 放在 sync 前是最便宜的守门员。

五、test-connection —— 连通性检查

逐个拉起配置里的插件并测试实际连接（等价于老版本的 doctor 职责之一）。无任何专属 flag。实测：

root@cq-server:/opt/cloudquery-demo# cloudquery test-connection local_sync.yml
Loading spec(s) from local_sync.yml
Test Connection Results
source       test (local@/opt/cloudquery-demo/plugins/cloudquery-source-test)                   Success
destination  postgresql (local@/opt/cloudquery-demo/plugins/cloudquery-destination-postgresql)  Success

退出码 0。DSN 错误、网络不通、权限不足都会在这里以 Failure + 具体错误暴露，比直接 sync 更快定位。注意：对 registry: cloudquery 插件，test-connection 需要先下载插件，因此会先撞登录墙（实测 Error: unauthorized. Try logging in via cloudquery login，见第9节）——校验配置本身请用 validate-config，它不需要下载插件。

六、migrate —— 目标端 schema 迁移

按 source 当前表结构在 destination 建表/加列/改类型。实测：

root@cq-server:/opt/cloudquery-demo# cloudquery migrate local_sync.yml
Loading spec(s) from local_sync.yml
Starting migration for: test (local@/opt/cloudquery-demo/plugins/cloudquery-source-test) -> [postgresql (local@/opt/cloudquery-demo/plugins/cloudquery-destination-postgresql)]
Migration completed successfully.

退出码 0。要点：

唯一专属 flag 是 --license（离线许可证）。没有 --dry-run（实测 help 确认），想预览迁移影响用 upgrade check（第10节）；
迁移激进度不在命令行控制，而是 destination 的 spec 字段 migrate_mode（try-safe/try-forced/forced-safe/forced，默认 try-safe），加 NOT NULL 列等破坏性变更在 try-safe 下会被拒绝，详见《CloudQuery 6.50 配置参数详解》 §8.3 的冲突实录；
sync 默认在同步前自动执行一次 migrate，--no-migrate 可关闭（见第7节）。

七、sync —— 核心同步命令

7.1 flags 一览

flag	说明
`--license string`	离线许可证文件
`--no-migrate`	关闭同步前的自动迁移
`--shard string`	分片并行，格式 `1/4`（第 1 片 / 共 4 片），Preview 特性
`--summary-location string`	把每次 sync 的 JSON 摘要追加写入指定 JSONL 文件
`--tables-metrics-location string`	每表指标输出文件（Preview，需 2024-07-10 后发布的插件）

另有全局 --invocation-id（固定 sync_id，便于 OpenTelemetry 关联与重放）。

7.2 最小实测

root@cq-server:/opt/cloudquery-demo# cloudquery sync local_sync.yml
Loading spec(s) from local_sync.yml
Starting sync for: test (local@/opt/cloudquery-demo/plugins/cloudquery-source-test) -> [postgresql (local@/opt/cloudquery-demo/plugins/cloudquery-destination-postgresql)]
/ Syncing resources... (13/-, 129 resources/s) [0s]
Sync completed successfully. Resources: 13, Errors: 0, Warnings: 0, Time: 1s

退出码 0。中间的 Syncing resources... 是 ANSI 原地刷新的进度行（同一行反复覆盖），脚本抓取时只看首尾两行即可；Resources: 13, Errors: 0, Warnings: 0 是本次同步的总量结论。

7.3 --summary-location 实测

cloudquery sync local_sync.yml --summary-location summary_d1.jsonl

同步后文件里追加一行 JSON（实测原文，字段含义见 help 内表格）：

{"cli_version":"6.50.0","destination_errors":0,"destination_name":"postgresql","destination_path":"/opt/cloudquery-demo/plugins/cloudquery-destination-postgresql","destination_version":"","destination_warnings":0,"resources":13,"source_errors":0,"source_name":"test","source_path":"/opt/cloudquery-demo/plugins/cloudquery-source-test","source_version":"","source_warnings":0,"source_tables":["test_paid_table","test_some_table","test_sub_table","test_testdata_table"],"sync_id":"2940cc99-e3cc-4ad5-b29f-881c65c72f18","sync_time":"2026-11-03T02:58:58.757841Z","sync_duration_ms":1016,"resources_per_table":{"test_paid_table":1,"test_some_table":1,"test_sub_table":10,"test_testdata_table":1},"errors_per_table":{"test_paid_table":0,"test_some_table":0,"test_sub_table":0,"test_testdata_table":0},"durations_per_table_ms":{"test_paid_table":0,"test_some_table":0,"test_sub_table":0,"test_testdata_table":0}}

多 destination 时每个 destination 各写一行。sync_id 即 --invocation-id（未指定则随机）。这是无平台场景下做同步台账最轻量的方式；另一份台账在目标库 cloudquery_sync_summaries 表里（destination 自动写入，SQL 直接查）。

7.4 --tables-metrics-location 实测

cloudquery sync local_sync.yml --tables-metrics-location metrics.jsonl

输出文件实际是一张对齐表格（实测原文，注意扩展名虽叫 .jsonl，内容并非 JSON）：

+---------------------+----------+-----------+--------+--------+
| TABLE               | DURATION | RESOURCES | ERRORS | PANICS |
+---------------------+----------+-----------+--------+--------+
| test_paid_table     |       0s |         1 |      0 | N/A    |
| test_some_table     |      2ms |         1 |      0 | 0      |
| test_sub_table      |       0s |        10 |      0 | N/A    |
| test_testdata_table |       0s |         1 |      0 | N/A    |
+---------------------+----------+-----------+--------+--------+

用于定位「哪张表慢/哪张表报错」，比翻日志快。

7.5 --shard 分片实测

root@cq-server:/opt/cloudquery-demo# cloudquery sync local_sync.yml --shard 1/2
...
Sync completed successfully. Resources: 12, Errors: 0, Warnings: 0, Time: 1s

同样配置全量同步 13 个资源，--shard 1/2（第一片）只同步了 12 个——数据按分片规则切给了两个进程，配合 cron 并行或 xargs -P 多进程可摊薄大表同步耗时。help 标注该特性为 Preview，支持列表见官方文档 running-in-parallel 页。

7.6 增量状态语义

6.50 的 sync help 用整段文字定义了 backend_options 场景下的状态提交规则：CLI 只在每个 destination 提交了此前记录之后才保存 source 的增量状态；若 destination 或状态后端提交失败，本次不再保存状态、sync 以错误退出，summary 里给出 state_error 字段；下次同步会从最后保存的状态起重放，append 模式的 destination 会拿到重复记录，失败表及其关联表的 delete-stale 会被跳过。配置写法见《CloudQuery 6.50 配置参数详解》第6节。

八、tables —— 导出表结构文档

为配置里的每个 source 生成其支持表的结构文档（JSON 或 Markdown），默认输出到 ./cq-docs。实测：

root@cq-server:/opt/cloudquery-demo# cloudquery tables local_sync.yml --format markdown --output-dir cq-docs-d1
Loading spec(s) from local_sync.yml
Generating docs for "test" to directory "cq-docs-d1/test"
Done generating docs for "test" to directory "cq-docs-d1/test"

退出码 0，产物为一个 source 一个子目录，内含 README.md + 每表一个 .md（实测目录清单）：

README.md  test_paid_table.md  test_some_table.md  test_sub_table.md  test_testdata_table.md

test_some_table.md 内容（实测原文）：

# Table: test_some_table

Test table

The composite primary key for this table is (**resource_id**, **client_id**).

## Relations

The following tables depend on test_some_table:
  - [test_sub_table](test_sub_table.md)

## Columns

| Name          | Type          |
| ------------- | ------------- |
|_cq_id|`uuid`|
|_cq_parent_id|`uuid`|
|resource_id (PK)|`int64`|
|column2|`utf8`|
|client_id (PK)|`int64`|

flags：--format json|markdown（默认 json）、--filter all|spec（spec 只导出配置里选中的表）、--output-dir。接文档站或做数据字典评审时，--filter spec --format markdown 是最小可用组合；注意 local registry 插件同样需要本地拉起进程取 schema，无需登录。

help 原文定位："Login to CloudQuery Hub. This is required to download plugins from CloudQuery Hub. Local plugins and different registries don't need login." 专属 flags：--team（登录到指定团队）、--host（直连 Platform 租户，如 acme.mycloudquery.com）。

默认流程是打开浏览器完成 OAuth 后回调本地端口。在无 GUI 的服务器上实测（stdin 非终端）：

root@cq-server:/opt/cloudquery-demo# cloudquery login
Failed to open browser. Please open https://accounts.cloudquery.io?returnTo=http://localhost:46203/callback manually and paste the token below:
Error: reading from non-terminal stdin is not supported. Hint: Consider setting an api key with the `CLOUDQUERY_API_KEY` env variable

退出码 1。也就是说服务器上两种可行方式：人工打开打印出的 URL 粘贴 token（需终端交互），或直接设环境变量 CLOUDQUERY_API_KEY（CI/无人值守推荐，token 在 Hub 控制台生成）。

登录墙的存在感（实测 registry: cloudquery 配置在未登录时的报错，plugin install/test-connection/migrate 同款）：

root@cq-server:/opt/cloudquery-demo# cloudquery plugin install connection.yml
Loading spec(s) from connection.yml
Error: unauthorized. Try logging in via `cloudquery login`

退出码 1。免费档插件（如 postgresql destination）也要登录，这是 2026 年选型必须知道的商业化变化（背景见《CloudQuery 6.50 介绍与选型指南》 §2.3）。

9.2 logout

root@cq-server:/opt/cloudquery-demo# cloudquery logout
CLI successfully logged out.

退出码 0。help 补充说明：登出后「取决于套餐与插件档位，可能仍可下载部分 Hub 插件」。

9.3 switch

多团队场景切换当前认证团队：cloudquery switch my-team。未登录实测：

root@cq-server:/opt/cloudquery-demo# cloudquery switch
Error: failed to get auth token: not authenticated. Hint: You may need to run `cloudquery login` or set CLOUDQUERY_API_KEY

退出码 1。

十、upgrade check —— 插件升级预检

6.50 的 upgrade 只有 check 一个子命令：在不迁移、不写任何数据的前提下，预览 source 插件升级到新版本对 destination 的影响。help 明确定义了退出码语义（实测原文归纳）：

退出码	含义
0	无需动作：无 schema 变化、可自动迁移、仅新增可空列/新表，或输出无差异
3	需要人工动作：手动迁移/重建、被选表被移除、或 file schema/输出变化
4	无法判定：某个 source/destination 评估失败或覆盖不完整
1	检查本身出错

多 destination 时取 0/3/4 中的最高值；报告始终先打印。flags：--to（必填，目标版本）、--source（多 source 配置时指定升级哪个）、--to-path（local/grpc/docker 源对应的 Hub 路径 <team>/<name>）、--output text|json、--license。

实测（对 local 的 test 源检查升级到 v3.0.0，未给 --to-path）：

root@cq-server:/opt/cloudquery-demo# cloudquery upgrade check local_sync.yml --to v3.0.0
Error: failed to start source test cloudquery/test@v3.0.0: failed to download plugin source cloudquery/test@v3.0.0: plugin version not found. If you're trying to use a private plugin you'll need to run `cloudquery login` first. The CloudQuery Hub path cloudquery/test was inferred from the name the source reports. Use --to-path <team>/<name> to set a different path

退出码 1。三个信息点：--to 缺省会直接报 required flag(s) "to" not set；local 源默认推断 Hub 路径 cloudquery/<name>，推断不对要用 --to-path 显式指定；目标版本下载走的仍是 Hub（需登录）。官方插件升级前用 --output json 把预检结果接入流水线，是 6.50 移除 protocol v1/v2 支持这类断代变更的标准预检手段。

十一、plugin 与 addon

11.1 plugin install

按配置预下载全部插件（把插件拉取与 sync 解耦，适合先装后跑的发布流程）。实测 local 配置为无操作（插件已在本地路径）：

root@cq-server:/opt/cloudquery-demo# cloudquery plugin install local_sync.yml
Loading spec(s) from local_sync.yml

Hub 配置未登录实测（退出码 1）：

root@cq-server:/opt/cloudquery-demo# cloudquery plugin install connection.yml
Loading spec(s) from connection.yml
Error: unauthorized. Try logging in via `cloudquery login`

11.2 plugin publish

help 定位："Publishes a plugin version to CloudQuery Hub from a local dist directory"，用法 cloudquery plugin publish [-D dist]。自研插件方使用，需登录，本专栏未实测发布。

11.3 addon download / publish

addon 是 Hub 上的配置包（如合规转换规则集），用法（help 原文示例）：

cloudquery addon download cloudquery/transformation/aws-compliance-premium@v1.9.0
cloudquery addon publish manifest.json v1.0.0 [--finalize]

均面向 Hub，需登录；离线 local 场景用不到。

十二、退出码与脚本化实践

实测汇总（同一环境、同一配置族）：

命令	场景	退出码
`migrate local_sync.yml`	成功	0
`test-connection local_sync.yml`	全部 Success	0
`sync local_sync.yml`	成功（13 资源）	0
`sync local_sync.yml --shard 1/2`	成功（12 资源）	0
`tables local_sync.yml --format markdown`	成功	0
`validate-config local_sync.yml`	通过	0
`validate-config bad.yml`	缺 destination	1
`sync bad.yml`	同上	1
`sync no_such_file.yml`	文件不存在	1
`plugin install connection.yml`	未登录撞墙	1
`upgrade check ... --to v3.0.0`	目标版本下载失败	1
`switch`	未登录	1
`login`（非终端 stdin）	无法交互	1
`logout`	成功	0

规律简单：0 成功、1 失败（upgrade check 例外，还有 3/4 两档语义）。cron 生产写法（实测模板见安装部署篇第10节）：

#!/bin/bash
cd /opt/cloudquery-demo
/usr/local/bin/cloudquery sync local_sync.yml \
  --summary-location summary.jsonl \
  --telemetry-level none \
  --no-log-file >> sync.cron.log 2>&1
rc=$?
[ $rc -ne 0 ] && echo "$(date -Is) sync failed rc=$rc" | mail -s "cloudquery sync" ops@example.com
exit $rc

排障口径：stdout 的报错有时很误导（实测一例 destination 迁移冲突在 stdout 只显示 Error: EOF，真因藏在 cloudquery.log），养成「先看退出码，再翻 --log-format json 日志」的习惯，实录见《CloudQuery 6.50 配置参数详解》与安装部署篇的排障小节。

十三、常见问题（FAQ）

Q1：想跑 cloudquery doctor，提示不存在？ 6.50 已无此命令（实测主 help 的 12 个子命令清单）。连通性检查用 test-connection，配置合法性用 validate-config，两者覆盖 doctor 的原有职责，且后者不需要下载插件即可校验 Hub 插件配置。

Q2：sync 和 migrate 什么关系，需要分开跑吗？ sync 默认先自动 migrate 再同步（实测 help："By default, sync runs a migration before syncing resources"），日常只跑 sync 即可。把 migrate 单独拆出来跑的场景：变更窗口内先改 schema、观察无误后再在业务低峰 sync --no-migrate 灌数。

Q3：为什么 test-connection 报 unauthorized，而 validate-config 不报？ 两者机制不同：validate-config 对 Hub 插件只拉 JSON Schema 做静态校验（免鉴权）；test-connection 要真实拉起插件进程，registry: cloudquery 就得先从 Hub 下载二进制，于是撞登录墙。离线环境要么登录/设 CLOUDQUERY_API_KEY，要么走本专栏的 local registry 自编译路线（安装部署篇第7节）。

Q4：--summary-location 和 destination 里的 cloudquery_sync_summaries 表记什么？重复吗？ 不重复，视角不同。summary 文件是 CLI 侧台账（JSONL 逐行追加，含 sync_id、耗时、每表资源数/错误数，见 §7.3 实测样本），适合日志采集器收走；cloudquery_sync_summaries 是 destination 库内审计表（含 CLI 版本、插件版本、状态错误等），适合 SQL 直查。生产上两个都开，成本为零。

Q5：脚本里怎么区分「upgrade check 说需要人工迁移」和「命令跑挂了」？ 看退出码：3=有 schema 风险需要人工介入，4=评估不完整（比如某 destination 连不上），1=检查自身失败（参数错、版本下载不到）。流水线里建议 case $? in 0) pass;; 3|4) block;; *) alert;; esac，把 3/4 当作发布门禁信号而不是错误。

十四、参考链接

本专栏实测系列：
CloudQuery CLI 各命令 --help 输出：6.50.0 二进制实测回显
官方文档（sync 语义、shard 支持列表）：https://www.cloudquery.io/docs （查询日期 2026-11-03）

CloudQuery 6.50 常用 CLI 命令详解

CloudQuery 6.50 常用 CLI 命令详解

一、概述

二、全局 flags

三、init —— 生成配置脚手架

四、validate-config —— 配置静态校验

五、test-connection —— 连通性检查

六、migrate —— 目标端 schema 迁移

七、sync —— 核心同步命令

7.1 flags 一览

7.2 最小实测

7.3 --summary-location 实测

7.4 --tables-metrics-location 实测

7.5 --shard 分片实测

7.6 增量状态语义

八、tables —— 导出表结构文档

九、login / logout / switch —— Hub 认证

9.1 login

9.2 logout

9.3 switch

十、upgrade check —— 插件升级预检

十一、plugin 与 addon

11.1 plugin install

11.2 plugin publish

11.3 addon download / publish

十二、退出码与脚本化实践

十三、常见问题（FAQ）

十四、参考链接