TimechoCLI 命令使用示例

大约 33 分钟

TimechoCLI 命令使用示例

2. Context 连接上下文管理

2.1 `ctx add`：添加上下文

基本语法

timecho-cli ctx add NAME [flags]

添加远程 Tree 模式数据库

timecho-cli ctx add prod \
  --host db.example.com \
  --port 6667 \
  --user root \
  --dialect tree

如果当前是交互式终端，命令会提示输入密码，直接回车可跳过保存；也可以通过 stdin 输入并保存到系统 Keychain：

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli ctx add prod \
    --host db.example.com \
    --port 6667 \
    --user root \
    --dialect tree \
    --password-stdin

在 --json 或 --non-interactive 模式下不会弹出密码提示。若没有使用 --password-stdin，Context 仍可创建，但凭据状态会是 missing，后续数据库命令需要通过环境变量或 Keychain 提供密码。添加 Table 模式上下文

timecho-cli ctx add table-prod \
  --host db.example.com \
  --port 6667 \
  --user root \
  --dialect table \
  --database telemetry

添加本地安装上下文

Linux：

timecho-cli ctx add local-dev \
  --kind local \
  --local /opt/timecho \
  --host 127.0.0.1 \
  --port 6667

Windows PowerShell：

timecho-cli ctx add local-dev `
  --kind local `
  --local "D:\timecho" `
  --host 127.0.0.1 `
  --port 6667

添加集群节点

timecho-cli ctx add cluster-prod \
  --host db1.example.com \
  --port 6667 \
  --nodes db1.example.com:6667,db2.example.com:6667,db3.example.com:6667 \
  --user root

也可以重复指定：

timecho-cli ctx add cluster-prod \
  --nodes db1.example.com:6667 \
  --nodes db2.example.com:6667 \
  --nodes db3.example.com:6667

配置查询参数

timecho-cli ctx add prod \
  --host db.example.com \
  --connect-timeout 10s \
  --query-timeout 2m \
  --fetch-size 4096 \
  --rpc-compression

添加 TLS 上下文

timecho-cli ctx add prod-tls \
  --host db.example.com \
  --port 6667 \
  --tls \
  --ca /etc/timecho/tls/ca.pem \
  --server-name db.example.com

添加双向 TLS 上下文

timecho-cli ctx add prod-mtls \
  --host db.example.com \
  --port 6667 \
  --tls \
  --ca /etc/timecho/tls/ca.pem \
  --cert /etc/timecho/tls/client.pem \
  --key /etc/timecho/tls/client-key.pem \
  --server-name db.example.com

2.2 `ctx list`：列出上下文

timecho-cli ctx list

JSON 输出：

timecho-cli ctx list --json

2.4 `ctx use`：切换当前上下文

timecho-cli ctx use prod

切换后，后续命令可以省略 --ctx prod：

timecho-cli status
timecho-cli sql "show version"

2.5 `ctx update`：更新上下文

只修改显式传入的参数。

修改主机和端口

timecho-cli ctx update prod \
  --host new-db.example.com \
  --port 6668

修改用户名和密码

printf '%s\n' "$NEW_TIMECHODB_PASSWORD" |
  timecho-cli ctx update prod \
    --user admin \
    --password-stdin

修改 SQL 方言

timecho-cli ctx update prod \
  --dialect table \
  --database telemetry

启用 TLS

timecho-cli ctx update prod \
  --tls \
  --ca /etc/timecho/tls/ca.pem \
  --server-name db.example.com

修改超时和 Fetch Size

timecho-cli ctx update prod \
  --connect-timeout 20s \
  --query-timeout 5m \
  --fetch-size 8192

修改集群节点列表

timecho-cli ctx update prod \
  --nodes db1.example.com:6667,db2.example.com:6667

2.6 `ctx remove`：删除上下文

只删除上下文配置，不删除 Keychain 密码，也不要求确认：

timecho-cli ctx remove old-prod

同时删除 Keychain 中保存的密码属于需要确认的操作：

timecho-cli ctx remove old-prod \
  --delete-secret \
  --yes

交互式终端中可以省略 --yes 并按提示确认；JSON 或 --non-interactive 模式下必须显式传入 --yes。

2.7 `ctx discover`：发现本地安装

自动搜索常见安装目录：

timecho-cli ctx discover

指定候选根目录：

timecho-cli ctx discover --root /opt

指定多个目录：

timecho-cli ctx discover \
  --root /opt/timecho \
  --root /srv/iotdb

Windows：

timecho-cli ctx discover `
  --root "C:\Timecho" `
  --root "D:\Apache-IoTDB"

JSON 输出：

timecho-cli ctx discover --json

ctx discover 只发现安装目录，不会自动修改 Context 配置。

3. SQL 执行

3.1 直接执行 SQL

timecho-cli --ctx prod sql "show version"

timecho-cli --ctx prod sql "show cluster"

timecho-cli --ctx prod sql "select * from root.sg.d1 limit 100"

3.2 JSON 输出

timecho-cli --ctx prod --json sql "show version"

timecho-cli --ctx prod --output json sql \
  "select * from root.sg.d1 limit 100"

3.3 CSV 输出

输出到终端：

timecho-cli --ctx prod --output csv sql \
  "select * from root.sg.d1 limit 100"

重定向到文件：

timecho-cli --ctx prod --output csv sql \
  "select * from root.sg.d1" > result.csv

3.4 从 SQL 文件执行

创建 SQL 文件：

select * from root.sg.d1 limit 100

执行：

timecho-cli --ctx prod sql --file query.sql

简写：

timecho-cli --ctx prod sql -f query.sql

3.5 从 stdin 执行

printf '%s\n' "show version" |
  timecho-cli --ctx prod sql --stdin

从文件管道输入：

cat query.sql |
  timecho-cli --ctx prod sql --stdin

PowerShell：

Get-Content .\query.sql -Raw |
  timecho-cli --ctx prod sql --stdin

3.6 强制按查询执行

当 SQL 无法自动判断类型时：

timecho-cli --ctx prod sql \
  --query \
  "show cluster"

3.7 强制按非查询执行

timecho-cli --ctx prod sql \
  --non-query \
  "create database root.demo"

3.8 使用 Table 方言

使用 Context 中配置的 Table 方言：

timecho-cli --ctx table-prod sql "show databases"

临时覆盖方言：

timecho-cli \
  --ctx prod \
  --sql-dialect table \
  sql "show databases"

3.9 通过 stdin 输入数据库密码

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod \
    sql "show version" \
    --password-stdin

3.10 设置超时

timecho-cli --ctx prod \
  --timeout 2m \
  sql "select * from root.sg.**"

3.11 安全显示 BLOB 二进制列

