velocli-cloud

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

VeloCLI Cloud Operations

VeloCLI 云运维操作

Operational workflows for VeloDB Cloud using

velocli

使用

velocli

的VeloDB Cloud运维工作流。

Safety Policy

安全策略

Read-only Cloud discovery (warehouse ls, cluster ls, ctx, auth status, billing, audit) may run proactively
Mutating operations (pause, resume, resize, create, delete, reboot, upgrade, password set, public-access changes, PrivateLink register/unregister) require explicit user confirmation before execution
Before asking for confirmation, show the target resource, current state if known, requested change, and user impact (billing, downtime, connectivity, or credential rotation)
The confirmation must be a clear question such as "Proceed with
```
<command>
```
?" Do not treat the user's initial request as confirmation
Secret values (API keys, passwords) must stay in environment variables or user terminal — never output raw secrets

只读类云资源发现操作（warehouse ls、cluster ls、ctx、auth status、billing、audit）可主动执行
变更类操作（pause、resume、resize、create、delete、reboot、upgrade、password set、public-access changes、PrivateLink register/unregister）执行前需要用户明确确认
请求确认前，需展示目标资源、当前已知状态、请求的变更内容以及对用户的影响（计费、停机、连接性或凭证轮换）
确认必须是清晰的问题，例如「是否执行
```
<command>
```
？」，不得将用户的初始请求视为确认
敏感值（API密钥、密码）必须保留在环境变量或用户终端中——绝对不能输出原始敏感信息

Binary Detection

二进制文件检测

```
VELOCLI_PATH
```
env var → use that binary
```
command -v velocli
```
→ use from PATH
```
command -v sdbcli
```
→ only for explicit SelectDB environments
If unavailable: do not stop at installation advice. Say commands cannot be executed in this environment, then still provide the full operational workflow, exact commands, confirmation gates, expected verification command, and install note. The user may have
```
velocli
```
elsewhere or may need the workflow as the deliverable.

优先使用
```
VELOCLI_PATH
```
环境变量指定的二进制文件
通过
```
command -v velocli
```
从系统PATH中查找并使用
通过
```
command -v sdbcli
```
查找——仅用于明确的SelectDB环境
若无法找到：不要仅提供安装建议就停止。说明当前环境无法执行命令，同时仍需提供完整的运维工作流、准确命令、确认环节、预期的验证命令以及安装提示。用户可能在其他位置拥有
```
velocli
```
，或者需要将工作流作为交付物。

Canonical Command Names

标准命令名称

Use only these command forms. Do not invent aliases.

Correct	Never use
`velocli auth add`	`velocli auth login` , `velocli login`
`velocli auth list`	`velocli auth ls`
`velocli auth status`	`velocli status`
`velocli cloud warehouse ls`	`velocli warehouse list` , `velocli warehouse ls`
`velocli cloud cluster ls`	`velocli cluster list`
`velocli cloud cluster get`	`velocli cluster info`
`velocli cloud use`	`velocli context set`
`velocli cloud ctx`	`velocli context`
`velocli cloud public-access get`	`velocli network status`
`velocli cloud audit ls`	`velocli audit list`
API host: `sandbox.velodb.io`	`api.sandbox.velodb.cloud` , `sandbox-api.velodb.io`
API host: `api.velodb.cloud`	`velodb.cloud/api`
API host: `api.selectdb.com`	`api.selectdb.cn`

仅使用以下命令形式，不得自行创建别名。

正确命令	禁止使用
`velocli auth add`	`velocli auth login` , `velocli login`
`velocli auth list`	`velocli auth ls`
`velocli auth status`	`velocli status`
`velocli cloud warehouse ls`	`velocli warehouse list` , `velocli warehouse ls`
`velocli cloud cluster ls`	`velocli cluster list`
`velocli cloud cluster get`	`velocli cluster info`
`velocli cloud use`	`velocli context set`
`velocli cloud ctx`	`velocli context`
`velocli cloud public-access get`	`velocli network status`
`velocli cloud audit ls`	`velocli audit list`
API主机: `sandbox.velodb.io`	`api.sandbox.velodb.cloud` , `sandbox-api.velodb.io`
API主机: `api.velodb.cloud`	`velodb.cloud/api`
API主机: `api.selectdb.com`	`api.selectdb.cn`

