mirrors/volcengine-cli

Volcengine Command Line Tools

中文 | English

特别说明

为了便于用户使用，从v1.0.20版本开始，火山引擎CLI工具命令前缀由“volcengine-cli” 更新为“ve”。低版本不受影响，请升级到v1.0.20及以后版本的用户及时更新指令前缀（可参考alias命令统一设置）。

概述

火山引擎-命令行工具
Go版本最低1.5+ 推荐是用1.12+

安装火山引擎CLI

通过release获取客户端

https://github.com/volcengine/volcengine-cli/releases 获取最新版本
下载对应操作系统的版本解压使用

自行编译获取客户端

使用build.sh编译客户端

# 如果是mac 
sh build.sh darwin
mv ve-darwin ve
# 如果是windows
sh build.sh windows
mv ve-windows ve
# 如果是linux
sh build.sh linux
mv ve-linux ve

配置火山引擎CLI

将火山引擎CLI 配置进环境变量

检查一下 $PATH 系统变量是否存在 /usr/local/bin，若没有则请您根据实际情况为火山引擎CLI 设置可用的环境变量
执行下面的命令，将 ve 拷贝至 /usr/local/bin 目录下即可使用
```
sudo cp ve /usr/local/bin
```

配置凭证

调用服务需要用到 AK，SK，region，可以通过以下两种方式进行配置

通过 ve configure set 设置，示例

ve configure set --profile test --region cn-beijing --access-key ak --secret-key sk

支持参数及相关说明

profile: 配置名称，如果 profile 已存在，则该命令会修改已有配置；否则就会新建配置，并将当前使用的profile指定为新配置
access-key: 您的 AK
secret-key: 您的 SK
region: 地域，如 cn-beijing
session-token: 如果使用角色扮演，需要提供
disable-ssl: 是否禁用 ssl，默认为 false
endpoint: 可以不填，默认值为 open.volcengineapi.com；当 endpoint-resolver 为 standard 时该值会被忽略
endpoint-resolver: 可选；指定 endpoint 解析器。设置为 standard（不区分大小写）时使用标准解析器；否则当 endpoint 非空时使用 endpoint
use-dual-stack: 可选；是否启用双栈，默认为 false

若配置文件中无配置，则会尝试从 export 的环境变量中读取配置

export VOLCENGINE_ACCESS_KEY=AK
export VOLCENGINE_SECRET_KEY=SK
export VOLCENGINE_REGION=cn-bejing

# 可选：自定义 endpoint；当 VOLCENGINE_ENDPOINT_RESOLVER=standard 时会忽略
export VOLCENGINE_ENDPOINT=open.volcengineapi.com

# 可选：endpoint 解析器；设置为 standard（不区分大小写）使用标准解析器
export VOLCENGINE_ENDPOINT_RESOLVER=standard

# 可选：是否启用双栈，true/false
export VOLCENGINE_USE_DUALSTACK=false

# 是否禁用SSL, 不设置的话默认为false
export VOLCENGINE_DISABLE_SSL=false

# 如果使用角色扮演，需要提供
export VOLCENGINE_SESSION_TOKEN=sessionToken

configure命令的其他操作

火山引擎CLI使用configure配置profile之后，会优先使用profile中的鉴权信息进行接口签名访问
使用 ve configure set 新增或者修改普通 AK profile 后，当前 configure 中的默认使用 profile 会被切换到新增或者修改的 profile 上；ve configure sso 不会自动切换当前 profile，配置完成后如需默认使用该 SSO profile，请执行 ve configure profile --profile [配置名]
如果存在多个profile，请在调用接口前，使用ve configure profile –profile [配置名] 进行切换，以保证正确的使用

获取指定配置(profile)信息

ve configure get --profile [配置名]

其中 profile 为可选字段，若不指定 profile 字段则会展示当前配置；若指定了 profile 则火山引擎CLI 会尝试获取指定配置并展示

若配置不存在，则返回的配置字段全为默认值

