CLI 参考

Wippy 运行时的命令行界面。

全局标志

适用于所有命令：

标志 缩写 描述
--config 配置文件，可重复；后面的文件覆盖前面的（默认：.wippy.yaml）
--verbose -v 启用调试日志
--very-verbose 包含堆栈跟踪的调试日志
--console -c 彩色控制台日志
--silent -s 禁用控制台日志
--event-streams -e 将日志流式传输到事件总线
--profiler -p 在 localhost:6060 启用 pprof
--memory-limit -m 内存限制（例如 1G、512M）

内存限制优先级：--memory-limit 标志 > GOMEMLIMIT 环境变量 > 默认 1GB。

--config 可以传入多次以组合配置文件。文件从左到右合并：后面的文件覆盖匹配的值并保留其余内容。每个显式指定的文件都必须存在；不带 --config 时，默认的 .wippy.yaml 是可选的。第一个文件锚定用于解析相对路径的目录。配置按顺序应用：文件组合，然后是 --profile 选择，最后是 --set 覆盖。参见配置。

wippy init

创建新的锁文件。

wippy init
wippy init --src-dir ./src --modules-dir .wippy
标志 缩写 默认值 描述
--src-dir -d ./src 源代码目录
--modules-dir .wippy 模块目录
--lock-file -l wippy.lock 锁文件路径

wippy run

启动运行时或执行命令。

wippy run                                   # 启动运行时
wippy run list                              # 列出可用命令
wippy run migrate                           # 运行命名的自定义命令
wippy run snapshot.wapp                     # 从打包文件运行
wippy run acme/http                         # 从中心运行模块
wippy run acme/http@1.2.3                   # 运行指定版本
wippy run --exec app:worker                 # 启动运行时并执行单个进程
标志 缩写 描述
--override -o 覆盖条目值（namespace:entry:field=value）；field 可为 kind 以更改条目种类
--set 覆盖配置值（section.path=value，可重复，优先于配置文件）
--exec -x 执行进程后退出（namespace:entry）
--host --exec 的终端主机 ID（若仅存在一个 terminal.host 则自动检测）
--registry 中心模块的注册中心 URL
--profile 应用来自 .wippy.yaml 或打包运行时元数据的运行时 profile（可重复，按顺序应用）

运行中心模块（wippy run org/module）会将其解析一次，记录到 wippy.lock，并在本地保存已验证的包。后续对同一引用的运行从锁文件启动 — 无需网络。不再匹配锁文件的版本选择器会被拒绝，并提示运行 wippy update。

对于本地应用，wippy run 会在任何运行时服务启动之前修复过期的锁文件。它加载源码中的依赖声明，当锁文件已经满足这些声明时，仅根据本地和已安装的证据重新求解依赖图（已验证的离线访问，不使用网络）。如果离线求解结果与锁文件一致，启动过程不变。如果求解成功但结果不同，该结果就成为候选依赖图；只有当离线求解失败或锁文件不再满足源码声明时，才会请求 hub 进行求解。候选依赖图缺少的包会被下载并校验，然后才重写 wippy.lock。选中了部署根的锁文件具有权威性，绝不会被重新求解。

--exec 会阻塞直到被启动的进程产生结果，然后将该进程的退出码作为 CLI 退出码传播。在 --exec 期间按 Ctrl-C 会取消运行中的进程，运行时仍会优雅关闭；第二次信号会强制退出。

--set 从命令行写入任意运行时配置值，按叶子合并到 .wippy.yaml 之上：

wippy run --set cluster.enabled=true \
          --set cluster.membership.join_addrs=node-2:7946,node-3:7946 \
          --set cluster.raft.bootstrap_expect=3

值按形态转换：true/false 转为布尔，整数和浮点转为数字，其余保持字符串（在选项需要时，5s 这样的时长会被解析）。

wippy test

运行测试入口点：即声明了 test use case 的进程条目。运行时启动、执行该条目并退出。wippy run 不会自动运行测试入口点；测试始终通过 wippy test 进行。

wippy test                     # 从本地项目运行测试
wippy test snapshot.wapp       # 从打包文件运行测试
wippy test acme/module@1.2.3   # 从中心模块运行测试
标志 缩写 描述
--override -o 覆盖条目值（namespace:entry:field=value）
--host 终端主机 ID（若仅存在一个 terminal.host 则自动检测）
--registry 中心模块的注册中心 URL
--set 覆盖配置值（section.path=value，可重复）
--profile 应用运行时 profile（可重复，按顺序应用）