READ_OBJECT(...) 等查询会返回 BLOB。human 模式默认只显示安全的大小摘要，不会把任意二进制字节直接写入终端：

timecho-cli --ctx table-prod sql \
  "select read_object(file_data) from object_test where device_id='pile-img-001'"

需要可复制的内容时，显式选择 Base64 或十六进制：

timecho-cli --ctx table-prod sql \
  --binary-encoding base64 \
  "select read_object(file_data) from object_test where device_id='pile-img-001'"

timecho-cli --ctx table-prod sql \
  --binary-encoding hex \
  "select read_object(file_data) from object_test where device_id='pile-img-001'"

显式选择编码时，human 与 CSV 输出中的二进制值带 base64: 或 hex: 前缀；未指定编码的 human 模式继续显示大小摘要。JSON 查询输出中的二进制值是不带前缀的编码字符串，并在 data.types 和data.binary_encoding 中声明列类型与编码；未指定时 JSON/CSV 默认使用Base64。--binary-encoding 只接受 base64 或 hex。

SQL 命令只允许一个输入来源：位置参数、--file 或 --stdin，不能同时使用。
一次调用只允许一条 SQL；多语句输入会被拒绝。
--query 和 --non-query 互斥。
--stdin 与 --password-stdin 不能共享 stdin。
通用 sql 命令禁止执行激活 SQL；数据库激活必须使用 activate apply。

4. CSV 数据导入

4.1 `data import csv`：导入官方 Tree CSV

CSV 示例：

Time,root.demo.device1.temperature,root.demo.device1.status
2026-07-21T08:00:00Z,25.1,true
2026-07-21T08:01:00Z,25.3,true
2026-07-21T08:02:00Z,25.7,false

导入：

timecho-cli --ctx prod data import csv data.csv

指定批次大小：

timecho-cli --ctx prod data import csv data.csv \
  --batch-size 5000

4.2 允许一定数量的错误行

timecho-cli --ctx prod data import csv data.csv \
  --max-bad-rows 10

4.3 将错误行写入文件

timecho-cli --ctx prod data import csv data.csv \
  --max-bad-rows 10 \
  --error-file rejected.csv

4.4 使用 Mapping 导入 Table 数据

原始 CSV：

ts,host,region,temperature,online
2026-07-21T08:00:00Z,server-01,beijing,25.1,true
2026-07-21T08:01:00Z,server-02,shanghai,26.3,true

mapping.yaml：

dialect: table
timeColumn: ts
database: telemetry
table: server_metrics
columns:
  - name: host
    target: host
    category: TAG
    type: STRING
  - name: region
    target: region
    category: TAG
    type: STRING
  - name: temperature
    target: temperature
    category: FIELD
    type: DOUBLE
  - name: online
    target: online
    category: FIELD
    type: BOOLEAN

导入：

timecho-cli --ctx table-prod data import csv metrics.csv \
  --mapping mapping.yaml

4.5 使用 Mapping 导入 Tree 数据

原始 CSV：

ts,temperature,status
2026-07-21T08:00:00Z,25.1,true
2026-07-21T08:01:00Z,25.3,false

tree-mapping.yaml：

dialect: tree
timeColumn: ts
device: root.demo.device1
columns:
  - name: temperature
    target: temperature
    type: DOUBLE
  - name: status
    target: status
    type: BOOLEAN

导入：

timecho-cli --ctx prod data import csv device1.csv \
  --mapping tree-mapping.yaml

4.6 通过 stdin 输入数据库密码

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod data import csv data.csv \
    --password-stdin

4.7 JSON 输出导入结果

timecho-cli --ctx prod --json data import csv data.csv \
  --batch-size 1000 \
  --max-bad-rows 10 \
  --error-file rejected.csv

5. CSV 数据导出

5.1 `data export csv`：导出到文件

timecho-cli --ctx prod data export csv \
  --sql "select * from root.demo.device1" \
  --out device1.csv

5.2 导出到 stdout

timecho-cli --ctx prod data export csv \
  --sql "select * from root.demo.device1" \
  --out -

也可以省略 --out，默认写到 stdout：

timecho-cli --ctx prod data export csv \
  --sql "select * from root.demo.device1"

通过 Shell 重定向到文件：

timecho-cli --ctx prod data export csv \
  --sql "select * from root.demo.device1" > device1.csv

5.3 导出 Table 查询

timecho-cli --ctx table-prod data export csv \
  --sql "select * from server_metrics limit 1000" \
  --out server-metrics.csv

5.4 导出 BLOB 列

CSV 中的二进制值默认使用带 base64: 前缀的 Base64；也可以选择十六进制：

timecho-cli --ctx table-prod data export csv \
  --sql "select read_object(file_data) from object_test" \
  --binary-encoding hex \
  --out object-content.csv

此时单元格使用 hex: 前缀。--binary-encoding 只接受 base64 或 hex。若需要恢复一个 OBJECT 的原始文件，不要经过 CSV，请使用下一节的data export object。

5.5 通过 stdin 输入数据库密码

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod data export csv \
    --sql "select * from root.demo.device1" \
    --out device1.csv \
    --password-stdin

CSV 写入 stdout 时不能与 JSON 输出模式同时使用。

6. OBJECT 文件导入导出

OBJECT 是 TimechoDB 企业版 Table 模型能力。导入前先确认数据库版本、授权状态、目标表 DDL、所有 TAG 列以及 OBJECT FIELD 列；不要把 Apache IoTDB 开源版的BLOB 与企业版 OBJECT 混用。

6.1 `data import object`：写入本地文件

以下命令把一个本地普通文件按 4 MiB（默认值）分段写入同一个 Table 行，并在最后一段设置 EOF：

timecho-cli --ctx table-prod data import object ./photo.png \
  --table telemetry.object_test \
  --object-column file_data \
  --timestamp 1700000000000 \
  --tag device_id=pile-img-001 \
  --tag file_type=image/png \
  --verify

规则与边界：

Context 必须使用 table 方言；--table 接受 table 或 database.table。

使用 database.table 时，该数据库用于本次导入连接。

--timestamp 是必填的毫秒时间戳；每个 TAG 列重复传入一个

--tag name=value；--object-column 指向 OBJECT FIELD。

--chunk-size 默认 4194304 字节，允许范围为 1 到 256 MiB。
--verify 默认启用，写完后分块读回并比较字节数与 SHA-256。仅在明确接受

不校验时使用 --verify=false。

本地校验只接受普通文件。若中途某段写入失败，服务端已经写入的分段无法由

CLI 自动回滚；应先检查或删除目标行，再决定是否重试。JSON 自动化示例：