Canonical Environment Variables

标准环境变量

Use these exact names. Do not invent alternatives.

Correct	Never use
`VELO_CLOUD_TOKEN`	`VELO_API_KEY` , `VELO_CLOUD_API_KEY` (env var name)
`VELO_CLOUD_API_HOST`	`VELO_API_HOST`
`VELO_CURRENT_WAREHOUSE`	`VELO_WAREHOUSE`
`VELO_CURRENT_CLUSTER`	`VELO_CLUSTER`
`VELO_HOST`	`VELOCLI_HOST`
`VELO_USER`	`VELOCLI_USER`
`VELO_PASSWORD`	`VELOCLI_PASSWORD`
Config dir: `~/.velodb/`	`~/.velocli/` , `~/.velo/`

Note:

$VELO_CLOUD_API_KEY

is fine as a user-chosen shell variable name when storing the key for

--api-key

. The table above is about the stateless-mode env vars that velocli reads internally.

仅使用以下准确名称，不得自行创建替代名称。

正确名称	禁止使用
`VELO_CLOUD_TOKEN`	`VELO_API_KEY` , `VELO_CLOUD_API_KEY` （velocli内部读取的无状态模式环境变量名）
`VELO_CLOUD_API_HOST`	`VELO_API_HOST`
`VELO_CURRENT_WAREHOUSE`	`VELO_WAREHOUSE`
`VELO_CURRENT_CLUSTER`	`VELO_CLUSTER`
`VELO_HOST`	`VELOCLI_HOST`
`VELO_USER`	`VELOCLI_USER`
`VELO_PASSWORD`	`VELOCLI_PASSWORD`
配置目录: `~/.velodb/`	`~/.velocli/` , `~/.velo/`

注意：

$VELO_CLOUD_API_KEY

作为用户自定义的Shell变量名存储

--api-key

对应的密钥是允许的。上表仅针对velocli内部读取的无状态模式环境变量名。

Mutation Response Template

变更操作响应模板

Every mutating Cloud operation must follow this pattern:

Read current state: run discovery command (e.g.,
```
cluster get
```
,
```
public-access get
```
,
```
cluster ls
```
)
Show impact: target resource name/id, current state, requested change, user impact (billing, downtime, connectivity, credential rotation)
Ask confirmation: "Proceed with
```
<exact command>
```
?" — a clear yes/no question. Do not treat the user's initial request as confirmation
Execute after confirmation: run the command
Verify: run a read-only command to confirm the result (e.g.,
```
cluster get
```
,
```
sql "SELECT 1"
```
,
```
public-access get
```
)

所有云资源变更操作必须遵循以下流程：

读取当前状态：执行资源发现命令（例如
```
cluster get
```
、
```
public-access get
```
、
```
cluster ls
```
）
展示影响：目标资源名称/ID、当前状态、请求的变更内容、对用户的影响（计费、停机、连接性、凭证轮换）
请求确认：「是否执行
```
<exact command>
```
？」——明确的是/否问题。不得将用户的初始请求视为确认
确认后执行：运行命令
验证结果：执行只读命令确认操作结果（例如
```
cluster get
```
、
```
sql "SELECT 1"
```
、
```
public-access get
```
）

Core Workflows

核心工作流

Onboarding (New Cloud Environment)

新云环境入门

Read

references/onboarding.md

for the complete flow:

Select API host (sandbox / international / China)

velocli auth add <name> --api-key $KEY --api-host <host> --mysql-password $PW

```
velocli auth status --format json
```
— verify API connectivity
Resolve warehouse/cluster context (may auto-pick or require
```
cloud use
```
)
```
velocli sql "SELECT 1" --format json
```
— verify data-plane connectivity

完整流程请查阅

references/onboarding.md

：

选择API主机（sandbox / 国际版 / 中国版）

velocli auth add <name> --api-key $KEY --api-host <host> --mysql-password $PW

