CLI リファレンス

Wippy CLI を使用して、プロジェクトの初期化、ランタイムの実行、依存関係の管理、レジストリエントリの確認、モジュールの公開を行います。

これはコマンドリファレンスです。ソース、ロックファイル、レジストリエントリ、または公開メタデータを扱うコマンドの例は、既存のプロジェクトまたはモジュールを前提としています。単一のエンドツーエンドプロジェクトを示すものではありません。

グローバルフラグ

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

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

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

wippy publish はグローバルオプションを、コマンドローカルの --config <dir> オプションで置き換えます。このコマンドでは、値は繰り返し可能なランタイム設定ファイルではなく、wippy.yaml を含むディレクトリです。

wippy init

wippy.lock を作成します。すでに存在する場合は、そのソースディレクトリとモジュールディレクトリの設定を更新します。このコマンドは、アプリケーションのソースファイルやレジストリエントリを生成しません。

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

wippy run

ランタイムを起動するか、コマンドを実行する。

wippy run                                   # Start runtime
wippy run list                              # List available commands
wippy run migrate                           # Run a named custom command
wippy run snapshot.wapp                     # Run from pack file
wippy run acme/http                         # Run module from hub
wippy run acme/http@1.2.3                   # Run specific version
wippy run --exec app:worker                 # Start runtime and execute a single process

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

ローカルのアプリケーションでは、wippy run はランタイムサービスが起動する前に古くなったロックを修復します。ソースの依存関係宣言を読み込み、ロックがすでにそれらを満たしている場合は、ローカルおよびインストール済みの証跡のみからグラフを再解決します (verified-offline アクセス、ネットワークなし)。このオフライン解決がロックと一致すれば、ブートはそのまま続行します。解決に成功したがロックと異なる場合、それが候補グラフになります。ハブに解決を依頼するのは、オフライン解決が失敗した場合か、ロックがソースの宣言をもはや満たしていない場合だけです。候補グラフに欠けているパックがダウンロードされて検証され、その後にのみ wippy.lock が書き換えられます。デプロイメントルートを選択しているロックは信頼できる情報源であり、再解決されることはありません。

--exec は起動したプロセスが結果を生成するまでブロックし、そのプロセスの終了コードを CLI の終了コードとして伝播します。--exec 中の Ctrl-C は実行中のプロセスをキャンセルし、ランタイムはそれでもグレースフルにシャットダウンします。2 回目のシグナルは強制終了します。

--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

ソースを含む 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                            # Install all
wippy install acme/http                  # Install specific module
wippy install --refresh acme/http        # Re-fetch a specific module

wippy update

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

wippy update                      # Update all
wippy update acme/http            # Update specific module
wippy update acme/http demo/sql   # Update multiple

wippy artifacts

ビルド時のファイルシステムアーティファクトを扱う。

wippy artifacts materialize

既存のパックから 1 つのアーティファクトファイルシステムを検証してマテリアライズする。

wippy artifacts materialize snapshot.wapp app:package_fs
wippy artifacts materialize snapshot.wapp app:package_fs --root build

リソースは完全な 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 "**"

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

出力ファイルはアトミックに書き込まれます。パックは出力先ディレクトリ内の一時ファイルとしてビルドされ、同期・検証されたうえで、はじめて対象へリネームされます。既存のファイルがある場合はそのパーミッションを引き継ぎます。パックに失敗しても以前のファイルはそのまま残ります。パックの入力の 1 つでもある出力を指定すること — 同じパス、または同じファイルに解決されるハードリンクやシンボリックリンク — は、読み取り中の入力を切り詰めるのではなく拒否されます。

--meta は予約済みメタデータを書き込めません。キー registry、および wippy. または system. 接頭辞の下にあるものはパックフォーマットが所有しており、拒否されます。

meta.artifact.format を宣言するリソースはパック時に検証されるため、不正なアーティファクトは消費側ではなくここで失敗します。ビルド時アーティファクトを参照してください。

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 auth login で認証するとレジストリの ID で検索でき、 --registry で使用するレジストリの資格情報を選択できます。

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
        security:
          actor:
            id: app:migrations
          policies:
            - app.security:migrations
          groups:
            - app.security:operators
    source: file://runner.lua
    method: main
    modules:
      - io
      - registry
      - funcs

以下のコマンドで実行する:

wippy run migrate

利用可能な全コマンドを一覧表示する:

wippy run list

wippy run list は --profile と --set を受け付けるため、一覧は wippy run が使用するのと同じマージ済みランタイム設定を反映する。

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

任意のプロセスエントリ種類 (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

このブロックが meta.command の中にあるのは、CLI からの起動パスにのみ適用されるためである。オペレータが自身のデプロイメント上でコマンドを開始したという事実が信頼の起点となる。同じプロセスエントリの通常のスポーンには影響せず、そちらはエントリ自身の security: ブロックに従う。

宣言はフェイルクローズドで、プロセスの起動前に検証される:

• security 内の未知のフィールドは拒否される。
• 空の security ブロック (アクターもポリシーもグループもない) は拒否される。
• name を持たない security は拒否される — コマンドは起動できるよう名前を持たなければならない。
• 解決できないポリシーやグループがあると起動を拒否する。解決はアトミックであり、部分的なスコープがインストールされることはない。

ブロックが actor を省略した場合、呼び出し元のアクターが継承される。policies と groups の両方を省略した場合、呼び出し元のスコープが継承される。

使用例

開発ワークフロー

# Initialize dependency lock metadata
wippy init
wippy add wippy/test
wippy add wippy/llm
wippy install

# Check for errors
wippy lint

# Run with debug output
wippy run -c -v

# Override config for local dev
wippy run -o app:db:host=localhost -o app:db:port=5432

本番デプロイ

# Create release pack with bytecode
wippy pack release.wapp --bytecode "**" --exclude-ns "test.**"

# Run from pack with memory limit
wippy run release.wapp -m 2G

デバッグ

# Execute single process
wippy run --exec app:worker

# With profiler enabled
wippy run -p -v
# Then: go tool pprof http://localhost:6060/debug/pprof/heap

依存関係管理

# Add new dependency
wippy add acme/http@latest

# Force re-download
wippy install --force

# Update specific module
wippy update acme/http

公開

# Login to hub
wippy auth login

# Validate module
wippy publish --dry-run

# Publish
wippy publish --version 1.0.0 --release-notes "Initial release"

環境変数

.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"

関連項目

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