timecho-cli --ctx table-prod --json --non-interactive data import object ./photo.png \
  --table telemetry.object_test \
  --object-column file_data \
  --timestamp 1700000000000 \
  --tag device_id=pile-img-001

6.2 `data export object`：恢复原始文件

单次查询必须通过 READ_OBJECT(...) 返回恰好一行、一列、非 NULL 的 BLOB：

timecho-cli --ctx table-prod data export object \
  --sql "select read_object(file_data) from object_test where device_id='pile-img-001' and time=1700000000000" \
  --out ./photo-restored.png

大对象可以使用包含且只包含一个 {{offset}} 和一个 {{length}} 占位符的分块查询模板：

timecho-cli --ctx table-prod data export object \
  --sql-template "select read_object(file_data, {{offset}}, {{length}}) from object_test where device_id='pile-img-001' and time=1700000000000" \
  --chunk-size 4194304 \
  --out ./photo-restored.png

导出必须使用 --out FILE，禁止把原始二进制写到 stdout。目标已存在时默认返回冲突；只有显式传入 --force 才替换。CLI 先写同目录临时文件，完整成功后再原子发布，并返回字节数和 SHA-256；查询失败不会发布半截目标文件。

7. TsFile 导入

7.1 `data import tsfile`

timecho-cli --ctx prod data import tsfile \
  "/data/import/2026-07-21.tsfile"

Windows 数据库服务端路径：

timecho-cli --ctx prod data import tsfile `
  "D:\timecho-data\import\2026-07-21.tsfile"

JSON 输出：

timecho-cli --ctx prod --json data import tsfile \
  "/data/import/2026-07-21.tsfile"

通过 stdin 输入数据库密码：

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod data import tsfile \
    "/data/import/2026-07-21.tsfile" \
    --password-stdin

参数是数据库服务器能够访问的路径，不是执行 CLI 的客户端本地路径。
CLI 首版不支持 TsFile 导出。

8. 数据库激活

8.1 `activate machine-code`：查询机器码

timecho-cli --ctx prod activate machine-code

JSON 输出：

timecho-cli --ctx prod --json activate machine-code

通过 stdin 输入数据库密码：

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod activate machine-code \
    --password-stdin

8.2 `activate apply`：应用激活码

推荐通过 stdin 输入激活码：

printf '%s' "$ACTIVATION_CODE" |
  timecho-cli --ctx prod activate apply --stdin

PowerShell：

$env:ACTIVATION_CODE |
  timecho-cli --ctx prod activate apply --stdin

直接通过参数传入：

timecho-cli --ctx prod activate apply \
  --code "YOUR-ACTIVATION-CODE"

JSON 输出：

printf '%s' "$ACTIVATION_CODE" |
  timecho-cli --ctx prod --json activate apply --stdin

推荐使用 --stdin，避免激活码进入 Shell 历史。
激活成功后，CLI 会再次查询激活状态，只有后置状态为 ACTIVATED 才判定成功。
激活码和数据库密码不能同时从同一个 stdin 管道读取；此时数据库密码应预先保存在 Keychain，或通过 TIMECHODB_PASSWORD 环境变量提供。

8.3 `activate status`：查看激活状态

timecho-cli --ctx prod activate status

JSON 输出：

timecho-cli --ctx prod --json activate status

通过 stdin 输入数据库密码：

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod activate status \
    --password-stdin

9. 本地配置管理

配置命令只操作本地安装目录、显式配置文件或 kind: local 的 Context，不通过 SSH 修改远程服务器文件。

9.1 `config get`：读取配置

通过本地 Context 读取

timecho-cli --ctx local-dev config get dn_rpc_port \
  --db-version 2.0.6.1

如果 Context 配置文件中已经存在准确的 versionHint，可以省略 --db-version。当前 ctx add/update 暂无设置 versionHint 的命令参数，因此普通 CLI 流程建议显式传入数据库版本。通过安装目录读取

timecho-cli config get dn_rpc_port \
  --home /opt/timecho \
  --db-version 2.0.6.1

通过指定 Properties 文件读取

timecho-cli config get dn_rpc_port \
  --file /opt/timecho/conf/iotdb-system.properties \
  --db-version 2.0.6.1

读取所有已有配置项

timecho-cli config get \
  --all \
  --home /opt/timecho \
  --db-version 2.0.6.1

JSON 输出：

timecho-cli --json config get \
  --all \
  --home /opt/timecho \
  --db-version 2.0.6.1

9.2 `config set`：修改配置

只校验并查看 Diff

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --dry-run

确认后正式写入

交互式：

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1

非交互式：

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --yes

修改时间精度

timecho-cli config set timestamp_precision ms \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --yes

修改数据目录

timecho-cli config set dn_data_dirs "/data1/iotdb,/data2/iotdb" \
  --file /opt/timecho/conf/iotdb-system.properties \
  --db-version 2.0.6.1 \
  --yes

Windows：

timecho-cli config set dn_data_dirs "D:\data1,D:\data2" `
  --home "D:\timecho" `
  --db-version 2.0.6.1 `
  --yes

正式写入时会显示 Diff、创建备份、检查并发变更并执行同目录原子替换。

9.3 `config diff`：比较配置差异

与 Schema 默认值比较

timecho-cli config diff \
  --home /opt/timecho \
  --db-version 2.0.6.1

比较两个 Properties 文件

timecho-cli config diff \
  --file /opt/timecho/conf/iotdb-system.properties \
  --against ./iotdb-system.expected.properties \
  --db-version 2.0.6.1

JSON 输出：

timecho-cli --json config diff \
  --home /opt/timecho \
  --db-version 2.0.6.1

9.4 `config tune`：查看调优建议

timecho-cli config tune \
  --home /opt/timecho \
  --db-version 2.0.6.1

JSON 输出：

timecho-cli --json config tune \
  --home /opt/timecho \
  --db-version 2.0.6.1

当前实现不自动应用调优建议。即使传入 --apply，也会返回稳定错误 tune_apply_unavailable：

timecho-cli config tune \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --apply \
  --yes

正确流程是先查看建议，再对确认过的配置逐项使用 config set：

timecho-cli config tune \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --json

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --dry-run

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --yes

内置保守 Schema 不包含猜测的硬件调优值；没有权威建议时，recommendations 为空并返回说明性 notice。

10. 配置 Schema 管理

10.1 `config schema list`：列出 Schema 字段

使用默认数据库版本：

timecho-cli config schema list

指定数据库版本：

timecho-cli config schema list \
  --db-version 2.0.6.1

JSON 输出：

timecho-cli --json config schema list \
  --db-version 2.0.6.1

10.2 `config schema show`：查看 Schema

查看完整 Schema：

timecho-cli config schema show \
  --db-version 2.0.6.1