```
velocli auth status --format json
```
—— 验证API连通性
解析数据仓库/集群上下文（可能自动选择或需要执行
```
cloud use
```
）
```
velocli sql "SELECT 1" --format json
```
—— 验证数据平面连通性

Context Management

上下文管理

Read

references/context.md

for warehouse→cluster hierarchy and resolution rules.

Always show current context before changing:
```
velocli cloud ctx --format json
```
Use explicit
```
--env
```
,
```
--warehouse
```
,
```
--cluster
```
when ambiguity exists
Switching warehouse clears cluster (old cluster may not belong to new warehouse)

数据仓库→集群的层级关系和解析规则请查阅

references/context.md

。

修改上下文前务必先展示当前上下文：
```
velocli cloud ctx --format json
```
存在歧义时，使用明确的
```
--env
```
、
```
--warehouse
```
、
```
--cluster
```
参数
切换数据仓库会清除集群上下文（旧集群可能不属于新数据仓库）

Cluster Lifecycle

集群生命周期

Read

references/cluster-lifecycle.md

for pause/resume/resize/create/delete flows.

Use
```
--wait
```
for user-facing workflows where completion feedback matters
All writes are idempotent (auto-generated RequestId)
Read-only:
```
cluster get
```
,
```
cluster ls
```
Mutating (confirm first):
```
pause
```
,
```
resume
```
,
```
reboot
```
,
```
resize
```
,
```
create
```
,
```
delete
```
If the binary is unavailable, still show: discovery command → confirmation question → mutation command → verification command. Do not bail out after "install velocli"

暂停/恢复/扩容/创建/删除流程请查阅

references/cluster-lifecycle.md

。

在面向用户的工作流中，若需要反馈完成状态，使用
```
--wait
```
参数
所有写入操作均具有幂等性（自动生成RequestId）
只读操作：
```
cluster get
```
、
```
cluster ls
```
变更操作（需先确认）：
```
pause
```
、
```
resume
```
、
```
reboot
```
、
```
resize
```
、
```
create
```
、
```
delete
```
若无法找到二进制文件，仍需展示：资源发现命令 → 确认问题 → 变更命令 → 验证命令。不得仅提示「安装velocli」就终止流程

Networking

网络配置

Read

references/networking.md

for public access and PrivateLink.

Read current state first:
```
velocli cloud public-access get
```
Confirm before any policy change

公网访问和PrivateLink相关内容请查阅

references/networking.md

。

先读取当前状态：
```
velocli cloud public-access get
```
任何策略变更前需确认

Billing & Audit

计费与审计

Read

references/billing-and-audit.md

for cost queries and operational history.

Billing summary for cost questions (supports hour/day/month granularity)
Audit ls for incident timelines, "who changed it" questions, and infrastructure change tracking

成本查询和操作历史相关内容请查阅

references/billing-and-audit.md

。

针对成本问题提供计费汇总（支持小时/天/月粒度）
使用audit ls查询事件时间线、「谁修改了配置」类问题以及基础设施变更追踪

Troubleshooting

故障排查

Read

references/troubleshooting.md

for common Cloud connection and configuration issues.

For permission errors, distinguish read-only success from mutation failure and tell the user which operation likely needs elevated scope
For API business-rule failures, do not retry the mutation blindly. Surface the API
```
code
```
,
```
message
```
, and
```
request_id
```
, then inspect current state with read-only commands

常见云连接和配置问题请查阅

references/troubleshooting.md

。

针对权限错误，区分只读操作成功与变更操作失败的情况，并告知用户哪些操作可能需要更高权限
针对API业务规则失败，不得盲目重试变更操作。需展示API的
```
code
```
、
```
message
```
和
```
request_id
```
，然后通过只读命令检查当前状态

Environment Switching

环境切换

Multiple ways to select environment (highest → lowest precedence):

```
--env <name>
```
flag (per-command)
```
VELO_ENV
```
environment variable (per-session)
```
velocli use <name>
```
(persistent)
fallback:
```
default
```

选择环境的多种方式（优先级从高到低）：

命令级别的
```
--env <name>
```
参数
会话级别的
```
VELO_ENV
```
环境变量
持久化的
```
velocli use <name>
```
命令
fallback：
```
default
```
环境