wippy lint

检查 Lua 代码的类型错误和警告。

wippy lint
wippy lint --level warning
wippy lint --json
wippy lint --rules

验证所有 Lua 条目：function.lua、library.lua、process.lua、workflow.lua（包括其 .bc 变体）。

标志 缩写 默认值 描述
--lock-file -l wippy.lock 锁文件路径
--level warning 最低严重级别：error、warning、hint
--ns 按命名空间模式过滤（例如 app、lib.*）
--code 按错误代码过滤（例如 E0001,E0004）
--rules false 启用风格/质量 lint 规则
--summary false 按错误代码分组输出
--limit 0 最多显示的诊断数（0 = 无限制）
--json false JSON 输出
--no-color false 禁用彩色输出
--cache-reset false lint 前清除 Lua 缓存
--profile 应用合并后运行时配置中的工作区 profile（可重复）
--set 覆盖合并后运行时配置的值（section.path=value，可重复）

wippy add

添加模块依赖。

wippy add acme/http
wippy add acme/http@1.2.3
wippy add acme/http@latest
标志 缩写 默认值 描述
--lock-file -l wippy.lock 锁文件路径
--registry 注册中心 URL

wippy install

从锁文件安装依赖。

wippy install                            # 安装全部
wippy install acme/http                  # 安装指定模块
wippy install --refresh acme/http        # 重新获取指定模块
标志 缩写 默认值 描述
--lock-file -l wippy.lock 锁文件路径
--refresh false 重新获取每个模块，绕过缓存
--force false --refresh 的别名
--repair false --refresh 的别名
--registry 注册中心 URL
--profile 应用合并后运行时配置中的工作区 profile（可重复）
--set 覆盖合并后运行时配置的值（section.path=value，可重复）

wippy update

更新依赖并重新生成锁文件。

wippy update                      # 更新全部
wippy update acme/http            # 更新指定模块
wippy update acme/http demo/sql   # 更新多个模块
标志 缩写 默认值 描述
--lock-file -l wippy.lock 锁文件路径
--src-dir -d ./src 源代码目录
--modules-dir .wippy 模块目录
--registry 注册中心 URL
--profile 应用合并后运行时配置中的工作区 profile（可重复）
--set 覆盖合并后运行时配置的值（section.path=value，可重复）

wippy artifacts

处理构建时文件系统构件。

wippy artifacts materialize

从现有的包中校验并物化一个构件文件系统。

wippy artifacts materialize snapshot.wapp app:package_fs
wippy artifacts materialize snapshot.wapp app:package_fs --root build
标志 默认值 描述
--root .wippy 物化根目录

该资源通过完整的 namespace:name 寻址，必须声明 meta.artifact.format，且该格式必须已在 CLI 中注册。此命令不解析任何模块依赖，不修改 wippy.lock，不调用任何包管理器，也不参与运行时组合。参见构建时构件。

wippy pack

创建快照包（.wapp 文件）。

wippy pack snapshot.wapp
wippy pack release.wapp --description "Release 1.0"
wippy pack app.wapp --embed app:assets --bytecode **
标志 缩写 描述
--lock-file -l 锁文件路径
--description -d 包描述
--tags -t 包标签（逗号分隔）
--meta 自定义元数据（key=value）
--embed 嵌入 fs.directory 条目（模式匹配）
--embed-all 嵌入所有 fs.directory 条目（不能与 --embed 同时使用）
--list 列出 fs.directory 条目（预览模式）
--exclude-ns 排除命名空间（模式匹配）
--exclude 排除条目（模式匹配）
--bytecode 将 Lua 编译为字节码（** 表示全部）
--profile 打包前应用来自 .wippy.yaml 的运行时 profile（可重复，按顺序应用）

不带 --embed 或 --embed-all 时，嵌入模式回退到模块清单 wippy.yaml 的 embed: 部分。打包应用时还会携带其依赖包中嵌入的资源，且最终的包只暴露主模块的命令。

输出文件以原子方式写入：包先构建到目标目录中的临时文件，同步、校验，然后才重命名覆盖目标文件，并在目标已存在时继承其权限。打包失败不会影响原有文件。将输出指定为该包的输入之一 — 相同路径，或解析到同一文件的硬链接或符号链接 — 会被拒绝，而不是在读取中途截断输入。

