CLI：workflow
CLI：workflow
Section titled “CLI：workflow”先读 CLI 总览：会话/目录、退出约定、角色边界、合成占位 ID 和执行授权规则在其中统一定义。本页逐叶补充例外；以下命令不是按顺序执行的脚本。
- viat workflow create
- viat workflow delete
- viat workflow list
- viat workflow show
- viat workflow test
- viat workflow update
合成夹具与执行边界
Section titled “合成夹具与执行边界”这些文件只为下面例子提供输入；创建远程对象、执行脚本、数据库 SQL 或存储操作前，必须自行准备隔离项目并明确授权。生成文档不执行任何例子。
inputs: {}steps: - id: echo script: demo_echooutputs: result: "$echo.output"demo_echo 使用脚本页无资源的 Python 夹具。先创建脚本，再 workflow create，然后才可 test；编辑/测试的是草稿，不是已发布快照。
viat workflow create
Section titled “viat workflow create”前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 按本页合成夹具写 demo-workflow.yaml，并先创建 demo_echo。该脚本不使用提供方。
Usage: viat workflow create --file <FILE> <NAME>命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
file: --file | PathBuf, 1, Set | 是; Clap 无显式默认 | — | — |
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
name: <NAME> (#1) | String, 1, Set | 是; Clap 无显式默认 | — | — |
Clap 参数组（literal metadata）：{"arguments":["file","name"],"id":"Create","multiple":true,"required":false}
输入、行为与副作用。 读取原始 YAML —file，POST name/folder/definition。名称可含文件夹。只建草稿，不执行/发布。
实际输出与退出。 stdout: created <name> (vN)。服务端校验定义及引用结构。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat workflow create demo_flow --file demo-workflow.yaml失败处理、验证与清理。 无效 YAML/定义或重名会失败。workflow show 验证；无引用时删除 demo_flow。
viat workflow delete
Section titled “viat workflow delete”前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。
Usage: viat workflow delete <NAME>命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
name: <NAME> (#1) | String, 1, Set | 是; Clap 无显式默认 | — | — |
Clap 参数组（literal metadata）：{"arguments":["name"],"id":"Delete","multiple":true,"required":false}
输入、行为与副作用。 删除保存的工作流草稿，不撤销执行及资源副作用。
实际输出与退出。 stdout: deleted <name>；DELETE 成功 0。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat workflow delete demo_flow失败处理、验证与清理。 先有意移除依赖调度/端点并保留 YAML。list 确认不存在；重建需保存定义，不能靠旧日志。
viat workflow list
Section titled “viat workflow list”前提与权限。 平台登录、已选择项目，并且是该项目成员（包括 Operator）。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。
Usage: viat workflow list [OPTIONS]命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
json: --json | bool, 0, SetTrue | 否；条件必填见行为; false | — | — |
Clap 参数组（literal metadata）：{"arguments":["json"],"id":"List","multiple":true,"required":false}
输入、行为与副作用。 列各文件夹当前工作流草稿。
实际输出与退出。 文本为限定名和 vN；—json 输出服务端列表；空列表成功。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat workflow list --json失败处理、验证与清理。 使用列表限定引用。不执行、不修改，无需清理。
viat workflow show
Section titled “viat workflow show”前提与权限。 平台登录、已选择项目，并且是该项目成员（包括 Operator）。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。
Usage: viat workflow show [OPTIONS] <NAME>命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
json: --json | bool, 0, SetTrue | 否；条件必填见行为; false | — | — |
name: <NAME> (#1) | String, 1, Set | 是; Clap 无显式默认 | — | — |
Clap 参数组（literal metadata）：{"arguments":["json","name"],"id":"Show","multiple":true,"required":false}
输入、行为与副作用。 读单个草稿，不是已发布端点快照。
实际输出与退出。 文本打印 # name (vN) 及 YAML 定义；—json 返回公开工作流对象。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat workflow show demo_flow --json失败处理、验证与清理。 名称不存在/歧义会失败；限定文件夹。若需回退，update/delete 前保存此定义；只读本身无需清理。
viat workflow test
Section titled “viat workflow test”前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。
Usage: viat workflow test [OPTIONS] <NAME>命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
input: --input / --args | String, 1, Set | 否；条件必填见行为; {} | — | 原始帮助：JSON object of inputs. --args is accepted too — the script commands spell it that way, and the two were confused constantly |
name: <NAME> (#1) | String, 1, Set | 是; Clap 无显式默认 | — | — |
Clap 参数组（literal metadata）：{"arguments":["input","name"],"id":"Test","multiple":true,"required":false}
输入、行为与副作用。 以 —input JSON（默认 {}，别名 —args）向 /test_run 执行在线未发布定义。访问真实资源并可修改。
实际输出与退出。 逐尝试步骤状态写 stderr。仅 user_error 为 null 且 step_runs 没有任何 failed 行时 stdout 打印 outputs 并退出 0。任一失败尝试行都退出 1，即使后来重试成功或运行时恢复整体结果。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat workflow test demo_flow --input '{}'失败处理、验证与清理。 失败时 stderr 打印 request_id、user_error 和失败步骤错误，不打印成功 outputs。用该 ID 查日志再决定重跑，重复执行可重复写入。不自动回滚资源。
viat workflow update
Section titled “viat workflow update”前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。
Usage: viat workflow update --file <FILE> <NAME>命令别名： 无。
| 参数 ID / 完整拼写 | 类型、消费值数量、action | 必填 / 默认 | 允许值 | 冲突、别名、解析与原始 Clap 帮助 |
|---|---|---|---|---|
file: --file | PathBuf, 1, Set | 是; Clap 无显式默认 | — | — |
help: --help / -h | String, 0, Help | 否；条件必填见行为; Clap 无显式默认 | — | 原始帮助：Print help |
name: <NAME> (#1) | String, 1, Set | 是; Clap 无显式默认 | — | — |
Clap 参数组（literal metadata）：{"arguments":["file","name"],"id":"Update","multiple":true,"required":false}
输入、行为与副作用。 从 —file PATCH 完整定义，产生新草稿版本。发布前端点保持旧快照。
实际输出与退出。 stdout: updated <name> → vN，附可能的待发布提示。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。
合成调用示例（只校验语法，不执行）。
viat workflow update demo_flow --file demo-workflow.yaml失败处理、验证与清理。 定义校验失败退出 1。保留旧 YAML、show 核查；仅明确允许真实副作用后 test；恢复旧定义回退草稿。
实现核对依据
Section titled “实现核对依据”语法来自固定 Clap 合同与 main.rs；行为/权限核对以下源文件，路径相对产品仓库根。
crates/viat-cli/src/commands/workflow.rs:150–216crates/viat-api/src/handlers/workflows.rs