CLI リファレンス

Wippy ランタイムのコマンドラインインターフェース。

グローバルフラグ

全てのコマンドで使用可能:

メモリ制限の優先順位: --memory-limit フラグ > GOMEMLIMIT 環境変数 > デフォルト 1GB。

--config は複数回指定して設定ファイルを合成できます。ファイルは左から右にマージされます: 後のファイルは一致する値を上書きし、それ以外はすべて保持します。明示的に指定したファイルはすべて存在しなければなりません。--config なしの場合、デフォルトの .wippy.yaml は任意です。最初のファイルが、相対パスの解決に使われるディレクトリを決めます。設定は次の順序で適用されます: ファイル合成、次に --profile の選択、最後に --set の上書き。設定を参照してください。

wippy init

新しいロックファイルを作成する。

wippy init
wippy init --src-dir ./src --modules-dir .wippy

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                 # ランタイムを起動し単一プロセスを実行

ハブモジュールの実行 (wippy run org/module) は一度だけ解決を行い、wippy.lock に記録し、検証済みパックをローカルにベンダリングします。同じ参照のその後の実行はロックから開始されます — ネットワークは不要です。ロックと一致しなくなったバージョンセレクタは、wippy update の実行を促すヒントとともに拒否されます。

--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 ユースケースを宣言するプロセスエントリを実行する。ランタイムが起動し、そのエントリを実行して終了する。wippy run はテストエントリポイントを自動実行しない。テストは常に wippy test を通して行う。

wippy test                     # Run tests from the local project
wippy test snapshot.wapp       # Run tests from a pack file
wippy test acme/module@1.2.3   # Run tests from a hub module

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 バリアントを含む)。

wippy add

モジュール依存関係を追加する。

wippy add acme/http
wippy add acme/http@1.2.3
wippy add acme/http@latest

wippy install

ロックファイルから依存関係をインストールする。

wippy install                            # すべてをインストール
wippy install acme/http                  # 特定のモジュールをインストール
wippy install --refresh acme/http        # 特定のモジュールを再取得

wippy update

依存関係を更新し、ロックファイルを再生成する。

wippy update                      # 全て更新
wippy update acme/http            # 特定のモジュールを更新
wippy update acme/http demo/sql   # 複数を更新

wippy pack

スナップショットパック (.wapp ファイル) を作成する。

wippy pack snapshot.wapp
wippy pack release.wapp --description "Release 1.0"
wippy pack app.wapp --embed app:assets --bytecode **

--embed も --embed-all も指定しない場合、埋め込みパターンはモジュールマニフェスト wippy.yaml の embed: セクションにフォールバックします。アプリケーションをパックすると依存パックの埋め込みリソースも引き継がれ、生成されたパックが公開するのはメインモジュールのコマンドのみです。

wippy publish

モジュールをハブに公開する。

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

カレントディレクトリの wippy.yaml を読み込む。

モジュールタイプは通常、wippy.yaml の type: として宣言します (公開を参照)。--module-type は単一の公開に対してそれを上書きします。どちらも設定されていない場合、新規作成されるモジュールは非推奨警告とともにデフォルトで application になります。

wippy search

ハブでモジュールを検索する。

wippy search http
wippy search "sql driver" --limit 20
wippy search auth --json

wippy auth

レジストリ認証を管理する。

wippy auth login

wippy auth login
wippy auth login --token YOUR_TOKEN

wippy auth logout

wippy auth logout

wippy auth status

wippy auth status
wippy auth status --json

wippy readme

ハブからモジュールの README を取得する。

wippy readme wippy/terminal
wippy readme wippy/terminal@1.2.3
wippy readme --json wippy/terminal@latest

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"

--meta のメタデータ演算子:

wippy registry show

wippy registry show app:http:handler
wippy registry show app:config --yaml

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

コマンドメタデータフィールド

任意のプロセスエントリ種類 (process.lua、process.wasm) が使用可能。コマンド名はロードされた全エントリ間で一意でなければならない。コマンド名の後の引数は文字列ペイロードとしてプロセスに渡される。

使用例

開発ワークフロー

# プロジェクトを初期化
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

公開

# ハブにログイン
wippy auth login

# モジュールを検証
wippy publish --dry-run

# 公開
wippy publish --version 1.0.0 --release-notes "Initial release"

環境変数

.wippy.yaml 内の値は ${env:NAME} で OS 環境変数を参照でき、ファイルのロード時に解決されます。変数が存在しない場合、設定のロードは失敗します。裸の ${name} 参照は、代わりに設定の vars: セクションから解決されます。

設定ファイル

永続的な設定のために .wippy.yaml を作成する:

logger:
  encoding: console

logmanager:
  min_level: -1  # debug

profiler:
  enabled: true
  address: localhost:6060

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

関連項目

• 設定 - 設定ファイルリファレンス
• オブザーバビリティ - 監視とログ