显示当前所有配置(profile)信息

ve configure list

切换当前使用的配置(profile)信息请确保版本大于或者等于>=1.0.16

ve configure profile --profile [配置名]

其中 profile 为必选字段，指定了 profile 则火山引擎CLI 会尝试获切换当前的配值

若配置不存在，当前的配置不会发生切换，并且会给出错误的提示

新建/修改配置(profile)

ve configure set --profile [配置名] --region [地区] --access-key [用户的AK] --secret-key [用户的SK] --endpoint [地区对应的endpoint]

新建或者修改配置后，当前的使用配置会切换到修改的配置上

新建配置时必须指定 profile 字段和 region 字段，修改已有配置必须指定 profile 字段

其余可指定的字段：

access-key
secret-key
region
session-token
disable-ssl
endpoint
endpoint-resolver
use-dual-stack

各个字段的作用您可以参考上节中 “支持参数及相关说明” 部分

删除配置(profile)

ve configure delete --profile [配置名]

删除配置时必须指定 profile 字段以指示需要删除的配置名

若待删除的是当前正在使用的配置，则删除成功后火山引擎CLI 会尝试从剩余的配置中随机挑选一个作为当前配置

SSO 快速上手

SSO 配置分两层：sso-session 保存企业 SSO 入口（Start URL、Region、Scopes），SSO profile 保存某个账号和角色的绑定信息。首次使用建议按下面顺序执行：

# 1. 创建 SSO 会话。registration-scopes 可省略，按提示回车即可使用默认值
ve configure sso-session --name my-sso --start-url https://{custom}.volccloudidentity.com/userportal --region cn-beijing

# 2. 创建 SSO 类型 profile，完成设备码授权，并在交互列表中选择 account 和 role
ve configure sso --profile my-dev --sso-session my-sso

# 3. 将当前默认 profile 切换到刚创建的 SSO profile
ve configure profile --profile my-dev

# 4. 后续直接执行业务命令；STS 过期时 CLI 会按需静默刷新
ve [service] [action] [params]

注意：ve configure sso 会写入 SSO profile，但不会自动修改当前默认 profile。若跳过第 3 步，业务命令仍会使用原来的 current profile。

SSO 命令关系

命令	什么时候用	主要作用	是否切换当前 profile
`ve configure sso-session`	每个 SSO 入口通常配置一次	保存 Start URL、Region、Scopes，可被多个 SSO profile 复用	否
`ve configure sso`	每个 account + role 组合配置一次	关联 SSO 会话，执行首次授权，选择账号和角色，写入 SSO profile	否
`ve configure profile --profile [配置名]`	需要让业务命令默认使用某个 profile 时	切换当前默认 profile	是
`ve sso login`	被提示重新登录，或希望主动刷新 SSO 登录态时	重新执行设备码授权并缓存 access token	否
`ve sso logout`	需要退出某个或全部 SSO 会话时	撤销缓存令牌，删除 token cache，清理 STS 临时凭证	否

配置 SSO 会话 (configure sso-session)

ve configure sso-session --name [会话名] --start-url [SSO Start URL] --region [地区] --registration-scopes [scope1,scope2]

该命令用于新增或修改 SSO 会话，后续可被 ve configure sso 复用。参数说明：

name: SSO 会话名称；未提供时进入交互式选择/创建模式
start-url: SSO Start URL；必填。格式为“用户登录链接 + /userportal”后缀，例如 https://{custom}.volccloudidentity.com/userportal；编辑已有会话时回车可沿用默认值
region: SSO 区域；默认 cn-beijing；编辑已有会话时回车可沿用默认值
registration-scopes: SSO scope 列表（逗号分隔）；可省略，默认 cloudidentity:account:access,offline_access；允许值仅 cloudidentity:account:access 和 offline_access

交互式流程说明：

若当前无任何 SSO 会话，会提示输入会话名，不能为空
若已有会话，会进入可搜索的列表选择，可选 “” 创建新会话
编辑已有会话时，Start URL、Region、Scopes 会回填默认值，回车可沿用
Scopes 会进行 trim、去重与校验；未输入时使用默认值