查看指定配置项：

timecho-cli config schema show \
  --db-version 2.0.6.1 \
  --key dn_rpc_port

查看时间精度定义：

timecho-cli config schema show \
  --db-version 2.0.6.1 \
  --key timestamp_precision

JSON 输出：

timecho-cli --json config schema show \
  --db-version 2.0.6.1 \
  --key dn_rpc_port

10.3 `config schema update`：更新 Schema

从默认发布地址更新：

timecho-cli config schema update \
  --version 1.0.0

指定自定义发布地址：

timecho-cli config schema update \
  --version 1.0.0 \
  --base-url https://downloads.example.com/timecho-schemas

JSON 输出：

timecho-cli --json config schema update \
  --version 1.0.0

CLI 将下载：

timechodb-schema-1.0.0.tar.gz
checksums.txt

并执行 HTTPS、SHA-256、归档路径和 Schema 内容校验。SHA-256 证明资产相对于 checksums.txt 未发生变化，但当前协议不宣称独立完成发布者身份或签名真实性验证。

11. 数据库状态检查

11.1 `status`

检查当前 Context：

timecho-cli status

检查指定 Context：

timecho-cli --ctx prod status

JSON 输出：

timecho-cli --ctx prod --json status

增加超时：

timecho-cli --ctx prod \
  --timeout 1m \
  status

通过 stdin 输入数据库密码：

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod status \
    --password-stdin

自动化调用：

timecho-cli \
  --ctx prod \
  --json \
  --non-interactive \
  --timeout 30s \
  --trace-id health-check-001 \
  status

状态结果包含数据库版本、激活、集群、Region、运行变量和磁盘占用等检查项，每项返回：

pass
warn
fail
skip

磁盘占用检查会按 Context 的 SQL 方言选择查询：树模型使用SHOW DISK_USAGE FROM root.**，表模型使用SELECT * FROM information_schema.table_disk_usage。两种模型的语法不能混用。

12. 诊断命令

12.1 远程数据库诊断

timecho-cli --ctx prod diagnose

JSON 输出：

timecho-cli --ctx prod --json diagnose

12.2 生成脱敏诊断包

timecho-cli --ctx prod diagnose \
  --bundle ./timecho-diagnose.zip

12.3 在远程诊断基础上包含本地诊断

timecho-cli --ctx local-dev diagnose \
  --local

12.4 指定本地安装目录

timecho-cli --ctx prod diagnose \
  --local \
  --home /opt/timecho

Windows：

