VeloCLI Cloud Operations
Operational workflows for VeloDB Cloud using velocli.
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
Binary Detection
VELOCLI_PATH env var → use that binarycommand -v velocli → use from PATHcommand -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.
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 |
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.
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)
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 $PWvelocli 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
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)
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"
Networking
Read references/networking.md for public access and PrivateLink.
- Read current state first:
velocli cloud public-access get
- Confirm before any policy change
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
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
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
1---2name: velocli-cloud3description: VeloDB Cloud operational workflows using velocli CLI. Use for VeloDB Cloud setup, velocli auth, API host selection, warehouse/cluster context management, cluster pause/resume/reboot/create/delete/resize, billing queries, audit log inspection, public access policy, PrivateLink configuration, BYOC/SOCKS5 connectivity, password rotation, warehouse upgrade, and Cloud operations troubleshooting. Also triggers on: "connect to VeloDB Cloud", "set up velocli", "pause cluster", "resume cluster", "check billing", "resize to N vCPU", "configure public access", "set up PrivateLink", "rotate password", "upgrade warehouse", environment switching, stateless mode for CI, audit/infrastructure change investigation, "who changed cluster/network/warehouse settings", and any VeloDB Cloud infrastructure management. Does NOT handle query optimization or table design — those belong to velodb-best-practices.4---56# VeloCLI Cloud Operations78Operational workflows for VeloDB Cloud using `velocli`.910---1112## Safety Policy1314- Read-only Cloud discovery (warehouse ls, cluster ls, ctx, auth status, billing, audit) may run proactively15- Mutating operations (pause, resume, resize, create, delete, reboot, upgrade, password set, public-access changes, PrivateLink register/unregister) require explicit user confirmation before execution16- Before asking for confirmation, show the target resource, current state if known, requested change, and user impact (billing, downtime, connectivity, or credential rotation)17- The confirmation must be a clear question such as "Proceed with `<command>`?" Do not treat the user's initial request as confirmation18- Secret values (API keys, passwords) must stay in environment variables or user terminal — never output raw secrets1920---2122## Binary Detection23241. `VELOCLI_PATH` env var → use that binary252. `command -v velocli` → use from PATH263. `command -v sdbcli` → only for explicit SelectDB environments274. 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.2829---3031## Canonical Command Names3233Use only these command forms. Do not invent aliases.3435| Correct | Never use |36|---------|-----------|37| `velocli auth add` | `velocli auth login`, `velocli login` |38| `velocli auth list` | `velocli auth ls` |39| `velocli auth status` | `velocli status` |40| `velocli cloud warehouse ls` | `velocli warehouse list`, `velocli warehouse ls` |41| `velocli cloud cluster ls` | `velocli cluster list` |42| `velocli cloud cluster get` | `velocli cluster info` |43| `velocli cloud use` | `velocli context set` |44| `velocli cloud ctx` | `velocli context` |45| `velocli cloud public-access get` | `velocli network status` |46| `velocli cloud audit ls` | `velocli audit list` |47| API host: `sandbox.velodb.io` | `api.sandbox.velodb.cloud`, `sandbox-api.velodb.io` |48| API host: `api.velodb.cloud` | `velodb.cloud/api` |49| API host: `api.selectdb.com` | `api.selectdb.cn` |5051## Canonical Environment Variables5253Use these exact names. Do not invent alternatives.5455| Correct | Never use |56|---------|-----------|57| `VELO_CLOUD_TOKEN` | `VELO_API_KEY`, `VELO_CLOUD_API_KEY` (env var name) |58| `VELO_CLOUD_API_HOST` | `VELO_API_HOST` |59| `VELO_CURRENT_WAREHOUSE` | `VELO_WAREHOUSE` |60| `VELO_CURRENT_CLUSTER` | `VELO_CLUSTER` |61| `VELO_HOST` | `VELOCLI_HOST` |62| `VELO_USER` | `VELOCLI_USER` |63| `VELO_PASSWORD` | `VELOCLI_PASSWORD` |64| Config dir: `~/.velodb/` | `~/.velocli/`, `~/.velo/` |6566Note: `$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.6768---6970## Mutation Response Template7172Every mutating Cloud operation must follow this pattern:73741. **Read current state**: run discovery command (e.g., `cluster get`, `public-access get`, `cluster ls`)752. **Show impact**: target resource name/id, current state, requested change, user impact (billing, downtime, connectivity, credential rotation)763. **Ask confirmation**: "Proceed with `<exact command>`?" — a clear yes/no question. Do not treat the user's initial request as confirmation774. **Execute after confirmation**: run the command785. **Verify**: run a read-only command to confirm the result (e.g., `cluster get`, `sql "SELECT 1"`, `public-access get`)7980---8182## Core Workflows8384### Onboarding (New Cloud Environment)8586Read `references/onboarding.md` for the complete flow:871. Select API host (sandbox / international / China)882. `velocli auth add <name> --api-key $KEY --api-host <host> --mysql-password $PW`893. `velocli auth status --format json` — verify API connectivity904. Resolve warehouse/cluster context (may auto-pick or require `cloud use`)915. `velocli sql "SELECT 1" --format json` — verify data-plane connectivity9293### Context Management9495Read `references/context.md` for warehouse→cluster hierarchy and resolution rules.9697- Always show current context before changing: `velocli cloud ctx --format json`98- Use explicit `--env`, `--warehouse`, `--cluster` when ambiguity exists99- Switching warehouse clears cluster (old cluster may not belong to new warehouse)100101### Cluster Lifecycle102103Read `references/cluster-lifecycle.md` for pause/resume/resize/create/delete flows.104105- Use `--wait` for user-facing workflows where completion feedback matters106- All writes are idempotent (auto-generated RequestId)107- Read-only: `cluster get`, `cluster ls`108- Mutating (confirm first): `pause`, `resume`, `reboot`, `resize`, `create`, `delete`109- If the binary is unavailable, still show: discovery command → confirmation question → mutation command → verification command. Do not bail out after "install velocli"110111### Networking112113Read `references/networking.md` for public access and PrivateLink.114115- Read current state first: `velocli cloud public-access get`116- Confirm before any policy change117118### Billing & Audit119120Read `references/billing-and-audit.md` for cost queries and operational history.121122- Billing summary for cost questions (supports hour/day/month granularity)123- Audit ls for incident timelines, "who changed it" questions, and infrastructure change tracking124125### Troubleshooting126127Read `references/troubleshooting.md` for common Cloud connection and configuration issues.128129- For permission errors, distinguish read-only success from mutation failure and tell the user which operation likely needs elevated scope130- 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 commands131132---133134## Environment Switching135136Multiple ways to select environment (highest → lowest precedence):1371. `--env <name>` flag (per-command)1382. `VELO_ENV` environment variable (per-session)1393. `velocli use <name>` (persistent)1404. fallback: `default`
velodb