配置 SSO 类型 profile (configure sso)

ve configure sso --profile [配置名] --sso-session [会话名] [--no-browser]

该命令用于创建或更新 SSO 类型 profile。执行时会关联一个 SSO 会话，走设备码授权流程，拉取账号列表和角色列表供用户选择，最后把 mode=sso、sso-session-name、account-id、role-name、region 写入 ~/.volcengine/config.json。

参数说明：

profile: profile 名称；未输入时可回车，默认使用 {sso-role-name}-{sso-account-id}
sso-session: SSO 会话名称；未输入时进入交互式选择/创建模式
no-browser: 添加 --no-browser 表示禁止自动打开浏览器，适合无图形界面的服务器环境

注意事项：

若指定的 profile 已存在且不是 SSO 类型，将拒绝覆盖并返回错误
若指定的 SSO 会话不存在，将引导创建，并要求输入 Start URL、Region 与 Scopes
configure sso 会完成首次授权和账号/角色选择，但不会切换当前默认 profile；请按需执行 ve configure profile --profile [配置名]
若要切换账号或角色，请重新执行 ve configure sso --profile [配置名] --sso-session [会话名]

日常登录、自动刷新与登出

业务命令的自动刷新

当前默认 profile 为 SSO 类型时，业务命令会自动检查并刷新 STS 临时凭证：

如果 profile 中的 session-token 未过期，直接复用
如果 STS 缺失或已过期，CLI 会使用缓存的 SSO access token 和 profile 中的 account-id / role-name 换取新的 STS，并写回 profile
如果 SSO access token 已过期或接近过期，CLI 只会尝试使用 refresh_token 静默刷新，不会在业务命令中自动打开浏览器
如果没有缓存 access token、refresh_token 缺失、客户端注册过期或刷新失败，业务命令会提示重新执行 ve sso login

ve sso login --profile [配置名]
# 或
ve sso login --sso-session [会话名]
# 或不传参数，按已配置的 sso-session 自动选择/交互选择
ve sso login

ve sso login 用于显式重新登录 SSO，会重新走设备码授权并缓存新的 access token。与 AWS SSO login 语义一致，每次执行都会重新认证当前 SSO 会话，不会使用已有 refresh_token 静默换取 access token。

参数说明：

profile: 指定要使用的 SSO profile；必须存在且类型为 sso，且已配置 sso-session
sso-session: 指定要使用的 SSO 会话；会话必须存在且有效
no-browser: 添加 --no-browser 表示禁止自动打开浏览器

登录行为说明：

未指定 profile 和 sso-session 时：未配置任何会话会返回错误，仅有一个会话时直接使用该会话登录，有多个会话时进入交互式选择（可搜索筛选）
sso login 不会重新选择 account/role；账号和角色来自 ve configure sso 写入的 account-id / role-name
当前仅支持设备码授权流程，--no-browser 用于关闭自动打开浏览器

SSO 登出 (sso logout)

ve sso logout --sso-session [会话名]
# 或不传参数，按已配置的 sso-session 自动选择/交互选择
ve sso logout

ve sso logout 用于退出 SSO 登录态。指定 --sso-session 时退出该会话；不指定时，未配置任何会话会返回错误，仅有一个会话时直接登出该会话，有多个会话时进入交互式选择，并支持选择 “All SSO sessions” 批量登出。

登出会执行：

撤销该 SSO 会话缓存的 refresh token（如果存在）
删除该 SSO 会话的 token cache
清理关联 SSO profile 中的 STS 临时凭证字段：access-key、secret-key、session-token、sts-expiration

登出不会执行：

不删除 SSO profile
不删除 sso-session 配置
不清除 profile 中的 account-id / role-name

因此，登出后如需继续使用原账号和角色，重新执行 ve sso login 即可；如需切换账号或角色，请重新执行 ve configure sso。

SSO 常见问题