timecho-cli --ctx prod diagnose `
  --local `
  --home "D:\timecho" `
  --bundle ".\timecho-diagnose.zip"

12.5 同时进行远程和本地诊断

timecho-cli --ctx local-dev diagnose \
  --local \
  --bundle ./timecho-full-diagnose.zip

12.6 通过 stdin 输入数据库密码

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod diagnose \
    --password-stdin \
    --bundle ./timecho-diagnose.zip

诊断结果会脱敏密码、Token、激活码等敏感信息。单个采集项失败时，其他采集项仍可继续执行，并返回 partial success。
当前 diagnose 总会先解析 Context、创建数据库 Session 并执行远程只读查询；--local 和 --home 只是附加本地 OS/JDK/配置/日志采集，不是离线诊断模式。即使只关心本地目录，也必须存在可连接的数据库 Context。

13. TimechoAI

TimechoAI 是统一 timecho-cli 下的命令组，不存在单独的timechoai-cli 可执行文件。当前对外可用的是 ping、forecast 和 key。evaluate、dimensions 仍注册在迁移契约中，但已隐藏并返回service_not_open，服务端开放前不得按可用能力调用或宣称支持；运行时帮助是最终命令契约。

13.1 查看 AI 命令

timecho-cli ai --help
timecho-cli ai ping --help
timecho-cli ai forecast --help
timecho-cli ai key --help
timecho-cli ai key set --help
timecho-cli ai key show --help
timecho-cli ai key remove --help

13.2 检查连通性与鉴权

export TIMECHOAI_API_KEY="your-api-key"
timecho-cli ai ping
timecho-cli ai ping --name World

优先避免把 API Key 写入 shell history：

printf '%s\n' "$TIMECHOAI_API_KEY" |
  timecho-cli ai ping --api-key-stdin

13.3 预测一个目标序列

输入支持 CSV、TSV 和 JSON。v0.1.0 Forecast 契约只接受一个--input：同一张表同时包含时间、目标以及可选的协变量列。历史部分至少需要 16 行；未传 --time-col 时会自动识别大小写不敏感的time 列。

timecho-cli ai forecast \
  --input ./data.csv \
  --target OT \
  --output-start-time 2024-01-17T00:00:00 \
  --output-length 96

--target 必须且只能传一次，值必须是一个目标列名；省略、重复或传入逗号分隔的多列都会在读取凭据和联网前失败。--output-start-time 也是必填项：time < boundary 的行是目标/历史协变量历史，time >= boundary 的行提供未来协变量，这些行中的目标值会被丢弃。边界可以落在两个样本之间，不要求在时间列中精确出现。显式模型使用 --model 或兼容别名 --model-id：

timecho-cli --json ai forecast \
  --input ./data.json \
  --target load \
  --output-start-time 2024-01-17T00:00:00 \
  --model Timer-3.5 \
  --output-length 24

历史和未来协变量分别使用 --history-cov、--future-cov 从同一个--input 选列。两个参数都可重复，也可使用逗号分隔，列顺序会保留；未来协变量必须是历史协变量的子集。默认自动适配只处理长度：超出 horizon 的未来行会被截断，不足时按固定采样间隔生成合法时间并将协变量补零。使用--no-auto-adapt 可严格拒绝长度不匹配；无论是否自动适配，都不会静默修复非法的列角色。

timecho-cli ai forecast \
  --input ./data.csv \
  --target OT \
  --history-cov temperature,humidity \
  --history-cov holiday \
  --future-cov temperature,holiday \
  --output-start-time 2024-01-17T00:00:00 \
  --output-length 48 \
  --no-auto-adapt

省略 --output-length 时，若没有未来协变量，wire 上保持 null 并由服务选默认值；若选了未来协变量，边界后已有行数会推断 horizon，一行也没有时则使用所选/自动路由模型默认值并生成未来行。旧参数--history-cov-input 和 --future-cov-input 已隐藏，传入任一参数只会返回forecast_legacy_flag 迁移错误；必须把旧文件的列合并进 --input 后使用新selector，不存在兼容执行路径。时间列严格对齐 Python SDK：只接受 YYYY-MM-DD，或带秒、可选 1～9 位小数、可选 Z/+HH:MM 的 ISO 日期时间。整列必须使用相同的分隔符、精度、时区表示/状态和固定采样间隔。数值时间戳、重复时间、混用日期/日期时间、混用 Z与 offset、不规则间隔都会在联网前失败。CLI 会稳定排序但不转成 UTC；--output-start-time 必须与输入保持相同的 aware/naive 时区状态。旧格式 2020-11-07 04:20:00 +0800 CST 不属于新 Forecast 契约。结果可以直接输出为 human、JSON envelope 或纯 CSV，也可以原子写入 CSV/JSON文件。现有目标文件会被完整替换，不会在失败时留下半成品：

timecho-cli --output csv ai forecast \
  --input ./data.csv \
  --target OT \
  --output-start-time 2024-01-17T00:00:00 \
  --output-length 96

timecho-cli ai forecast \
  --input ./data.csv \
  --target OT \
  --output-start-time 2024-01-17T00:00:00 \
  --output-length 96 \
  --out ./prediction.csv

timecho-cli --json ai forecast \
  --input ./data.csv \
  --target OT \
  --output-start-time 2024-01-17T00:00:00 \
  --out ./prediction.json

--model-param KEY=VALUE 可重复使用，VALUE 优先按 JSON 解析，否则按普通字符串传递。目标和协变量列只接受有限数值；空值、NaN、Inf、重复列和非法时间值会在读取凭据或发起网络请求前被拒绝。--plot、--plot-format、--plot-width、--plot-height 和 --plot-scale由统一 Go CLI 原生处理，不会切换到 Python CLI 或 MCP。一个包含所有绘图参数的PNG 示例是：

timecho-cli ai forecast \
  --input ./data.csv \
  --target OT \
  --output-start-time 2024-01-17T00:00:00 \
  --output-length 96 \
  --plot ./forecast.png \
  --plot-format png \
  --plot-width 1200 \
  --plot-height 700 \
  --plot-scale 2

--plot PATH 必填后才能使用其他绘图参数；它默认写 PNG，.html/.htm后缀或 --plot-format html 写自包含 SVG HTML。--plot-format 只接受png|html。--plot-width/--plot-height 是逻辑像素，默认 800×500，范围均为1～8192；--plot-scale 是 PNG 分辨率倍率，默认 2，范围 0.25～8，且缩放后宽高不能超过 8192 像素。--out 与 --plot 必须使用不同路径。绘图复用同一份已准备目标历史，因此实线历史只包含边界前的行；预测线为虚线，边界为灰色点线。被 --history-cov 选中的列也复用它们已准备的边界前帧，仅绘制为低强调的 history-only 辅助曲线，不会延伸到预测区间。绘图文件使用同目录临时文件和原子替换，渲染失败时保留旧文件，并且在成功结果输出前返回错误。Forecast JSON envelope 的 data.results 保留 API 的 split-table 形状（columns和 data）；human/CSV 模式会展开服务返回的结果表，只在返回多表时增加确定性 task 列。使用 --plot 时 JSON 还会返回 data.plot，其中包含绝对路径和逻辑/最终尺寸；human 模式报告路径，CSV 保持纯 CSV 并把路径写到 stderr。--out result.json 写入同样的 results payload，但不包含 CLI 外层 envelope。

13.4 管理 TimechoAI API Key

只查看状态不会回显 Key；设置/轮换优先从 stdin 读取，避免把密钥写入命令参数或 shell history：

printf '%s\n' "$TIMECHOAI_API_KEY" |
  timecho-cli ai key set --api-key-stdin

timecho-cli ai key show
timecho-cli ai key remove

ai key 使用系统 Keychain 的 service timecho-cli、account ai/api-key。set 的解析顺序为 --api-key-stdin、TIMECHOAI_API_KEY、兼容变量TIMER_CLIENT_API_KEY，最后才是在可交互终端中的安全提示；JSON 或非交互模式不会提示输入。

13.5 尚未开放的 AI 服务

evaluate 和 dimensions 仍可由已安装二进制识别，但已从 ai --help 隐藏，直接调用会返回类型化错误 service_not_open。服务端开放前不要把以下命令当作成功路径或提供可用性承诺：

timecho-cli ai evaluate
timecho-cli ai dimensions

AI 专属参数是 --api-key-stdin 和 --base-url。API Key 顺序为 stdin、TIMECHOAI_API_KEY、兼容变量 TIMER_CLIENT_API_KEY、系统 keychain。根级--timeout、--json、--output、--non-interactive、--verbose 和--trace-id 继续复用。AI JSON 与其他命令使用同一个timecho.com/timecho-cli/v1alpha1，Forecast 使用 TimechoAIForecast kind；MCP 仍不属于本期迁移，也不要根据规划文档拼造 MCP 调用。

13.6 使用 Forecast Agent Skill

需要 Agent 自动完成“检查数据 → 选择路由 → 预测 → 绘图 → 汇报”时，安装内置timecho-forecast 工作流：

timecho-cli setup skills \
  --agent codex \
  --skill timecho-forecast \
  --dry-run

timecho-cli setup skills \
  --agent codex \
  --skill timecho-forecast

选择该工作流时，若来源中存在，安装器会自动把timechoai-cli-guide 和公共 timecho-cli-guide 加入计划。工作流先检查统一CLI 的根/AI 帮助，执行只走 timecho-cli ai，运行时 --help 优先于静态示例。

14. Skills 安装与上传包导出

timecho-cli setup skills 同时承担两类交付：

文件系统安装：Codex、Claude、CodeBuddy、OpenClaw、Hermes、TRAE、TRAE CN；
上传包导出：TRAE Work、WorkBuddy。

上传包导出不会调用平台私有 API，也不会自动完成远端导入。

14.1 默认行为：安装二进制内置 Skills

不传 --source、--bundle、--version 时，使用构建进二进制的离线 Skills catalog：

timecho-cli setup skills

默认参数等价于：

--agent all --scope user

其中 all 只展开为以下文件系统 Agent：

claude
codex
codebuddy
openclaw
hermes
trae
trae-cn

all 不包含 trae-work 和 workbuddy，避免在未指定导出目录时意外生成上传包。先查看内置 catalog 的安装计划：

timecho-cli --json setup skills \
  --agent codex \
  --dry-run

输出中的关键字段：

字段	含义
`source_mode: embedded`	使用二进制内置 catalog
`bundle_version: embedded-<digest>`	构建时 catalog 摘要标签
`sha256_verified: false`	没有使用外部 `checksums.txt`
`delivery_mode: filesystem`	直接写入 Agent Skills 目录
`delivery_status: planned`	Dry Run，仅生成计划

内置 catalog 是构建时快照，不代表官网或远程 Release 的最新版本。需要指定发布版本时使用 --version。

14.2 从官方 Release 安装

指定 --version 且不传 --source/--bundle 时，从 Release 下载：

timechodb-skills-1.0.0.tar.gz
checksums.txt

安装到 Codex 用户目录：

timecho-cli setup skills \
  --version 1.0.0 \
  --agent codex

使用 JSON 输出：

timecho-cli --json setup skills \
  --version 1.0.0 \
  --agent codex

使用自定义 HTTPS Release 地址：

timecho-cli setup skills \
  --version 1.0.0 \
  --base-url https://downloads.example.com/timechodb-skills \
  --agent codex

实际下载地址由以下部分组成：

<base-url>/<version>/timechodb-skills-<version>.tar.gz
<base-url>/<version>/checksums.txt

远程下载只允许 HTTPS，并在安全解包前验证 SHA-256。校验和只能证明资产与 checksums.txt 一致，不等于独立的发布者签名认证。

14.3 从仓库 Skills 目录安装

本地开发时可直接使用规范源目录：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --dry-run

确认计划后正式安装：

timecho-cli setup skills \
  --source ./skills \
  --agent codex

Windows PowerShell：

timecho-cli setup skills `
  --source .\skills `
  --agent codex `
  --dry-run

