跳转到内容
Viat

CLI：script

CLI：script

Section titled “CLI：script”

先读 CLI 总览：会话/目录、退出约定、角色边界、合成占位 ID 和执行授权规则在其中统一定义。本页逐叶补充例外；以下命令不是按顺序执行的脚本。

合成夹具与执行边界

Section titled “合成夹具与执行边界”

这些文件只为下面例子提供输入；创建远程对象、执行脚本、数据库 SQL 或存储操作前，必须自行准备隔离项目并明确授权。生成文档不执行任何例子。

# demo.py (also scripts/demo_echo.py in a repo checkout)
def main():
    return {"ok": True}

先用 script create 创建 demo_echo，再运行 show/update/run 等例子。Rust/binary 示例还须你自己的匹配 SDK/可执行程序，并非此 Python 夹具；不能用文本文件冒充二进制。离线测试须另外编写真正断言的 tests/ 夹具，空套件不等于成功覆盖。

viat script build

Section titled “viat script build”

前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。

Usage: viat script build [OPTIONS] <NAME>

命令别名： 无。

参数 ID / 完整拼写类型、消费值数量、action必填 / 默认允许值冲突、别名、解析与原始 Clap 帮助
help: --help / -hString, 0, Help否；条件必填见行为; Clap 无显式默认—原始帮助：Print help
name: <NAME> (#1)String, 1, Set是; Clap 无显式默认——
wait: --waitbool, 0, SetTrue否；条件必填见行为; false—原始帮助：Poll until the install finishes instead of returning immediately

Clap 参数组（literal metadata）：{"arguments":["name","wait"],"id":"Build","multiple":true,"required":false}

输入、行为与副作用。 构建已保存草稿，不发布。Python/TypeScript 预热依赖、复用单次安装；—wait 轮询。Rust 立即编译，—wait 无意义。Binary 报告 manifest 目标与本实例 artifact，而非编译。

实际输出与退出。 文本报告环境/构建；不带 —wait 时退出 0 仍可在安装。—wait 安装失败/超时退出 1。Rust 失败打印源码诊断和 rustc 输出，退出 1。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。

合成调用示例（只校验语法，不执行）。

终端窗口
viat script build demo_echo --wait

失败处理、验证与清理。 需服务端构建能力/工具链/包访问；可安装下载依赖，须明确允许。修复后 build 重试，逐节点 env 验证。无 CLI 撤销来删除环境/artifact。

viat script compile

Section titled “viat script compile”

前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。

Usage: viat script compile [OPTIONS] [NAME]

命令别名： 无。

参数 ID / 完整拼写类型、消费值数量、action必填 / 默认允许值冲突、别名、解析与原始 Clap 帮助
all: --allbool, 0, SetTrue否；条件必填见行为; false—原始帮助：Every rust script in the project, one after another — before switching traffic to a release that retired the artifacts. Skips those the deployment already has; exits 1 if any failed
folder: --folderString, 1, Set否；条件必填见行为; Clap 无显式默认—冲突 ID：all; 原始帮助：Folder half of the script’s identity, when the bare name is ambiguous
force: --forcebool, 0, SetTrue否；条件必填见行为; false—原始帮助：Build even when the deployment already has this artifact
help: --help / -hString, 0, Help否；条件必填见行为; Clap 无显式默认—原始帮助：Print help (see a summary with ‘-h’)
name: <NAME> (#1)String, 1, Set否；条件必填见行为; Clap 无显式默认—冲突 ID：all
push: --pushbool, 0, SetTrue否；条件必填见行为; false—原始帮助：Upload the binary to the deployment’s artifact store
sdk_path: --sdk-pathString, 1, Set否；条件必填见行为; Clap 无显式默认；运行时：VIAT_RUST_SDK_PATH，否则报错—原始帮助：The viat SDK crate the deployment was built with. Defaults to $VIAT_RUST_SDK_PATH

Clap 参数组（literal metadata）：{"arguments":["all","folder","force","name","push","sdk_path"],"id":"Compile","multiple":true,"required":false}

输入、行为与副作用。 仅本地 Rust 编译，使用服务端提供的精确 crate/artifact key。指定一个 name 或 —all（已发布冻结程序，不是草稿）。—push 才上传；默认不传。—force 绕过已有跳过；—sdk-path 或 VIAT_RUST_SDK_PATH 的 SDK digest 须匹配。

实际输出与退出。 打印编译/artifact/上传进度。—all 逐个继续，报告失败，有任一失败退出 1。已有 artifact 可成功跳过。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。

合成调用示例（只校验语法，不执行）。

终端窗口
viat script compile demo_rust --sdk-path ./viat-sdk

失败处理、验证与清理。 需本地 cargo/rustup、匹配 SDK 与服务端 OS/架构；编译可下载 crate。上传另需服务端启用；artifact key 变化会拒绝。保留源码/诊断；按需清理演示构建输出，勿盲删共享缓存。

viat script create

Section titled “viat script create”

前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 demo.py 写 def main(): return {“ok”: True}（return 放在下一缩进行）。不使用资源；之后执行需服务端 Python/uv。

Usage: viat script create --name <NAME> --language <LANGUAGE> --file <FILE>

命令别名： viat script new

参数 ID / 完整拼写类型、消费值数量、action必填 / 默认允许值冲突、别名、解析与原始 Clap 帮助
file: --fileString, 1, Set是; Clap 无显式默认——
help: --help / -hString, 0, Help否；条件必填见行为; Clap 无显式默认—原始帮助：Print help
language: --languageString, 1, Set是; Clap 无显式默认——
name: --nameString, 1, Set是; Clap 无显式默认——

Clap 参数组（literal metadata）：{"arguments":["file","language","name"],"id":"Create","multiple":true,"required":false}

输入、行为与副作用。 读取 UTF-8 —file 创建草稿。—name 可为 folder/name；—language 在服务端校验。别名 new。不发布、不执行。 允许语言：python、typescript、sql、graphql、shell、llm、viat_gql、rust、binary。

实际输出与退出。 stdout: created <name> (v<version>)。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。

合成调用示例（只校验语法，不执行）。

终端窗口
viat script create --name demo_echo --language python --file demo.py

失败处理、验证与清理。 文件缺失/语言无效/重名会失败。script show 验证；移除依赖夹具/端点后可删演示脚本。

viat script delete

Section titled “viat script delete”

前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。

Usage: viat script delete <NAME>

命令别名： 无。

参数 ID / 完整拼写类型、消费值数量、action必填 / 默认允许值冲突、别名、解析与原始 Clap 帮助
help: --help / -hString, 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 script delete demo_echo

失败处理、验证与清理。 先盘点端点/工作流/调度依赖并保存源码。list 和 publish plan 验证；需要时从保存源码重建。勿以删草稿安全撤下某路由：应使用 endpoint unpublish。

viat script env

Section titled “viat script env”

前提与权限。 平台登录、已选择项目，并且是该项目成员（包括 Operator）。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。

Usage: viat script env [OPTIONS] <NAME>

命令别名： 无。

参数 ID / 完整拼写类型、消费值数量、action必填 / 默认允许值冲突、别名、解析与原始 Clap 帮助
help: --help / -hString, 0, Help否；条件必填见行为; Clap 无显式默认—原始帮助：Print help
json: --jsonbool, 0, SetTrue否；条件必填见行为; false——
name: <NAME> (#1)String, 1, Set是; Clap 无显式默认——
probe: --probebool, 0, SetTrue否；条件必填见行为; false—原始帮助：Ask the package cache instead of reporting what is recorded

Clap 参数组（literal metadata）：{"arguments":["json","name","probe"],"id":"Env","multiple":true,"required":false}

输入、行为与副作用。 GET 回答实例的依赖环境状态；—probe 检查包缓存而非仅已记录状态。不安装、不执行脚本。 普通读取只需成员；—probe 会派生探测进程，额外要求项目 Owner/Admin/Developer。

实际输出与退出。 文本含 key、包、状态（ready/building/failed/未构建）、安装错误与可选 probe；—json 返回原状态。环境 failed 是信息，不必然导致 CLI 非零退出。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。

合成调用示例（只校验语法，不执行）。

终端窗口
viat script env demo_echo --json

失败处理、验证与清理。 多实例须逐节点查；单次响应不代表集群就绪。用 script build 显式重试安装。读取/探测无需撤销。

viat script list

Section titled “viat script list”

前提与权限。 平台登录、已选择项目，并且是该项目成员（包括 Operator）。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。

Usage: viat script list [OPTIONS]

命令别名： 无。

参数 ID / 完整拼写类型、消费值数量、action必填 / 默认允许值冲突、别名、解析与原始 Clap 帮助
help: --help / -hString, 0, Help否；条件必填见行为; Clap 无显式默认—原始帮助：Print help
json: --jsonbool, 0, SetTrue否；条件必填见行为; false——

Clap 参数组（literal metadata）：{"arguments":["json"],"id":"List","multiple":true,"required":false}

输入、行为与副作用。 列所有文件夹当前草稿脚本，不是发布快照。

实际输出与退出。 文本为限定路径、语言、v<version>；—json 输出公开脚本列表。空列表成功。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。

合成调用示例（只校验语法，不执行）。

终端窗口
viat script list --json

失败处理、验证与清理。 使用限定名避免歧义。只读，无需清理。

viat script logs

Section titled “viat script logs”

前提与权限。 平台登录、已选择项目，并且是该项目成员（包括 Operator）。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。

Usage: viat script logs <NAME>

命令别名： 无。

参数 ID / 完整拼写类型、消费值数量、action必填 / 默认允许值冲突、别名、解析与原始 Clap 帮助
help: --help / -hString, 0, Help否；条件必填见行为; Clap 无显式默认—原始帮助：Print help
name: <NAME> (#1)String, 1, Set是; Clap 无显式默认——

Clap 参数组（literal metadata）：{"arguments":["name"],"id":"Logs","multiple":true,"required":false}

输入、行为与副作用。 先解析脚本，再合并一页端点执行与一页草稿测试，按新到旧。工作流步骤执行归属工作流，此处没有。

实际输出与退出。 stdout 为格式化 {items:[…]} 或无执行说明；任一源达到 50 行时 stderr 警告。没有 —json：非空输出已是 JSON。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。

合成调用示例（只校验语法，不执行）。

终端窗口
viat script logs demo_echo

失败处理、验证与清理。 旧执行/工作流步骤用 logs query/show 分页。脚本不存在则失败，不伪装空列表。无远程变更/清理。

viat script run

Section titled “viat script run”

前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。

Usage: viat script run [OPTIONS] <NAME>

命令别名： 无。

参数 ID / 完整拼写类型、消费值数量、action必填 / 默认允许值冲突、别名、解析与原始 Clap 帮助
args: --args / --inputString, 1, Set否；条件必填见行为; Clap 无显式默认；运行时：{}—原始帮助：JSON object of inputs. --input is accepted too — the workflow commands spell it that way, and the two were confused constantly
help: --help / -hString, 0, Help否；条件必填见行为; Clap 无显式默认—原始帮助：Print help
name: <NAME> (#1)String, 1, Set是; Clap 无显式默认——
record: --recordString, 1, Set否；条件必填见行为; Clap 无显式默认—原始帮助：Record this run’s http/graphql/cloud calls as cassettes under this directory (one <resource>.yaml each), for viat script test

Clap 参数组（literal metadata）：{"arguments":["args","name","record"],"id":"Run","multiple":true,"required":false}

输入、行为与副作用。 以 JSON —args（运行时默认 {}）执行在线草稿。别名 —input。可发生真实资源调用/写入，并非离线。—record 成功后写回 http/graphql/cloud cassette。

实际输出与退出。 成功 stdout 格式化 output，捕获 stderr 写 stderr；ok=false 打印错误并退出 1。显式 ViatResponse/流的 output=None：成功 CLI 输出可为 null，不代表 HTTP 失败。Shell stdout 是日志，不是结果。草稿 API 不返回完整 HTTP 响应信封。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。

合成调用示例（只校验语法，不执行）。

终端窗口
viat script run demo_echo --args '{}'

失败处理、验证与清理。 运行前审查外部副作用。用 logs 核查请求；HTTP 状态/头须用发布/隔离端点验证。Cassette 不存请求凭据但可含敏感响应体：审查/删除生成文件；CLI 不能撤销外部写入。

viat script show

Section titled “viat script show”

前提与权限。 平台登录、已选择项目，并且是该项目成员（包括 Operator）。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。

Usage: viat script show [OPTIONS] <NAME>

命令别名： 无。

参数 ID / 完整拼写类型、消费值数量、action必填 / 默认允许值冲突、别名、解析与原始 Clap 帮助
help: --help / -hString, 0, Help否；条件必填见行为; Clap 无显式默认—原始帮助：Print help
json: --jsonbool, 0, SetTrue否；条件必填见行为; false——
name: <NAME> (#1)String, 1, Set是; Clap 无显式默认——

Clap 参数组（literal metadata）：{"arguments":["json","name"],"id":"Show","multiple":true,"required":false}

输入、行为与副作用。 读已保存草稿源码、版本和 dedicated worker 设置。

实际输出与退出。 文本含 # name (language, vN)、content、dedicated 与 dedicated_count；—json 返回完整公开对象。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。

合成调用示例（只校验语法，不执行）。

终端窗口
viat script show demo_echo --json

失败处理、验证与清理。 404/歧义：核对项目并限定文件夹。源码可能意外硬编码秘密；保护输出。无变更/清理。

viat script test

Section titled “viat script test”

前提与权限。 无需已有平台登录或选择项目；仍须本地文件/进程权限及下述命令专属前提。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。

Usage: viat script test [OPTIONS] [TARGETS]...

命令别名： 无。

参数 ID / 完整拼写类型、消费值数量、action必填 / 默认允许值冲突、别名、解析与原始 Clap 帮助
help: --help / -hString, 0, Help否；条件必填见行为; Clap 无显式默认—原始帮助：Print help
json: --jsonbool, 0, SetTrue否；条件必填见行为; false—原始帮助：Emit a machine-readable JSON summary (for CI)
targets: <TARGETS> (#1)String, 1..∞, Append否；条件必填见行为; Clap 无显式默认；运行时：tests/；无显式目标时 Rust 发现 scripts/——

Clap 参数组（literal metadata）：{"arguments":["json","targets"],"id":"Test","multiple":true,"required":false}

输入、行为与副作用。 本地通过 uv 跑 Python pytest、bun test 跑 TypeScript，并跑发现的 Rust 内嵌测试。默认发现 tests/，Rust 用 scripts/。匹配版本 viat-test-host 提供假资源，不使用登录服务端。但用户测试代码本身不受网络沙箱限制。

实际输出与退出。 流式输出运行器结果；—json 捕获机器报告，诊断写 stderr。传播汇总非零测试状态。缺前提会失败；无测试可打印 no tests found，不代表覆盖。 完全未发现测试时明确退出 0（no tests found），与 endpoint test 的空夹具失败不同。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。

合成调用示例（只校验语法，不执行）。

终端窗口
viat script test --json

失败处理、验证与清理。 需相应语言 uv/bun/cargo 和匹配 host（VIAT_TEST_HOST_BIN 可覆盖）。TypeScript 临时注入 node_modules/viat 后清理。检查夹具是否外呼；审查后可删本地报告。

viat script update

Section titled “viat script update”

前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。

Usage: viat script update [OPTIONS] <NAME>

命令别名： viat script edit

参数 ID / 完整拼写类型、消费值数量、action必填 / 默认允许值冲突、别名、解析与原始 Clap 帮助
dedicated: --dedicatedbool, 0, SetTrue否；条件必填见行为; false——
dedicated_count: --dedicated-counti32, 1, Set否；条件必填见行为; Clap 无显式默认——
file: --fileString, 1, Set否；条件必填见行为; Clap 无显式默认——
help: --help / -hString, 0, Help否；条件必填见行为; Clap 无显式默认—原始帮助：Print help
name: <NAME> (#1)String, 1, Set是; Clap 无显式默认——
no_dedicated: --no-dedicatedbool, 0, SetTrue否；条件必填见行为; false—冲突 ID：dedicated

Clap 参数组（literal metadata）：{"arguments":["dedicated","dedicated_count","file","name","no_dedicated"],"id":"Update","multiple":true,"required":false}

输入、行为与副作用。 部分 PATCH；加载配置前要求至少 —file/—dedicated/—no-dedicated/—dedicated-count 之一。edit 是别名。只改传入字段；变更草稿，不改已发布快照。

实际输出与退出。 stdout: updated <name> → vN，可附待发布端点提示。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。

合成调用示例（只校验语法，不执行）。

终端窗口
viat script update demo_echo --file demo.py

失败处理、验证与清理。 dedicated 冲突/数量或文件无效会失败。保存旧源码/设置，show 核查后有意发布；恢复旧草稿并重新发布可回退已交付变更。

viat script upload

Section titled “viat script upload”

前提与权限。 平台登录、已选择项目，有效项目角色为 Owner/Admin/Developer。Operator 不可用，包括只读形式。 以下合成名称仅用于隔离演示项目；标识符请替换成该项目 list/create 返回的值。

Usage: viat script upload [OPTIONS] --binary <BINARY> <NAME>

命令别名： 无。

参数 ID / 完整拼写类型、消费值数量、action必填 / 默认允许值冲突、别名、解析与原始 Clap 帮助
binary: --binaryPathBuf, 1, Set是; Clap 无显式默认—原始帮助：The executable
folder: --folderString, 1, Set否；条件必填见行为; Clap 无显式默认—原始帮助：Folder half of the script’s identity, when the bare name is ambiguous
help: --help / -hString, 0, Help否；条件必填见行为; Clap 无显式默认—原始帮助：Print help
name: <NAME> (#1)String, 1, Set是; Clap 无显式默认——
target: --targetString, 1, Set否；条件必填见行为; Clap 无显式默认；运行时：CLI 机器 OS/架构—原始帮助：<os>/<arch> it was built for; defaults to this machine’s

Clap 参数组（literal metadata）：{"arguments":["binary","folder","name","target"],"id":"Upload","multiple":true,"required":false}

输入、行为与副作用。 仅 binary 语言：读取非空可执行文件，以 update_manifest=1 上传；服务端随后把 digest 记为新草稿版本。—target 默认 CLI 机器 OS/架构，不探测远程；—folder 消歧。

实际输出与退出。 打印字节数、目标、digest、manifest 新版本或未变，以及待发布端点。不发布。 除本节例外外，正常完成为 0，参数/文件/HTTP/运行错误为非零（解析错误通常 2，运行错误通常 1）。

合成调用示例（只校验语法，不执行）。

终端窗口
viat script upload demo_binary --binary ./demo-worker --target linux/x86_64

失败处理、验证与清理。 需服务端允许上传、匹配可执行格式及 binary manifest 脚本。语言错误/空文件/不支持目标会失败。show/build 核查后有意发布；回退需旧 manifest 和 artifact（show 不取字节）。

实现核对依据

Section titled “实现核对依据”

语法来自固定 Clap 合同与 main.rs；行为/权限核对以下源文件，路径相对产品仓库根。

  • crates/viat-cli/src/commands/script.rs
  • crates/viat-api/src/handlers/scripts.rs
  • crates/viat-api/src/handlers/rust_artifact.rs