kibo CLI 参考
本页列出 kibo 的全局参数、退出码、JSON 输出格式，以及读写本地文件的规则。命令的用法按读者分在三处：
- Workspace 与 Volume 操作见kibo 命令行及其列出的主题页。
- 注册与连接配置见 身份与注册。
- node、存储池、Platform 与 Template 管理见 Operator 的node、存储池与 目录。
kibo node list各列的含义见list 与 get。
每个命令的用法与参数见 kibo 命令，由 kibo 的源码生成。
全局参数
这些参数可以放在子命令之前或之后。
| 参数 | 默认值 | 说明 |
|---|---|---|
--endpoint <url> | context 中保存的地址 | 覆盖本次请求的 ctrl 地址。未传时先看环境变量 KIBO_ENDPOINT，再用 context 中的值。身份与信任的证书不变 |
--json | 关闭 | 输出稳定的 JSON，业务结果在 result 字段 |
--timeout <duration> | 30s | 单次请求的超时。文件上传与下载本身不受它限制。node drain --wait 用它限制整个等待过程 |
命令自带的通用参数
下面几个参数只挂在用得到的命令上，必须写在子命令之后，例如 kibo workspace delete ws-01k6… --yes。每条命令接受哪些参数，见 kibo 命令中该命令的页面。
| 参数 | 说明 |
|---|---|
--command-id <key> | 发送变更的命令的幂等键，未传时自动生成。同一个键加同样的输入重放不会重复执行；输入不同时以冲突拒绝。kibo template publish 可以从构建结果推导出它。规则见 kibo help command-ids |
-y, --yes | 在需要确认的命令（例如删除）上跳过确认。非交互终端下必须提供 |
-q, --quiet | 只输出结果里的资源 ID，一行一个，例如 ws=$(kibo workspace create --template t -q) |
--wide | 加上默认省略的字段：各类 revision、generation、完整 digest、labels、注册版本与能力名清单 |
-L, --label-column <key> | 可重复；把这个 label 显示成一列，列名是 key 最后一个 / 之后的部分 |
--all | 逐页读完全部结果；不带时只取一页，-q 会在 stderr 提示还有下一页 |
--quiet、--wide 与 --json 两两互斥。
需要等待服务端完成的命令有 --wait-timeout，默认值是 1h 或 2h，列在各命令的页面上。workspace create/start/stop/delete 与 template prepare 另有 --no-wait，受理即返回。
等待超时或按 Ctrl-C 都不会撤回已提交的操作。结果未知时用同一个幂等键重放，或用 kibo workspace command get 查询，不要换一个幂等键重新提交。
幂等键与期望版本
修改已有对象的命令遵循同一套规则：
- 每条写命令带一个幂等键（
--command-id）和一个期望版本。同样的幂等键配同样的输入再执行一次，只返回当前状态，不会重复生效；同样的幂等键配不同的输入返回already_exists，退出码13。 - 期望版本用于乐观锁。不传时
kibo先读取当前版本再提交；提交时版本已变化，服务端返回aborted（过期策略的版本返回failed_precondition），kibo以退出码13结束且不自动重试。请重新读取状态后再决定。 - 显式传
--command-id时必须同时传对应的期望版本参数。手工操作时两者都不传即可，kibo会生成随机的幂等键并读取当前版本。 - 目标对象不存在时退出码为
12。
大小与 CPU 的写法
- 容量与内存写成数字加单位，单位一律按二进制：
K、M、G、T、P与Ki、KiB等写法等价，1G是1 << 30字节，没有单位是字节。 KB、MB、GB这类十进制写法会在发送请求前被拒绝，并提示改成G或GiB。- CPU 写成核数或毫核：
2、0.5、1500m。
补全与 ID 前缀
kibo completion bash|zsh|fish|powershell输出补全脚本。Workspace、Volume、Template、node、Exposure、Egress 与 Resolver 的 ID 参数，以及--template、--volume、--workspace、--node、--egress、--resolver，补全时向 ctrl 读取第一页资源。- Workspace 与 Volume 的 ID 参数接受唯一前缀，例如
kibo workspace get ws-01k6。没有匹配时退出12，多个匹配时退出2并列出候选。
JSON 输出
- 字段名与 API 定义一致，使用 snake_case。枚举保留完整名称，例如人读输出中的
AVAILABLE在 JSON 中是WORKSPACE_STATE_AVAILABLE。 - 除了
result，还要检查completeness与error字段。有输出不代表命令成功。 - 写命令的 envelope 带
command_id，取值就是本次使用的幂等键，可以直接用来重放或查询。只读命令没有幂等键，不输出这个字段。人读输出里同一个值显示为Command ID。 - 等待完成的
workspace create/start/stop/delete输出WorkspaceCommandResult：result.workspace_id是 Workspace ID，result.command_result是命令完成时的 Workspace，result.current_workspace是之后读到的当前状态；stop 另有result.durability。--no-wait输出Workspace，ID 同样在result.workspace_id。
退出码
kibo 的退出码，包括 workspace exec 与 workspace terminal 的，见由 kibo 源码生成的 kibo 退出码。
错误输出
- 人读输出只有
Error:一行，服务端给出阶段与原因时附在括号里；有针对性的下一步写在Hint:一行；写命令另有Command ID:。 - 错误类别、影响与是否可重试只出现在
--json的error字段里。 - 拼错子命令或参数时，
Hint:给出最接近的写法。
本地文件输入与输出
注册密钥文件的读取方式见注册密钥的规则。
读取 Egress 口令
适用于 kibo egress create/update 的 --password-file 与 --password-stdin：
- 末尾的一个换行（
\n或\r\n）被去掉，其余字符原样作为口令，可以含空格。口令 1 到 255 字节。 - 只给
--username时在终端上不回显地询问；没有终端时必须用这两个参数之一。命令行上没有直接写口令的参数，--password在任何命令上都被拒绝。 - 口令不出现在任何输出、错误信息与 JSON 结果中。
写入下载的文件
适用于 kibo workspace file get：
- 新文件权限为
0600。覆盖已有的普通文件时保留原权限。用--mode 0640等指定权限，范围0000到0777。 - 先写到临时文件，完整接收后再替换目标。传输失败时目标文件不变。
- 目标不能是符号链接或特殊文件。输出到
-（标准输出）时不能使用--mode。