本地目录模式不会要求外部 checksum，输出为：

source_mode: directory
sha256_verified: false
bundle_version: local

如果同时传入 --source 和 --version，--version 只作为 manifest 中的本地 bundle 标签，不会触发远程下载：

timecho-cli setup skills \
  --source ./skills \
  --version dev-20260729 \
  --agent codex

--source 和 --bundle 互斥。

14.4 从本地 Bundle 安装

本地 .tar.gz bundle 必须同时提供包含该文件摘要的 checksums.txt：

timecho-cli setup skills \
  --bundle ./timechodb-skills-local.tar.gz \
  --checksums ./checksums.txt \
  --agent codex \
  --dry-run

正式安装：

timecho-cli setup skills \
  --bundle ./timechodb-skills-local.tar.gz \
  --checksums ./checksums.txt \
  --agent codex

此模式的输出应包含：

source_mode: bundle
sha256_verified: true

Bash：生成只包含 Skill 目录的测试 Bundle

stage="$(mktemp -d)"
cp -R skills/timechodb-* skills/timechoai-* skills/timecho-cli-guide skills/timecho-forecast "$stage/"
tar -czf timechodb-skills-local.tar.gz -C "$stage" .
sha256sum timechodb-skills-local.tar.gz > checksums.txt
rm -rf "$stage"

PowerShell：生成只包含 Skill 目录的测试 Bundle

$stage = Join-Path $env:TEMP ("timechodb-skills-stage-" + [guid]::NewGuid())
New-Item -ItemType Directory -Path $stage | Out-Null

Get-ChildItem -LiteralPath .\skills -Directory |
  Where-Object { $_.Name -like 'timechodb-*' -or $_.Name -like 'timechoai-*' -or $_.Name -eq 'timecho-cli-guide' -or $_.Name -eq 'timecho-forecast' } |
  ForEach-Object {
    Copy-Item -LiteralPath $_.FullName -Destination $stage -Recurse
  }

tar -czf .\timechodb-skills-local.tar.gz -C $stage .

$asset = (Resolve-Path .\timechodb-skills-local.tar.gz).Path
$hash = (Get-FileHash -Algorithm SHA256 -LiteralPath $asset).Hash.ToLowerInvariant()
"$hash  $([IO.Path]::GetFileName($asset))" |
  Set-Content -LiteralPath .\checksums.txt -Encoding ascii

Remove-Item -LiteralPath $stage -Recurse -Force

不要直接把整个仓库根目录打入 Skills bundle。若从本仓库的 skills/ 打包，也建议只选择 timechodb-*、timechoai-*、timecho-cli-guide 与 timecho-forecast 规范目录，避免把 embed.go、测试文件或其他非 Skill 资产混入发布包。

14.5 选择部分 Skill

--skill 可重复，也可以使用逗号分隔：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --skill timechodb-knowledge-base \
  --skill timechodb-sql-dev

Forecast 工作流可以单独选择：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --skill timecho-forecast \
  --dry-run

等价写法：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --skill timechodb-knowledge-base,timechodb-sql-dev

选择不存在或名称格式非法的 Skill 会在写入目标目录前失败。若被选中的 Skill 在 SKILL.md 中调用 timecho-cli，并且来源中包含timecho-cli-guide，安装器会自动把该指南加入安装或导出计划；显式选择timecho-forecast 时，来源中存在 timechoai-cli-guide 也会自动加入。这样Agent 在执行依赖 Skill 前可以先通过运行时 --help 和分层命令参考确认当前语法。无关 Skill 不会被注入指南，显式选择指南本身也不会重复。因此，自动化脚本应以 dry-run 或正式结果中的 plan.install /plan.export 为最终选择集合，而不是假定它与命令行 --skill 参数完全一一对应。

14.6 文件系统 Agent 与默认目录

User Scope

Agent	目标目录
`claude`	`~/.claude/skills`
`codex`	`~/.agents/skills`
`codebuddy`	`~/.codebuddy/skills`
`openclaw`	`~/.openclaw/skills`
`hermes`	`~/.hermes/skills`
`trae`	`~/.trae/skills`
`trae-cn`	`~/.trae-cn/skills`

示例：

timecho-cli setup skills --agent claude
timecho-cli setup skills --agent codex
timecho-cli setup skills --agent codebuddy
timecho-cli setup skills --agent openclaw
timecho-cli setup skills --agent hermes
timecho-cli setup skills --agent trae
timecho-cli setup skills --agent trae-cn

Project Scope

Agent	目标目录
`claude`	`<project>/.claude/skills`
`codex`	`<project>/.agents/skills`
`codebuddy`	`<project>/.codebuddy/skills`
`openclaw`	`<project>/.agents/skills`
`hermes`	`<project>/.agents/skills`
`trae`	`<project>/.trae/skills`
`trae-cn`	`<project>/.trae/skills`

Codex 项目级安装：

timecho-cli setup skills \
  --agent codex \
  --scope project \
  --project-dir /workspace/my-project

Windows PowerShell：

