天翼云 CLI 的配置项包括访问凭证、输出格式和日志行为。所有配置项均支持三种配置方式，优先级从高到低为：

命令行参数 > 配置文件 > 环境变量

交互式配置

运行 configure 命令，按提示逐项输入：

ctyun-cli configure

交互过程：

[INFO] 开始配置天翼云CLI...
Access Key [dd2b****786d3]:           # 输入 AccessKey，已有配置时掩码显示
Secret Key [7cf0****120e]:            # 输入 SecretKey，输入时关闭回显
输出格式 (json/table) [json]:
开启日志 (true/false) [false]:
日志文件路径 []:
日志格式 (text/json) [text]:
[OK] 配置已保存到 ~/.ctyun-cli.yaml

• AccessKey / SecretKey 输入时关闭终端回显，防止敏感信息泄露

• 已有配置值时，AccessKey / SecretKey 以掩码形式显示（如 dd2b****786d3），其他字段明文显示

• 直接按回车可保留当前值

配置文件

配置文件默认路径：

• Linux / macOS：~/.ctyun-cli.yaml

• Windows：%USERPROFILE%\.ctyun-cli.yaml

也可通过 --config / -c 指定其他路径：

ctyun-cli vpc ListVpc --regionID bb9fdb42056f11eda1610242ac110002 --config /path/to/config.yaml

手动创建或编辑配置文件：

# ~/.ctyun-cli.yaml
access_key: "your-access-key"    # 天翼云 AccessKey
secret_key: "your-secret-key"    # 天翼云 SecretKey
output: "json"                   # 输出格式 (json/table)
log: false                       # 是否开启日志
log_file: ""                     # 日志文件路径；为空时输出到 stderr
log_format: "text"               # 日志格式 (text/json)

访问凭证

天翼云 CLI 通过 AccessKey / SecretKey 对调用方进行身份认证。调用任何 API 操作前，必须先完成认证信息的配置。AccessKey / SecretKey的获取点击此处

环境变量

适合 CI/CD 等自动化场景：

# Linux / macOS
export CTYUN_AK="your-access-key"
export CTYUN_SK="your-secret-key"

# Windows PowerShell
$env:CTYUN_AK="your-access-key"
$env:CTYUN_SK="your-secret-key"

也可在单次命令中临时指定：

CTYUN_AK="your-access-key" CTYUN_SK="your-secret-key" ctyun-cli vpc ListVpc --regionID bb9fdb42056f11eda1610242ac110002

命令行参数

通过 --access-key / -a 和 --secret-key / -s 直接传入：

ctyun-cli vpc ListVpc --regionID bb9fdb42056f11eda1610242ac110002 -a your-access-key -s your-secret-key

安全建议

• 不要将 AccessKey / SecretKey 硬编码在脚本中，优先使用环境变量或配置文件

• 不要长期将 AccessKey / SecretKey 写在 Shell 命令中，Shell 历史记录会保存明文密钥

• 配置文件建议设置文件权限为仅当前用户可读

• 生产环境建议使用环境变量，避免密钥落盘

• 命令行参数方式会将密钥暴露在进程列表中，仅用于临时调试

• CLI 日志不会记录 AccessKey 和 SecretKey

输出格式

通过 --output / -o 控制返回结果的展示格式，支持 json（默认）和 table：

# JSON 输出（默认）
ctyun-cli vpc ListVpc --regionID bb9fdb42056f11eda1610242ac110002

# Table 输出
ctyun-cli vpc ListVpc --regionID bb9fdb42056f11eda1610242ac110002 -o table

通过 --cli-query 可使用 JMESPath 表达式对返回结果进行过滤。

埋点与日志

默认不输出日志。开启 --log 后，CLI 会记录命令调用和 HTTP 请求的结构化日志：

# 输出日志到 stderr
ctyun-cli vpc ListVpc --regionID bb9fdb42056f11eda1610242ac110002 --log true

# 写入文件并记录请求/响应
ctyun-cli vpc ListVpc --regionID bb9fdb42056f11eda1610242ac110002 --log true --log-file ./ctyun-cli.log

日志参数说明

环境变量

也可通过环境变量控制日志行为：

优先级规则

当多种方式同时配置时，CLI 按以下优先级取值：

命令行参数 > 配置文件 > 环境变量

示例：若配置文件中设置了 access_key: "key-from-file"，同时环境变量 CTYUN_AK="key-from-env"，则 CLI 使用配置文件中的值；若再通过 --access-key key-from-cli 传入，则使用命令行参数的值。

全局参数一览

以下参数可附加在任何命令之后：

  -c, --config string       指定配置文件路径（默认 ~/.ctyun-cli.yaml）  
  -o, --output string       输出格式 (json|table，默认 json)      
      --cli-query string    JMESPath 查询表达式，用于筛选 API 返回结果  
  -a, --access-key string   天翼云 AccessKey  
  -s, --secret-key string   天翼云 SecretKey      
      --log                 开启日志          
      --log-file string     日志文件路径，默认输出到 stderr      
      --log-format string   日志格式 (text|json，默认 text)