一、参数分类速查
| 分类 | 参数 |
| 认证相关 | –secretId, –secretKey, –token, –role-arn, –role-session-name, –use-cvm-role |
| 区域与接入点 | –region, –endpoint |
| 版本与配置 | –version, –profile |
| 输出相关 | –output, –filter, –language |
| 超时与轮询 | –timeout, –waiter |
| 高级功能 | –generate-cli-skeleton, –cli-input-json, –cli-unfold-argument |
| 网络代理 | –https-proxy |
| 调试与日志 | –warning |
三、–secretId
指定腾讯云 API 密钥 SecretId。
·类型：String
·环境变量：TENCENTCLOUD_SECRET_ID
·配置文件：支持
示例：
tccli cvm DescribeInstances –secretId AKID******
注意：说明：建议使用 tccli configure 配置密钥，避免在命令行明文传递。
四、–secretKey
指定腾讯云 API 密钥 SecretKey。
·类型：String
·环境变量：TENCENTCLOUD_SECRET_KEY
·配置文件：支持
示例：
tccli cvm DescribeInstances –secretKey ******
五、–token
临时证书 Token，用于临时密钥场景（如 STS）。
·类型：String
·环境变量：TENCENTCLOUD_TOKEN
·配置文件：支持
示例：
tccli cvm DescribeInstances –token <临时token>
六、–role-arn
指定角色 ARN（角色扮演场景）。
·类型：String
·环境变量：TENCENTCLOUD_ROLE_ARN
示例：
tccli cvm DescribeInstances –role-arn qcs::cam::uin/100001:role/role-name
七、–role-session-name
指定角色会话名称。
·类型：String
·环境变量：TENCENTCLOUD_ROLE_SESSION_NAME
示例：
tccli cvm DescribeInstances –role-session-name my-session
八、–use-cvm-role
使用 CVM 角色获取密钥，适用于在 CVM 实例中运行 TCCLI。
·类型：Boolean（开关参数）
示例：
tccli cvm DescribeInstances –use-cvm-role
十、–region
指定要操作的资源所属地域。
·类型：String
·环境变量：TENCENTCLOUD_REGION
·配置文件：支持
示例：
tccli cvm DescribeInstances –region ap-guangzhou
常用地域：
·ap-guangzhou: 广州
·ap-shanghai: 上海
·ap-beijing: 北京
十一、–endpoint
指定访问点域名。可用于指定最近的接入点或私有化部署场景。
·类型：String
·配置文件：支持（格式: 服务名.endpoint）
示例：
# 指定 CVM 广州接入点tccli cvm DescribeInstances –endpoint cvm.ap-guangzhou.tencentcloudapi.com# 配置默认 endpointtccli configure set cvm.endpoint cvm.ap-guangzhou.tencentcloudapi.com
十三、–version
指定接口版本，用于访问特定旧版本的接口。
·类型：String（日期格式: YYYY-MM-DD）
·配置文件：支持（格式: 服务名.version）
示例：
# 指定 CVM 2017-03-12 版本tccli cvm DescribeZones –version 2017-03-12# 配置默认版本tccli configure set cvm.version 2017-03-12
注意：与 tccli –version（显示工具版本）不同。
十四、–profile
指定配置文件名，用于多账户管理。
·类型：String
·环境变量：TCCLI_PROFILE
·默认值: default
示例：
# 使用名为 test 的配置tccli cvm DescribeInstances –profile test# 或使用环境变量export TCCLI_PROFILE=testtccli cvm DescribeInstances
多账户配置：
# 配置 test 账户tccli configure –profile test# 使用 test 账户tccli cvm DescribeInstances –profile test
十六、–output
指定输出格式。
·类型：String（枚举）
·可选值：json | text | table
·默认值：json
·配置文件：支持
示例：
# JSON 格式（默认）tccli cvm DescribeInstances –output json# 表格格式（易读）tccli cvm DescribeInstances –output table# 文本格式（适合脚本处理）tccli cvm DescribeInstances –output text
十七、–filter
使用 JMESPath 语法过滤返回结果字段。
·类型：String（JMESPath 表达式）
·JMESPath 文档：https://jmespath.org/
示例：
# 只看某个字段tccli cvm DescribeZones –filter TotalCount# 输出: 4# 指定数组第一个元素tccli cvm DescribeZones –filter ZoneSet[0]# 输出: {"ZoneState": "AVAILABLE", "ZoneId": "100001", …}# 获取所有元素的某个字段tccli cvm DescribeZones –filter ZoneSet[*].ZoneName# 输出: ["广州一区", "广州三区", "广州四区"]# 重命名字段tccli cvm DescribeZones –filter 'ZoneSet[*].{name:ZoneName, id:ZoneId}'# 输出: [{"name": "广州一区", "id": "100001"}, …]# 高级过滤：筛选标签tccli cvm DescribeInstances –region ap-hongkong \\ –filter 'InstanceSet[].[InstanceId,InstanceName,Tags[?Key==`app`].Value|[0]]' \\ –output text
十八、–language
指定输出语言。
·类型：String（枚举）
·可选值：zh-CN | en-US
·默认值：zh-CN
示例：
tccli cvm DescribeInstances –language en-US
20、–timeout
指定单次 API 请求的超时时间。
·类型：Integer（单位：秒）
·适用场景：
·处理大量数据的查询接口。
·长时间运行的操作。
·网络不稳定时需要延长超时。
示例：
# 设置超时时间为 60 秒tccli cvm DescribeInstances –timeout 60
21、–waiter
轮询实例状态直到满足指定条件。
·类型：JSON String
·必需参数：
·expr：查询表达式（JMESPath 语法）
·to：目标状态值
·可选参数：
·timeout：轮询超时时间（秒）
·interval：轮询间隔时间（秒）
示例：
# 基本用法：等待实例状态变为 RUNNINGtccli cvm DescribeInstancesStatus –region ap-hongkong \\ –waiter "{'expr':'InstanceStatusSet[0].InstanceState','to':'RUNNING'}"# 自定义超时和间隔tccli cvm DescribeInstancesStatus –region ap-hongkong \\ –waiter "{'expr':'InstanceStatusSet[0].InstanceState','to':'RUNNING','timeout':180,'interval':5}"
配置文件设置：
{ "waiter": { "interval": 5, "timeout": 180 }}
适用场景：
·等待实例启动完成
·等待异步任务完成
·等待资源状态变更
23、–generate-cli-skeleton
输出参数骨架（用于生成 JSON 模板）。
·类型：String（可选值）
·可选值：input（默认）
示例：
# 生成 input 参数模板tccli cvm RunInstances –generate-cli-skeleton > /tmp/RunInstances.json
24、–cli-input-json
从 JSON 文件读取参数。
·类型：String（文件路径）
·路径格式：file:// + 文件绝对路径
工作流程：
# 1. 生成骨架文件tccli cvm RunInstances –generate-cli-skeleton > /tmp/RunInstances.json# 2. 编辑 JSON 文件填写参数vim /tmp/RunInstances.json# 3. 从文件读取参数执行tccli cvm RunInstances –cli-input-json file:///tmp/RunInstances.json
适用场景：
·批量操作：相同参数创建多个资源
·复杂参数：参数较多时避免命令行过长
·脚本化：便于版本控制和复用
25、–cli-unfold-argument
复杂类型参数展开为点分格式。
·类型：Boolean（开关参数）
示例：
tccli cvm RunInstances –cli-unfold-argument
27、–https-proxy
指定 HTTPS 代理服务器。
·类型：String（URL）
·环境变量：https_proxy 或 http_proxy
示例：
# 方式一：命令行指定tccli cvm DescribeRegions –https-proxy https://192.168.1.1:1111# 方式二：环境变量（Linux/macOS）export https_proxy=https://myproxy.com:1111tccli cvm DescribeRegions# 方式三：环境变量（Windows）set http_proxy=https://myproxy.com:1111tccli cvm DescribeRegions# 永久设置（Windows）setx http_proxy=https://myproxy.com:1111
注意：说明：建议优先使用环境变量配置代理，方便全局生效。
29、–warning
开启警告日志。
·类型：Boolean（开关参数）
·默认：关闭
·配置文件：支持
示例：
tccli cvm DescribeInstances –warning
配置方式：
tccli configure set warning on
30、参数优先级
当多种方式配置同一参数时，TCCLI 按以下优先级生效（从高到低）：
1. 命令行参数：直接在命令行指定。
2. 环境变量：通过 export 或 set 设置。
3. 配置文件：通过 tccli configure 配置。
4. 默认值：系统内置默认值。
示例：
# 配置文件中 region = ap-beijingtccli configure set region ap-beijing# 环境变量设置 region = ap-shanghaiexport TENCENTCLOUD_REGION=ap-shanghai# 命令行指定 region = ap-guangzhoutccli cvm DescribeInstances –region ap-guangzhou# 实际生效: ap-guangzhou（命令行优先级最高）
32、Q1：–timeout 与 –waiter 的 timeout 有什么区别？
| 特性 | –timeout | –waiter timeout |
| 作用对象 | 单次 API 请求 | 轮询操作总时长 |
| 单位 | 秒 | 秒 |
| 包含请求次数 | 1 次 | 多次（根据 interval 计算） |
| 适用场景 | 防止单次请求超时 | 等待异步操作完成 |
示例：
# –timeout: 单次请求最多等 60 秒tccli cvm DescribeInstances –timeout 60# –waiter timeout: 总共轮询 180 秒（每 5 秒查询一次）tccli cvm DescribeInstancesStatus \\ –waiter "{'expr':'…','to':'RUNNING','timeout':180,'interval':5}"# 结合使用tccli cvm DescribeInstancesStatus –timeout 30 \\ –waiter "{'expr':'…','to':'RUNNING','timeout':180,'interval':5}"# 含义：每次请求超时 30 秒，总共轮询 180 秒
33、Q2：如何管理多个腾讯云账号？
使用 –profile 参数管理多个账号配置：
# 1. 配置账号 A（默认账号）tccli configure# 输入 secretId、secretKey、region 等# 2. 配置账号 Btccli configure –profile account-b# 输入账号 B 的 secretId、secretKey、region 等# 3. 使用账号 A（默认）tccli cvm DescribeInstances# 4. 使用账号 Btccli cvm DescribeInstances –profile account-b# 5. 设置环境变量使用账号 Bexport TCCLI_PROFILE=account-btccli cvm DescribeInstances # 自动使用账号 B
34、Q3：如何查看所有可用参数？
# 查看 TCCLI 总体帮助（包含通用参数）tccli help# 查看服务帮助tccli cvm help# 查看接口帮助（包含接口特定参数）tccli cvm DescribeInstances help# 查看详细帮助tccli cvm DescribeInstances help –detail
35、Q4：如何在脚本中使用 TCCLI？
方法一：直接调用
#!/bin/bashtccli cvm DescribeInstances –region ap-guangzhou –output json
方法二：使用参数文件
#!/bin/bash# 1. 生成参数模板tccli cvm RunInstances –generate-cli-skeleton > params.json# 2. 编辑参数# … 修改 params.json …# 3. 批量执行for i in {1..5}; do tccli cvm RunInstances –cli-input-json file://$(pwd)/params.jsondone
方法三：结合 jq 处理输出
#!/bin/bash# 获取实例 ID 列表instance_ids=$(tccli cvm DescribeInstances \\ –region ap-guangzhou \\ –filter 'InstanceSet[*].InstanceId' \\ –output json | jq -r '.[]')for id in $instance_ids; do echo "Processing: $id" # 进一步操作…done
37、安全建议
·使用 tccli configure 配置密钥，避免在命令行明文传递。
·生产环境建议使用角色授权（–role-arn）或 CVM 角色（–use-cvm-role）。
·临时操作使用临时密钥（–token）。
·避免在脚本中硬编码密钥。
38、性能建议
·网络不稳定：增加 –timeout
·长时操作：使用 –waiter 轮询状态
·大量数据：结合 –filter 过滤结果
39、效率建议
·多账号管理：使用 –profile
·批量操作：使用 –generate-cli-skeleton + –cli-input-json
·脚本调试：使用 –output table + –warning
·结果处理：善用 –filter 和 JMESPath