timecho-cli setup skills `
  --agent codex `
  --scope project `
  --project-dir "D:\projects\my-project"

若省略 --project-dir，project scope 使用当前工作目录。自动化脚本仍建议显式传入项目根目录。OpenClaw 项目级默认复用 .agents/skills。如需 OpenClaw 原生项目目录：

timecho-cli setup skills \
  --agent openclaw \
  --scope project \
  --project-dir /workspace/my-project \
  --native-target

目标将变为：

<project>/skills

--native-target 只适用于 OpenClaw。Hermes project scope 安装完成后，如果 Hermes 没有自动发现目录，CLI 会提示把目标目录加入 Hermes external_dirs。

14.7 同时安装到多个文件系统 Agent

--agent 可重复或使用逗号分隔：

timecho-cli setup skills \
  --source ./skills \
  --agent codex,claude,codebuddy \
  --scope project \
  --project-dir /workspace/my-project \
  --dry-run

等价写法：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --agent claude \
  --agent codebuddy \
  --scope project \
  --project-dir /workspace/my-project

CLI 会先为全部目标生成计划，再开始逐目标应用；但当前多目标执行不是跨目录的全局事务。如果后续目标写入失败，已经成功的前序目标不会自动整体回滚。

14.8 覆盖一个文件系统 Agent 的目标目录

--target-dir 只允许与一个文件系统 Agent 配合：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --target-dir ./tmp/codex-skills \
  --dry-run

以下组合会失败：

timecho-cli setup skills \
  --agent codex,claude \
  --target-dir ./shared-skills

CLI 不会把一个自定义目录暗中复用给多个 Agent。

14.9 Dry Run、冲突与 `--force`

Dry Run 只生成计划，不创建 Skill、manifest、备份或导出包：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --dry-run

文件系统安装使用目标目录下的：

.timechodb-skills-manifest.json

记录 bundle 版本与文件 SHA-256。如果已安装 Skill 的内容和 manifest 记录不一致，默认报告 conflict 并保留用户修改：

timecho-cli setup skills \
  --source ./skills \
  --agent codex

明确允许替换时：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --force

当前 --force 也可能替换同名但未被 manifest 管理的 Skill 目录。使用前必须先运行 --dry-run 并确认目标路径。

单个文件系统目标的安装会在目标文件系统中 staging，并在 Skill/manifest 提交失败时尝试回滚。

14.10 为 TRAE Work 导出上传包

TRAE Work 是上传型目标，必须显式选择并提供 --export-dir：

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work \
  --export-dir ./dist/trae-work-skills \
  --dry-run

正式导出 ZIP：

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work \
  --export-dir ./dist/trae-work-skills \
  --package-format zip

导出 .skill 包：

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work \
  --export-dir ./dist/trae-work-skills \
  --package-format skill

auto 对 TRAE Work 当前解析为 zip。

14.11 为 WorkBuddy 导出上传包

timecho-cli setup skills \
  --source ./skills \
  --agent workbuddy \
  --export-dir ./dist/workbuddy-skills

WorkBuddy 当前只接受 ZIP：

timecho-cli setup skills \
  --source ./skills \
  --agent workbuddy \
  --export-dir ./dist/workbuddy-skills \
  --package-format zip

以下写法会失败：

timecho-cli setup skills \
  --source ./skills \
  --agent workbuddy \
  --export-dir ./dist/workbuddy-skills \
  --package-format skill

14.12 Workspace 级上传包

workspace scope 只用于 TRAE Work / WorkBuddy 上传型导出，并要求 --workspace：

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work \
  --scope workspace \
  --workspace telemetry-team \
  --export-dir ./dist/trae-workspace-skills

timecho-cli setup skills \
  --source ./skills \
  --agent workbuddy \
  --scope workspace \
  --workspace telemetry-team \
  --export-dir ./dist/workbuddy-workspace-skills

文件系统 Agent 不接受 workspace scope；上传型 Agent 不接受 project scope。

14.13 同时为 TRAE Work 和 WorkBuddy 导出

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work,workbuddy \
  --export-dir ./dist/upload-skills

当同时选择两个上传型 Agent 时，输出分别写入：

./dist/upload-skills/trae-work
./dist/upload-skills/workbuddy

因为 WorkBuddy 不接受 .skill，同时导出时应使用默认 auto 或显式 zip：

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work,workbuddy \
  --export-dir ./dist/upload-skills \
  --package-format zip

14.14 同时执行文件系统安装和上传包导出

混合目标必须提供 --export-dir。由于文件系统和上传目标共同接受的 scope 只有 user，混合执行应使用默认 user scope：

timecho-cli setup skills \
  --source ./skills \
  --agent codex,workbuddy \
  --export-dir ./dist/workbuddy-skills \
  --dry-run

正式执行：

timecho-cli setup skills \
  --source ./skills \
  --agent codex,workbuddy \
  --export-dir ./dist/workbuddy-skills

14.15 上传包内容与状态

每个 Skill 生成一个独立包，包根目录直接包含：

SKILL.md
scripts/       # 仅当原 Skill 存在
references/    # 仅当原 Skill 存在
assets/        # 仅当原 Skill 存在

导出目录还包含：

export-manifest.json
checksums.txt
IMPORT.md
<skill-name>.zip 或 <skill-name>.skill

正常导出后的状态是：

delivery_mode: import-package
delivery_status: awaiting-import

这表示包已经生成，仍需在 TRAE Work 或 WorkBuddy 中人工完成导入。当前实现不进行浏览器自动上传、私有 API 调用、远端状态查询、启停或回滚。已存在且由 export-manifest.json 管理的导出目录，如果内容完全一致会跳过；内容不同默认冲突，可使用 --force 替换。非空但没有 manifest 的目录视为 unmanaged，即使传入 --force 也不会覆盖。

14.16 Agent 名称与别名

正式名称：

claude
codex
codebuddy
openclaw
hermes
trae
trae-cn
trae-work
workbuddy
all

当前保留以下兼容别名：

输入	归一化结果
`claude-code`	`claude`
`code-buddy`	`codebuddy`
`traework`	`trae-work`
`work-buddy`	`workbuddy`

名称不区分大小写，但文档和自动化脚本建议始终使用正式小写名称。

14.17 安全与行为边界

Skill 名称只能包含小写字母、数字和连字符，长度 1–64，且不能以连字符开头或结尾。
目录名必须与 SKILL.md frontmatter 中的 name 一致。
SKILL.md 必须包含 name 和 description。
Skill 源或包中的 symlink 会被拒绝。
安装器只复制/打包文件，不执行 Skill 中的脚本。
归档会检查 traversal、绝对路径、链接、大小限制和异常 entry。
--dry-run 不产生安装或导出副作用。
上传包采用确定性文件顺序、固定时间戳和权限，便于稳定校验。

15. 版本信息

15.1 `version`

timecho-cli version

JSON 输出：

timecho-cli version --json

也可以写成：

timecho-cli --json version

输出内容包括：

CLI 版本。
Git Commit。
构建日期。
发布渠道。
Go 版本。
操作系统和 CPU 架构。

16. Shell Completion

16.1 Bash

当前终端临时启用：

source <(timecho-cli completion bash)

永久安装：

timecho-cli completion bash \
  > ~/.local/share/bash-completion/completions/timecho-cli

16.2 Zsh

timecho-cli completion zsh \
  > "${fpath[1]}/_timecho-cli"

然后重新启动 Zsh：

exec zsh

16.3 Fish

mkdir -p ~/.config/fish/completions

timecho-cli completion fish \
  > ~/.config/fish/completions/timecho-cli.fish

16.4 PowerShell

当前会话临时启用：

timecho-cli completion powershell |
  Out-String |
  Invoke-Expression

写入 PowerShell Profile：

timecho-cli completion powershell |
  Out-File -Append -Encoding utf8 $PROFILE

如果 Profile 不存在：

New-Item -ItemType File -Force $PROFILE
timecho-cli completion powershell |
  Out-File -Append -Encoding utf8 $PROFILE

17. 结构化输出、退出码与自动化

17.1 JSON 成功 Envelope

timecho-cli --json \
  --trace-id build-check-001 \
  version

输出结构：

{
  "ok": true,
  "api_version": "timecho.com/timecho-cli/v1alpha1",
  "command": "timecho-cli version",
  "data": {
    "version": "1.0.0",
    "commit": "0123456789ab",
    "date": "2026-07-29T00:00:00Z",
    "channel": "stable",
    "go": "go1.25.0",
    "os": "linux",
    "arch": "amd64"
  },
  "meta": {
    "trace_id": "build-check-001",
    "duration_ms": 1
  },
  "notices": []
}

data 的具体字段由命令决定；脚本应先判断 ok，再解析命令数据。

17.2 JSON 错误 Envelope

构造一个本地参数错误：

timecho-cli --json sql

错误写入 stderr，结构类似：

{
  "ok": false,
  "api_version": "timecho.com/timecho-cli/v1alpha1",
  "command": "timecho-cli sql",
  "error": {
    "type": "validation",
    "code": "sql_source",
    "message": "exactly one SQL source is required",
    "hint": "pass one positional SQL, --file, or --stdin",
    "retryable": false,
    "param": "sql"
  },
  "meta": {},
  "notices": []
}

自动化逻辑应优先判断 error.type 和 error.code，不要依赖完整英文 message。

17.3 stdout 与 stderr

JSON 成功：stdout；
JSON 失败：stderr；
CSV 查询结果：纯 stdout；
human 最终数据：stdout；
human 错误、提示和 verbose 诊断：stderr。

Bash 分离输出：

timecho-cli --json version \
  >result.json \
  2>error.json

PowerShell：

timecho-cli --json version `
  1> .\result.json `
  2> .\error.json

17.4 退出码

退出码	含义
`0`	成功
`1`	数据库操作错误，或未映射到专用退出码的一般错误
`2`	参数或输入校验错误
`3`	配置、凭据或一般冲突
`4`	网络或协议错误
`5`	内部错误
`6`	不支持或策略拒绝
`7`	Partial，已有部分结果但部分采集/处理失败
`10`	缺少写操作确认
`130`	操作被中断

Bash：

timecho-cli --json version
code=$?
echo "$code"

PowerShell：

timecho-cli --json version
$code = $LASTEXITCODE
Write-Output $code

17.5 非交互式配置写入

先执行 Dry Run：

timecho-cli --json \
  --non-interactive \
  config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --dry-run

审查通过后显式确认：

timecho-cli --json \
  --non-interactive \
  --yes \
  config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1

如果正式写入时没有 --yes，命令返回 confirmation_required，不会提示或修改文件。

17.6 CI 中安装内置 Skills

使用临时目标，避免写入执行器真实 Agent 目录：

target="$(mktemp -d)"

timecho-cli --json \
  --non-interactive \
  setup skills \
  --agent codex \
  --target-dir "$target" \
  --dry-run

timecho-cli --json \
  --non-interactive \
  setup skills \
  --agent codex \
  --target-dir "$target"

PowerShell：

$target = Join-Path $env:TEMP ("timechodb-ci-skills-" + [guid]::NewGuid())

timecho-cli --json `
  --non-interactive `
  setup skills `
  --agent codex `
  --target-dir $target `
  --dry-run