--meta 无法写入保留的元数据。键 registry 以及 wippy. 或 system. 前缀下的任何内容都归包格式所有，会被拒绝。

声明了 meta.artifact.format 的资源在打包时会被校验，因此格式错误的构件会在此处失败，而不是在消费方失败。参见构建时构件。

wippy publish

将模块发布到 Hub。

wippy publish
wippy publish --version 1.0.0
wippy publish --dry-run

从当前目录的 wippy.yaml 读取配置。

标志 描述
--version 发布版本
--dry-run 仅验证，不实际发布
--label 以可变标签发布，而非版本号
--release-notes 发布说明
--protected 将版本标记为受保护
--embed 按 id 或 name 嵌入 fs.directory 条目
--config 包含 wippy.yaml 的目录路径（默认：.）
--registry 注册中心 URL
--create 若模块在注册中心尚不存在则自动创建
--module-visibility 新建模块的可见性（仅 --create）：public 或 private（默认：private）
--module-type 模块类型：library、application、agent 或 plugin（覆盖 wippy.yaml 中的 type:）
--module-display-name 新建模块的显示名称（仅 --create）

模块类型通常在 wippy.yaml 中以 type: 声明（参见发布）；--module-type 仅对单次发布覆盖它。两者都未设置时，新建模块默认为 application 并给出弃用警告。

在 Hub 中搜索模块。

搜索会在可用时使用所选注册中心保存的认证令牌。使用 wippy auth login 完成认证后即可用你的注册中心身份搜索；--registry 用于选择要使用其凭据的 注册中心。

wippy search http
wippy search "sql driver" --limit 20
wippy search auth --json
标志 默认值 描述
--json false 以 JSON 格式输出
--limit 20 最大结果数
--registry 注册中心 URL

wippy auth

管理注册中心认证。

wippy auth login

wippy auth login
wippy auth login --token YOUR_TOKEN
标志 描述
--token API 令牌
--registry 注册中心 URL
--local 将凭据存储在本地

wippy auth logout

wippy auth logout
标志 描述
--registry 注册中心 URL
--local 删除本地凭据

wippy auth status

wippy auth status
wippy auth status --json
标志 描述
--json 以 JSON 格式输出

wippy readme

从 Hub 获取模块的 README。

wippy readme wippy/terminal
wippy readme wippy/terminal@1.2.3
wippy readme --json wippy/terminal@latest
标志 描述
--json 以 JSON 格式输出
--registry 注册中心 URL（默认：来自凭据）

wippy registry

查询和检查注册表条目。两个子命令都接受 --profile 和 --set，用于调整加载条目时所使用的合并运行时配置。

wippy registry list

wippy registry list
wippy registry list --kind "function.lua.*"
wippy registry list --ns "app.*" --json
wippy registry list --meta "type=api" --meta "enabled=true"
标志 缩写 描述
--kind -k 按类型过滤（glob 模式）
--ns -n 按命名空间过滤（glob 模式）
--name 按名称过滤（glob 模式）
--meta 按元数据过滤（可重复）
--json 以 JSON 格式输出
--yaml 以 YAML 格式输出
--registry-meta 在 JSON 或 YAML 输出中包含注册表所有的元数据（owner、root）；需要 --json 或 --yaml
--lock-file -l 锁文件路径

--meta 的元数据运算符：

运算符 含义
field=value 精确匹配
field~regex 正则匹配
field*substr 包含子串
field^prefix 以前缀开头
field$suffix 以后缀结尾

wippy registry show

wippy registry show app:http:handler
wippy registry show app:config --yaml
标志 缩写 描述
--field -f 显示指定字段
--json 以 JSON 格式输出
--yaml 以 YAML 格式输出
--raw 原始输出
--lock-file -l 锁文件路径

wippy version

打印版本信息。

wippy version
wippy version --short

自定义命令

任何 process.lua 或 process.wasm 条目都可以通过添加 command 元数据注册为命名命令：

entries:
  - name: migrate_runner
    kind: process.lua
    meta:
      command:
        name: migrate
        short: Run database migrations
    source: file://runner.lua
    method: main
    modules:
      - io
      - registry
      - funcs

使用以下方式运行：

wippy run migrate

列出所有可用命令：

