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。

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 test                               # 运行测试
wippy run snapshot.wapp                      # 从打包文件运行
wippy run acme/http                          # 运行模块
wippy run --exec app:processes/app:worker   # 执行单个进程
标志 缩写 描述
--override -o 覆盖条目值（namespace:entry:field=value）
--exec -x 执行进程后退出（host/namespace:entry）
--host 执行主机
--registry 注册中心 URL

wippy lint

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

wippy lint
wippy lint --level warning

验证所有 Lua 条目：function.lua.*、library.lua.*、process.lua.*、workflow.lua.*。

标志 描述
--level 报告的最低严重级别

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 --force
标志 缩写 描述
--lock-file -l 锁文件路径
--force 绕过缓存，始终重新下载
--registry 注册中心 URL

wippy update

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

wippy update                      # 更新全部
wippy update acme/http            # 更新指定模块
wippy update acme/http demo/sql   # 更新多个模块
标志 缩写 默认值 描述
--lock-file -l wippy.lock 锁文件路径
--src-dir -d . 源代码目录
--modules-dir .wippy 模块目录
--registry 注册中心 URL

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 条目（模式匹配）
--list 列出 fs.directory 条目（预览模式）
--exclude-ns 排除命名空间（模式匹配）
--exclude 排除条目（模式匹配）
--bytecode 将 Lua 编译为字节码（** 表示全部）

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

在 Hub 中搜索模块。

wippy search http
wippy search "sql driver" --limit 20
wippy search auth --json
标志 描述
--json 以 JSON 格式输出
--limit 最大结果数
--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

wippy registry

查询和检查注册表条目。

wippy registry list

wippy registry list
wippy registry list --kind function.lua
wippy registry list --ns app --json
标志 缩写 描述
--kind -k 按类型过滤
--ns -n 按命名空间过滤
--name 按名称过滤
--meta 按元数据过滤
--json 以 JSON 格式输出
--yaml 以 YAML 格式输出
--lock-file -l 锁文件路径

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: test_runner
    kind: process.lua
    meta:
      command:
        name: test
        short: Run application tests
    source: file://runner.lua
    method: main
    modules:
      - io
      - registry
      - funcs

使用以下方式运行：

wippy run test

列出所有可用命令：

wippy run list

命令元数据字段

字段 必填 描述
name 是 与 wippy run <name> 配合使用的命令名称
short 否 在 wippy run list 中显示的简短描述

任何进程条目类型均可使用（process.lua、process.wasm）。命令名称在所有已加载的条目中必须唯一。命令名称之后的参数会传递给该进程。

示例

开发工作流

# 初始化项目
wippy init
wippy add wippy/http wippy/sql
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:processes/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.yaml 以保存持久化设置：

logger:
  mode: development
  level: debug
  encoding: console

logmanager:
  min_level: -1  # debug

profiler:
  enabled: true
  address: localhost:6060

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

另请参阅