timecho-cli --json `
  --non-interactive `
  setup skills `
  --agent codex `
  --target-dir $target

18. 密码使用示例

CLI 的密码读取顺序为：

--password-stdin
TIMECHODB_PASSWORD
操作系统 Keychain

18.1 使用环境变量

Bash：

export TIMECHODB_PASSWORD='your-password'
timecho-cli --ctx prod status

PowerShell：

$env:TIMECHODB_PASSWORD = "your-password"
timecho-cli --ctx prod status

使用完成后清除：

unset TIMECHODB_PASSWORD

PowerShell：

Remove-Item Env:TIMECHODB_PASSWORD

18.2 使用 stdin

Bash：

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod status --password-stdin

PowerShell：

$env:TIMECHODB_PASSWORD |
  timecho-cli --ctx prod status --password-stdin

18.3 使用 Keychain

添加 Context 时写入：

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli ctx add prod \
    --host db.example.com \
    --password-stdin

后续直接使用：

timecho-cli --ctx prod status
timecho-cli --ctx prod sql "show version"

19. 完整操作流程示例

19.1 添加连接

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli ctx add prod \
    --host db.example.com \
    --port 6667 \
    --user root \
    --dialect tree \
    --password-stdin

19.2 切换上下文

timecho-cli ctx use prod

19.3 检查版本

timecho-cli sql "show version"

19.4 查看状态

timecho-cli status

19.5 查询数据

timecho-cli --json sql \
  "select * from root.demo.device1 limit 100"

19.6 导入 CSV

timecho-cli data import csv data.csv \
  --batch-size 1000 \
  --max-bad-rows 10 \
  --error-file rejected.csv

19.7 导出 CSV

timecho-cli data export csv \
  --sql "select * from root.demo.device1" \
  --out device1.csv

19.8 获取机器码

timecho-cli activate machine-code

19.9 应用激活码

printf '%s' "$ACTIVATION_CODE" |
  timecho-cli activate apply --stdin

19.10 验证激活状态

timecho-cli activate status

19.11 检查本地配置

timecho-cli config get \
  --all \
  --home /opt/timecho \
  --db-version 2.0.6.1

19.12 修改配置

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --dry-run

确认后写入：

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --yes

19.13 生成诊断包

timecho-cli diagnose \
  --local \
  --home /opt/timecho \
  --bundle ./timecho-diagnose.zip

19.14 安装 Codex Skills

timecho-cli setup skills \
  --version 1.0.0 \
  --agent codex \
  --scope user