TiDB Cloud CLI (ti) 命令参考

本页介绍 TiDB Cloud CLI (ti) 命令共享的命令结构和行为。要查看单个命令的语法和选项，请选择其命令组或使用文档导航。

语法

ti <command> [options] [global options]
ti <command-group> <command> [options] [global options]

例如：

ti configure --profile staging
ti db list-db-clusters --db-cluster-type starter

ti 可执行文件仅接受长选项。像 -p 这样的单字母选项会被拒绝。

在生成的用法说明中，必需选项应写在可选选项之前，并使用方括号括起可选选项：

ti db describe-db-cluster
  --db-cluster-id <string>
  [--output <string>]
  [--view <string>]

值类型使用尖括号括起。在命令帮助中，每个必需选项的名称和类型后面都会跟随 (required)：

--db-cluster-name <string> (required)   Starter DB cluster display name
--wait                                  Wait until the created cluster is active

命令和命令组

使用下表查找顶层命令或命令组的参考文档。每个命令页面都包含其语法、选项和示例。

要在终端中列出可用命令，请运行 ti help 或 ti <command-group> help。

全局选项

• --debug：启用已脱敏的调试输出。
• --output <string>：将输出格式设置为 json 或 text。[default: json]
• --profile <string>：选择本地配置（Profile）。[default: default]
• --query <string>：在渲染输出之前应用 JMESPath 表达式。
• --region <string>：为当前命令覆盖配置中的默认 Region 代码，例如 aws-us-east-1。

命令页面会单独记录 --help、--version 以及所有命令特定选项。

输出

返回结构化数据的命令默认使用 JSON：

ti db list-db-clusters --db-cluster-type starter

使用文本输出可获得更适合人工阅读的表示形式：

ti db list-db-clusters --db-cluster-type starter --output text

像 ti fs read-file 和 ti fs copy-file --to-stdout 这样的原始字节导向命令会直接写出文件内容。

JMESPath 查询

--query 会在命令成功执行之后、输出渲染之前运行：

ti db list-db-clusters \
  --db-cluster-type starter \
  --query 'clusters[].{id:id,name:display_name,state:state}'

无效的表达式会导致失败，不会用部分输出替代命令结果。

试运行 (Dry-run)

支持 --dry-run 的变更型控制平面命令会验证本地选项、配置、凭证、Region 和请求结构，然后在不执行远程变异的情况下报告一个计划。

ti db delete-db-cluster \
  --db-cluster-id "<cluster-id>" \
  --dry-run

只读命令会拒绝 --dry-run。该选项不是全局模拟选项，仅在命令帮助中显示时才可用。

帮助和版本形式

运行 ti 而不带命令时，会返回退出码 2，并将紧凑的命令树概要打印到 stderr：

ti [ERROR]: the following arguments are required: command

The TiDB Cloud Command Line Interface is a unified tool to manage your TiDB Cloud Filesystem (FS) and Starter services.

usage: ti <command> [<subcommand>] [parameters]
To see help information, you can run:

  ti help
  ti <command> help
  ti <command> <subcommand> help

使用显式帮助形式来显示命令和选项：

ti help
ti db help
ti db create-db-cluster help
ti --help
ti --version

help 是一个用于浏览命令层级的命令。--help 在每个命令上都可用；这两种形式是有意并存的。--version 选项在每个命令级别也都可用，并报告同一个 ti 可执行文件的版本。

错误和退出行为

人类可读的错误信息以一个空行开头，并使用稳定的前缀：

ti [ERROR]: <message>

错误会写入 stderr，成功的命令输出会写入 stdout。用法和配置失败会在远程变异发生之前返回非零退出码。运行时和远程 API 失败也会返回非零退出码。交互式配置被中断时会返回退出码 130。

--debug 可以显示已脱敏的请求和解析上下文。它不得显示 API key、FS token、DB 密码、SQL 文本、文件内容或连接字符串。

相关文档

有关配置、安全性、兼容性和故障排查的详细信息，请参阅以下文档：

发布说明

有关 TiDB Cloud CLI (ti) 的最新变更，请参阅 TiDB Cloud CLI (ti) Release Notes。