腾讯云命令行工具 TCCLI 通用参数

TCCLI 提供了一组通用参数，这些参数可以在所有服务和接口调用中使用。本章节详细说明所有通用参数的用法。
参数分类速查
分类
参数
认证相关
--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
﻿
# 配置默认 endpoint
tccli 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=test
tccli 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
超时与轮询参数
--timeout
指定单次 API 请求的超时时间。
类型：Integer（单位：秒）
适用场景：
处理大量数据的查询接口。
长时间运行的操作。
网络不稳定时需要延长超时。
示例：
# 设置超时时间为 60 秒
tccli cvm DescribeInstances --timeout 60
注意：
--timeout: 控制单次请求的超时时间。
--waiter 的 timeout: 控制轮询操作的总超时时间（包含多次请求）。
--waiter
轮询实例状态直到满足指定条件。
类型：JSON String
必需参数：
expr：查询表达式（JMESPath 语法）
to：目标状态值
可选参数：
timeout：轮询超时时间（秒）
interval：轮询间隔时间（秒）
示例：
# 基本用法：等待实例状态变为 RUNNING
tccli 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
  }
}
适用场景：
等待实例启动完成
等待异步任务完成
等待资源状态变更
高级功能参数
--generate-cli-skeleton
输出参数骨架（用于生成 JSON 模板）。
类型：String（可选值）
可选值：input（默认）
示例：
# 生成 input 参数模板
tccli cvm RunInstances --generate-cli-skeleton > /tmp/RunInstances.json
--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
适用场景：
批量操作：相同参数创建多个资源
复杂参数：参数较多时避免命令行过长
脚本化：便于版本控制和复用
--cli-unfold-argument
复杂类型参数展开为点分格式。
类型：Boolean（开关参数）
示例：
tccli cvm RunInstances --cli-unfold-argument
网络代理参数
--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:1111
tccli cvm DescribeRegions
﻿
# 方式三：环境变量（Windows）
set http_proxy=https://myproxy.com:1111
tccli cvm DescribeRegions
﻿
# 永久设置（Windows）
setx http_proxy=https://myproxy.com:1111
说明：建议优先使用环境变量配置代理，方便全局生效。
调试与日志参数
--warning
开启警告日志。
类型：Boolean（开关参数）
默认：关闭
配置文件：支持
示例：
tccli cvm DescribeInstances --warning
配置方式：
tccli configure set warning on
参数优先级
当多种方式配置同一参数时，TCCLI 按以下优先级生效（从高到低）：
1. 命令行参数：直接在命令行指定。
2. 环境变量：通过 export 或 set 设置。
3. 配置文件：通过 tccli configure 配置。
4. 默认值：系统内置默认值。
示例：
# 配置文件中 region = ap-beijing
tccli configure set region ap-beijing
﻿
# 环境变量设置 region = ap-shanghai
export TENCENTCLOUD_REGION=ap-shanghai
﻿
# 命令行指定 region = ap-guangzhou
tccli cvm DescribeInstances --region ap-guangzhou
﻿
# 实际生效: ap-guangzhou（命令行优先级最高）
常见问题
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 秒
Q2：如何管理多个腾讯云账号？
使用 --profile 参数管理多个账号配置：
# 1. 配置账号 A（默认账号）
tccli configure
# 输入 secretId、secretKey、region 等
﻿
# 2. 配置账号 B
tccli configure --profile account-b
# 输入账号 B 的 secretId、secretKey、region 等
﻿
# 3. 使用账号 A（默认）
tccli cvm DescribeInstances
﻿
# 4. 使用账号 B
tccli cvm DescribeInstances --profile account-b
﻿
# 5. 设置环境变量使用账号 B
export TCCLI_PROFILE=account-b
tccli cvm DescribeInstances  # 自动使用账号 B
Q3：如何查看所有可用参数？
# 查看 TCCLI 总体帮助（包含通用参数）
tccli help
﻿
# 查看服务帮助
tccli cvm help
﻿
# 查看接口帮助（包含接口特定参数）
tccli cvm DescribeInstances help
﻿
# 查看详细帮助
tccli cvm DescribeInstances help --detail
Q4：如何在脚本中使用 TCCLI？
方法一：直接调用
#!/bin/bash
tccli 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.json
done
方法三：结合 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
使用建议
安全建议
使用 tccli configure 配置密钥，避免在命令行明文传递。
生产环境建议使用角色授权（--role-arn）或 CVM 角色（--use-cvm-role）。
临时操作使用临时密钥（--token）。
避免在脚本中硬编码密钥。
性能建议
网络不稳定：增加 --timeout
长时操作：使用 --waiter 轮询状态
大量数据：结合 --filter 过滤结果
效率建议
多账号管理：使用 --profile
批量操作：使用 --generate-cli-skeleton + --cli-input-json
脚本调试：使用 --output table + --warning
结果处理：善用 --filter 和 JMESPath

分类	参数
认证相关	--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

特性	--timeout	--waiter timeout
作用对象	单次 API 请求	轮询操作总时长
单位	秒	秒
包含请求次数	1 次	多次（根据 interval 计算）
适用场景	防止单次请求超时	等待异步操作完成

TCCLI 通用参数

本页目录：

参数分类速查

认证相关参数

--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

参数优先级

常见问题

Q1：--timeout 与 --waiter 的 timeout 有什么区别？

Q2：如何管理多个腾讯云账号？

Q3：如何查看所有可用参数？

Q4：如何在脚本中使用 TCCLI？

使用建议

安全建议

性能建议

效率建议