执行完 ve configure sso 后业务命令还在使用旧账号怎么办？请执行 ve configure profile --profile [配置名] 切换当前默认 profile。configure sso 只写入 profile，不会自动切换 current profile。
什么时候需要执行 ve sso login？首次 ve configure sso 已完成授权。日常业务命令会自动复用或静默刷新凭证；只有当 CLI 提示重新登录，或者你想主动刷新 SSO 登录态时，再执行 ve sso login。
为什么 ve sso login 每次都会重新打开授权流程？这是显式登录语义：每次都会重新走设备码授权，不会用已有 refresh_token 静默完成登录。
想换账号或角色怎么办？重新执行 ve configure sso --profile [配置名] --sso-session [会话名]，在交互列表中重新选择 account 和 role。
没有图形界面的机器怎么登录？在 ve configure sso 或 ve sso login 后加 --no-browser，按命令行输出的授权地址在浏览器中完成授权。
Scopes 应该怎么填？通常可以省略，默认使用 cloudidentity:account:access,offline_access。如果手动填写，只允许 cloudidentity:account:access 和 offline_access，CLI 会自动去重并校验。

# 使用默认 profile 登录，未指定 region 时会提示输入
ve login

# 推荐：指定 profile 和地域，profile/region 支持 -p/-r 简写
ve login -p dev -r cn-beijing

# 无浏览器、远程服务器或容器环境使用跨设备登录
ve login -p dev -r cn-beijing --remote

该命令通过火山引擎控制台完成 OAuth 2.0 + PKCE 登录，并将临时 STS 凭证缓存到本地，后续业务命令可复用该 profile 的临时凭证。

参数说明：

--profile, -p：配置名称，默认 default
--region, -r：地域；未指定时会提示输入，直接回车使用 cn-beijing
--remote：跨设备登录；按终端输出的 URL 在浏览器完成登录，并将浏览器展示的授权码完整粘贴回终端
--endpoint-url：登录服务地址，默认 https://signin.volcengine.com，通常无需修改

注意事项：

登录成功后，profile 会被写为 console-login 模式，并记录 login-session
使用非 default profile 登录后，业务命令不会自动切换 profile；需要先执行 ve configure profile --profile dev
本机浏览器无法回跳 CLI 所在机器时，使用 --remote

完整使用流程示例：

# 1. 登录并写入 dev profile
ve login --profile dev --region cn-beijing

# 2. 如果 dev 不是当前默认 profile，先切换当前使用的配置
ve configure profile --profile dev

# 3. 执行业务命令时会使用当前 profile 中的 console-login 临时凭证
ve ecs DescribeInstances

# 4. 使用结束后清理本地登录状态
ve logout --profile dev

Console 登出 (logout)

# 登出 default profile
ve logout

# 登出指定 profile
ve logout -p dev

# 登出当前配置中的所有 Console Login profile
ve logout --all

该命令用于清理 ve login 建立的本地登录状态。它只删除本地缓存凭证并清除 profile 中的 login-session，不会删除 profile，也不会向服务端发起请求。

参数说明：

--profile, -p：配置名称，默认 default
--all：清理当前配置中的所有 console-login profile；开启后忽略 --profile

注意事项：

ve logout 不带 --profile 时只处理 default profile，不会自动按 current 登出
只有 console-login profile 可使用该命令；AK/SSO profile 不适用
登出后若需继续使用，重新执行 ve login

配置自动补全

使用 ve completion –help 可以查看各种终端下配置自动补全的方式，用户可以根据提示信息自己选择是否配置自动补全功能

Bash

火山引擎CLI 的 Bash 补全脚本可以通过 ve completion bash 进行查看，在 shell 中导入该自动补全脚本，即可开启自动补全功能

1. 安装 bash-completion

火山引擎CLI 补全脚本依赖于工具 bash-completiom，所以你必须先安装并启用它（可以用命令 type _init_completion 检查 bash-completion 是否已安装）