wippy run list

wippy run list 接受 --profile 和 --set，因此列表反映的是与 wippy run 相同的合并后运行时配置。

命令元数据字段

字段 必填 描述
name 是 与 wippy run <name> 配合使用的命令名称
short 否 在 wippy run list 中显示的简短描述
main 否 将此条目标记为默认入口点。当运行 pack 或中心模块时未给出命令名，会执行该用例中唯一的 main 条目；即使没有 main，唯一的入口点也会被选用，而存在多个入口点却没有 main 则是错误
use_case 否 入口点类别，默认 run。声明 use_case: test 的条目就是 wippy test 执行的对象
security 否 从 CLI 启动时命令所运行的安全上下文

任何进程条目类型均可使用（process.lua、process.wasm）。命令名称不做唯一性检查；当多个已加载条目声明相同名称时，按注册表顺序第一个匹配的条目会运行。命令名称之后的参数会作为字符串负载传递给进程。

命令安全

命令条目声明其 CLI 启动所运行的角色身份和策略作用域：

entries:
  - name: migrate_runner
    kind: process.lua
    meta:
      command:
        name: migrate
        short: Run database migrations
        security:
          actor:
            id: system.migrations
            meta:
              role: operator
          policies:
            - app.security:migrations_policy
          groups:
            - app.security:operators
    source: file://runner.lua
    method: main
字段 说明
actor.id 被启动进程的角色身份
actor.meta 由策略求值的角色属性
policies 添加到作用域的单个策略的注册表 ID（namespace:name）
groups 其策略被添加到作用域的策略组的注册表 ID

该块位于 meta.command 内部，因为它只作用于 CLI 启动路径 — 操作员在自己的部署上启动了该命令，这就是信任锚点。它对同一进程条目的普通 spawn 没有影响；那些遵循条目自身的 security: 块。

声明是失败即关闭的，并在进程启动前完成校验：

  • security 内的未知字段会被拒绝。
  • 空的 security 块（没有 actor、没有 policies、没有 groups）会被拒绝。
  • 没有 name 的 security 会被拒绝 — 命令必须可命名才能被启动。
  • 无法解析的策略或策略组会拒绝启动；解析是原子的，因此绝不会安装出部分作用域。

当该块省略 actor 时，继承调用方的角色身份。当它同时省略 policies 和 groups 时，继承调用方的作用域。

示例

开发工作流

# 初始化项目
wippy init
wippy add wippy/test wippy/llm
wippy install

# 检查错误
wippy lint

# 启用调试输出运行
wippy run -c -v

# 覆盖本地开发配置
wippy run -o app:db:host=localhost -o app:db:port=5432

生产部署

# 创建带字节码的发布包
wippy pack release.wapp --bytecode ** --exclude-ns test.**

# 从打包文件运行并设置内存限制
wippy run release.wapp -m 2G

调试

# 执行单个进程
wippy run --exec app:worker

# 启用性能分析器
wippy run -p -v
# 然后：go tool pprof http://localhost:6060/debug/pprof/heap

依赖管理

# 添加新依赖
wippy add acme/http@latest

# 强制重新下载
wippy install --force

# 更新指定模块
wippy update acme/http

发布

# 登录 Hub
wippy auth login

# 验证模块
wippy publish --dry-run

# 发布
wippy publish --version 1.0.0 --release-notes "Initial release"

环境变量

变量 作用
WIPPY_TOKEN 注册中心认证令牌；覆盖已存储的凭据（通过 hub.auth.authenticate 推送的 token 优先级更高）
WIPPY_REGISTRY 默认注册中心 URL（被 --registry 覆盖）
WIPPY_CACHE_DIR 通过 wippy run org/module 运行的中心模块的缓存目录（默认：~/.wippy/cache）
GOMEMLIMIT 未设置 --memory-limit 时的内存限制回退值

.wippy.yaml 中的值可以通过 ${env:NAME} 引用 OS 环境变量，在文件加载时解析；变量缺失会导致配置加载失败。裸 ${name} 引用则从配置的 vars: 部分解析。

配置文件

创建 .wippy.yaml 以保存持久化设置：

logger:
  encoding: console

logmanager:
  stream_to_events: true

profiler:
  enabled: true
  address: localhost:6060

override:
  app:gateway:addr: ":9090"
  app:db:host: "localhost"

另请参阅