安装：yum install bash-completion 或 apt-get install bash-completion
启用 bash-completion：source /usr/share/bash-completion/bash_completion

建议将 source /usr/share/bash-completion/bash_completion 添加至 ~/.bashrc 中
检查 bash-completion 是否安装成功：执行 type _init_completion 验证 bash-completion 的安装状态

2. 配置自动补全

按以下步骤配置即可在 Bash 下开启自动补全功能：

echo ‘source <(ve completion bash)’ >> ~/.bashrc
ve completion bash > /etc/bash_completion.d/ve

之后重新加载 Shell （或者 source ~/.bashrc）后即可生效

若出现 _get_comp_words_by_ref: command not found 的错误，请再次检查 bash-completion 是否安装配置成功

Zsh

火山引擎CLI 的 Zsh 补全脚本可以通过 ve completion zsh 进行查看，在 shell 中导入该自动补全脚本，即可开启自动补全功能

按以下步骤配置即可在 Zsh 下开启自动补全功能：

Zsh 中启用 compinit： echo “autoload -U compinit; compinit” >> ~/.zshrc
配置自动补全 ve completion zsh > “${fpath[1]}/_ve”

之后重新加载 Shell （或者 source ~/.zshrc）后即可生效

配置颜色

使用 ve enable-color 可以开启彩色显示功能

使用 ve disable-color 可以关闭彩色显示功能

使用火山引擎CLI

查询支持的服务列表及服务下支持的接口列表

查询支持的服务列表
```
ve [-h|--help]
```
查询服务下支持的接口列表
```
ve ecs [-h|--help]
```

查看版本

ve version

ve -v

调用API

使用火山引擎CLI 调用 API 时，基本命令结构如下：

ve <service name> <action> [--parameter1 value1 --parameter2 value2 ...]

您可以使用 ve <service name> <action> –help 查看想要调用的API的参数列表、返回结果等信息，例如：ve ecs DescribeInstances –help

若需要查看更详细的信息，您也可以在 https://www.volcengine.com/docs 进行查阅

以下提供一些代码示例：

基本使用

ve ecs DescribeInstances

ve rds_mysql ListDBInstanceIPLists --InstanceId "xxxxxx"

支持传入 JSON

ve rds_mysql ModifyDBInstanceIPList --InstanceId "xxxxxx" --GroupName "xxxxxx" --IPList '["10.20.30.40", "50.60.70.80"]'

对于 ContentType 为 application/json 的请求，火山引擎CLI 还支持直接将 body 作为 JSON 数据传入

ve rds_mysql ModifyDBInstanceIPList --body '{"InstanceId":"xxxxxx", "GroupName": "xxxxxx", "IPList": ["10.20.30.40", "50.60.70.80"]}'

Security and privacy

This project takes security seriously. For vulnerability reporting and supported versions, see SECURITY.md

Volcengine Command Line Tools

特别说明

概述

安装 火山引擎CLI

通过release获取客户端

自行编译获取客户端

配置 火山引擎CLI

配置凭证

configure命令的其他操作

获取指定配置(profile)信息

显示当前所有配置(profile)信息

切换当前使用的配置(profile)信息 请确保版本大于或者等于>=1.0.16

新建/修改配置(profile)

删除配置(profile)

SSO 快速上手

SSO 命令关系

配置 SSO 会话 (configure sso-session)

配置 SSO 类型 profile (configure sso)

日常登录、自动刷新与登出

业务命令的自动刷新

SSO 登录 (sso login)

SSO 登出 (sso logout)

SSO 常见问题

Console 登录 (login)

Console 登出 (logout)

配置自动补全

Bash

1. 安装 bash-completion

2. 配置自动补全

Zsh

配置颜色

使用 火山引擎CLI

查询支持的服务列表及服务下支持的接口列表

查看版本

调用API

Security and privacy

安装火山引擎CLI

配置火山引擎CLI

切换当前使用的配置(profile)信息请确保版本大于或者等于>=1.0.16

使用火山引擎CLI