walrus-cli について
walrus-cliは、Walrusユーザー向けのコマンドラインスキルです。walrusコマンドによるblobの保存と読み出し、ライフサイクル管理、ネットワーク情報の確認を説明します。設定、ネットワークコンテキスト、スクリプト向けJSON出力も扱います。
主な機能
- 01blobの保存、読み出し、状態確認
- 02blobの延長、削除、焼却、共有
- 03価格、エポック、ネットワーク状態の確認
- 04スクリプト向けJSON出力
- 05ウォレット、設定ファイル、ネットワークコンテキストの設定
活用シーン
- 01コマンドラインからファイルをアップロードまたは取得する
- 02スクリプトやCI/CDワークフローで操作を自動化する
- 03ネットワーク状態を調べ、ストレージ価格を確認する
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/walrus-cliを入力して読み込まれたか確認します。
同梱ファイルevals/evals.json
詳細
Walrus CLI
ソースの制約： このスキルのすべての情報は、 Walrus クライアントのドキュメントをソースとしています。 このスキルを拡張する際は、これらのソースのみを参照してください。
walrus CLI は、Walrus を操作するための主要なコマンドラインツールです。blob の保存と読み取り、blob のステータス確認、blob のライフサイクル管理（延長、削除、バーン、共有）、およびキルトの操作に対応しています。すべてのコマンドで、スクリプト用の JSON 出力を利用できます。
このスキルのすべてのパターンは、以下を基にしています。
- https://docs.wal.app/docs/walrus-client/walrus-cli
- https://docs.wal.app/docs/walrus-client/storing-blobs
- https://docs.wal.app/docs/walrus-client/reading-blobs
- https://docs.wal.app/docs/walrus-client/json-mode
CLI コマンドについて不明な点がある場合は、回答する前に該当するページを取得してください。
関連スキル
| トピック | スキル | 次の場合に読み込む |
|---|---|---|
| blob のライフサイクル | walrus-blob-lifecycle | blob の延長、削除、バーン、共有、大容量アップロードを行う場合 |
| キルト | walrus-quilts | store-quilt／read-quilt で小さな blob をまとめる場合 |
| HTTP API | walrus-http-api | CLI の代わりに REST エンドポイントを使用する場合 |
| TypeScript SDK | walrus-ts-sdk | TypeScript からプログラムでアクセスする場合 |
| 暗号化 | walrus-data-security | 保存前にデータを暗号化する場合 |
スキルの内容
インストール
suiup でインストールします。
curl -sSfL https://raw.githubusercontent.com/Mystenlabs/suiup/main/install.sh | sh
suiup install sui
suiup install walrus
最新バージョンに更新します。
suiup update walrus
特定のネットワークバージョンに切り替えます。
# Correct syntax: walrus@<network>
suiup install walrus@mainnet
suiup install walrus@testnet
walrus --help で確認します。各サブコマンドも --help に対応しています。spawn walrus ENOENT または command not found が表示された場合、バイナリが PATH にありません。suiup インストーラーを再実行するか、~/.suiup/bin を PATH に追加してください。
設定
CLI は、現在のディレクトリ、$XDG_CONFIG_HOME/walrus/、~/.config/walrus/、または ~/.walrus/ から client_config.yaml を読み込みます。最新の設定をダウンロードします。
curl --create-dirs https://docs.wal.app/setup/client_config.yaml \
-o ~/.config/walrus/client_config.yaml
--config <PATH> でカスタム設定の場所を指定します。標準以外の Sui ウォレット設定には --wallet <PATH> を使用します。設定内の複数のコンテキストを切り替えるには、--context <NAME> を使用します。
blob の保存
# Store a file for 5 epochs
walrus store myfile.png --epochs 5
# Store multiple files (glob patterns supported)
walrus store *.png --epochs 10
# Store as permanent (cannot be deleted before expiry)
walrus store myfile.png --epochs 30 --permanent
# Store as deletable (default)
walrus store myfile.png --epochs 10 --deletable
# Store using an upload relay
walrus store myfile.png --epochs 5 --upload-relay https://relay.example.com
blob の有効期間オプション
| オプション | 説明 |
|---|---|
--epochs <N> | エポック数（最大 53＝2 年）。最大値には --epochs max を使用します。 |
--earliest-expiry-time <TIME> | RFC 3339 の日付、または簡易形式（例：2025-06-20 15:00:00） |
--end-epoch <N> | 特定の終了エポック番号 |
blob は終了エポックの開始時に期限切れになります。エポックの切り替わり直前に --epochs 1 を指定して保存すると、ほぼ即座に期限切れになります。
blob の永続性
| オプション | 動作 |
|---|---|
--deletable | 所有者は有効期限前に削除できます（新しい blob のデフォルト） |
--permanent | アップロードしたユーザーであっても、有効期限前に削除できません |
自動最適化
- 同じ内容で十分な有効期間を持つ永続 blob が存在する場合、クライアントは再アップロードをスキップします（
--forceで上書きできます）。 - ウォレットに適切なストレージリソースがある場合、新たに購入せず再利用します。
- blob がすでに認証済みでも、削除可能であるか有効期間が不十分な場合、クライアントはエンコード済みデータの送信をスキップし、証明書のみを取得します。
blob の読み取り
# Check blob status by blob ID
walrus blob-status --blob-id <BLOB_ID>
# Check blob status by file (re-encodes to derive blob ID)
walrus blob-status --file myfile.png
# Status requests time out after 1s per node by default; raise it on slow links
walrus blob-status --blob-id <BLOB_ID> --timeout 5s
# Read a blob to stdout
walrus read <BLOB_ID>
# Read a blob to a file
walrus read <BLOB_ID> --out output.dat
整合性チェック
v1.37 以降、CLI はデフォルトでパフォーマンスに優れた整合性チェックを使用します。完全なチェックには --strict-consistency-check を使用します。書き込み元が既知で信頼できる場合は、--skip-consistency-check を使用します。
JSON モード
スクリプトで使用できるよう、すべてのコマンドが JSON モードに対応しています。
# Store via JSON mode
walrus json '{
"config": "path/to/client_config.yaml",
"command": {
"store": {
"files": ["README.md", "LICENSE"],
"epochs": 100
}
}
}'
# Read via JSON mode
walrus json '{
"command": {
"read": {
"blobId": "4BKcDC0Ih5RJ8R0tFMz3MZVNZV8b2goT6_JiEEwNHQo"
}
}
}'
JSON モードでは、オプション名に kebab-case ではなく camelCase を使用します（blob-status は blobStatus になります）。config、context、wallet、gasBudget などのグローバルオプションは、command と並んでルートに配置します。引数なしで walrus json を実行すると、標準入力から JSON を読み取ります（echo '{...}' | walrus json）。出力は常に JSON 形式なので、jq にパイプで渡せます。失敗した場合、CLI は人間が読めるエラーメッセージを標準エラー出力に表示し、ゼロ以外の終了コードで終了します。
完全な JSON モードを使わずに JSON 出力を得るには、標準コマンドに --json を指定します。
walrus store myfile.png --epochs 5 --json
システム情報の確認
# Show current epoch, pricing, and network parameters
walrus info
# Show with JSON output
walrus info --json
walrus info は、現在のエポック番号、エポックの期間、ストレージ単位あたりの価格、書き込み手数料、先のエポックの最大数（53）を表示します。大量にアップロードする前に、価格を確認するために使用してください。サブコマンドを使うと、出力を絞り込めます：walrus info epoch、walrus info committee、walrus info bft、walrus info coin（設定されたコンテキストにおける WAL コインの StructTag）。
Testnet で WAL を取得する
保存には WAL が必要で、各トランザクションには SUI が必要です。Testnet では、CLI を使って SUI を 1:1 の比率で WAL に交換できます。
walrus get-wal --context testnet # exchanges 0.5 SUI (500,000,000 MIST) by default
walrus get-wal --context testnet --amount 1000000000
walrus get-wal --exchange-id <OBJECT_ID> # use a specific exchange object instead of the config's
get-wal は Testnet でのみ動作します。Mainnet ではコンテキストに交換オブジェクトが定義されていないため、The object ID of an exchange object must be specified ... this command is only available on Testnet というエラーが発生してコマンドは失敗します。WAL を取り扱う取引所で Mainnet の WAL を入手するか、WAL を保有するアドレスから転送してもらってください。クライアントが拒否するパッケージの WAL を配布することがあるため、サードパーティの WAL フォーセットは避けてください。
アドレス間で WAL を転送する
Walrus に転送コマンドはありません。Sui では WAL はコインタイプとして扱われるため、sui client を使って転送します（パブリッシャー用ウォレット、共有チームウォレット、エージェント用ウォレットへの資金補充時など）。
# 1. Find the WAL coin objects (coinType ends in ::wal::WAL)
sui client balance ADDRESS --coin-type WAL_COIN_TYPE --with-coins --json
# 2. Transfer a whole coin object
sui client transfer --object-id WAL_COIN_ID --to RECIPIENT_ADDRESS --gas-budget 10000000
# Merge small coins first so one coin covers the amount
sui client merge-coin --primary-coin LARGEST_WAL_COIN_ID --coin-to-merge OTHER_WAL_COIN_ID
Sui はコインオブジェクト全体を転送します。正確な金額を送るには、プログラマブルトランザクションブロックでコインを分割してください。受取人にもガス代として SUI が必要です。
ネットワークの状態を確認する
アップロードが断続的に失敗する場合、通常はクライアントの設定ミスではなく、ストレージノードに到達できないことが原因です。
walrus health --committee # one row per committee node, then a summary
walrus health --committee --sort-by status --json
walrus info bft # tolerated faults f, quorum 2f+1, write threshold n-f
walrus info committee # shard count and committee
障害はノード数ではなく、シャード数で数えます。シャード数を n、f = (n - 1) / 3 とすると、少なくとも n - f 個のシャードが応答すれば書き込みが認証され、n - 2f 個のシャードがあれば読み取りを再構成できます。シャード数が 1,000 のネットワークでは、書き込みには 667 個、読み取りには 334 個のシャードが必要です。正常なシャード数が n - f を大きく上回る場合は通常どおりアップロードできます。わずかに上回る場合は断続的な失敗が予想されます。下回る場合は書き込みを認証できないため、再試行せずに待ってください。--active-set、--node-ids、--node-urls を使うと別のノードセットを選択できます。--detail を指定すると、ノードごとの状態が追加されます。
Testnet と Mainnet の切り替え
設定ファイルでは複数のコンテキストをサポートしています。次のコマンドで切り替えます。
# Use testnet context for a single command
walrus --context testnet store myfile.png --epochs 5
# Use mainnet context
walrus --context mainnet blob-status --blob-id <BLOB_ID>
コンテキストは、client_config.yaml の contexts: キーの下で定義します。各コンテキストでは、system_object、staking_object、n_shards、rpc_urls を指定します。
コントラクトのパラメーター
各ネットワークにおける現在の Walrus コントラクトのパラメーターは次のとおりです。
| パラメーター | Mainnet | Testnet |
|---|---|---|
system_object | 0x2734a3f967c2dcfb4545a04a72e55432c461e78c1afca993ad642380e35429d6 | 0x6c2547cbf202cdf4e19a069a17dbb2fcc407e4ea1049614550ca1e8bd842e0c4 |
staking_object | 0x10b9d30c28448939337279d46fa7e1a2b0e33d5a0e13f1096ee412e1ece41e55 | 0x954e63bc1b3b0523f25e7ba0d2b81fdf8fe08cc2eb53e7b73e87a37e5c4fc601 |
n_shards | 1000 | 1000 |
これらの値は、デフォルトの client_config.yaml と walrus info --json からも確認できます。
ログ
# Enable trace-level logging
RUST_LOG=walrus=trace walrus info
# Default is info level; debug and trace give deeper insight
RUST_LOG=walrus=debug walrus store myfile.png --epochs 5
ガス予算
--gas-budget <MIST> を使うと、コマンドで使用できる SUI の上限を設定できます。省略した場合、ガス予算は自動的に推定されます。
ルール
- 必ず blob の有効期間を指定してください。
walrus storeでは--epochs引数が必須です。デフォルト値はありません。 - すべての blob は公開されています。 機密データは保存前に暗号化してください。
walrus-data-securityスキルを参照してください。 - 自動化には JSON モードを使用してください。
walrus jsonコマンドと--jsonフラグを使うと、CI/CD パイプラインやスクリプトで解析可能な出力が得られます。 - Blob ID はオブジェクト ID とは異なります。 Blob ID はコンテンツを識別します。Sui オブジェクト ID はオンチェーンオブジェクトを識別します。コマンドによって、どちらを指定するかが異なります。各コマンドの
--helpを確認してください。 - ストレージプールは、まだ CLI の機能ではありません。 Rust SDK と Move コントラクトで利用できるプレビュー機能です。
walrus storeにプール用のフラグはありません。walrus-blob-lifecycleを参照してください。 - クライアントを原因と決めつける前に、
walrus health --committeeを確認してください。 発生したりしなかったりするアップロードの失敗は、通常、ストレージノードに到達できないことが原因です。 - シェル補完を生成してください。
walrus completion bash|zsh|fishを実行し、出力を適切な補完ディレクトリに配置してください。
よくある間違い
- エポックの境界付近で
--epochs 1を指定して保存する。 blob は終了エポックの開始時に期限切れとなるため、ほぼすぐに期限切れになることがあります。余裕をもったエポック数を指定してください。 - 削除すればデータが利用できなくなると思い込む。 削除によって、現在および今後のストレージノードから sliver が削除されるだけです。同じ blob のコピーが別に存在する（他の人がアップロードした）場合、データには引き続きアクセスできます。すべての blob は公開されています。
- スクリプトで
--jsonを付け忘れる。 デフォルトでは人間が読みやすい形式で出力されます。自動化で解析可能な出力を得るには、--jsonまたはwalrus jsonを使用してください。 - 設定なしで
walrusを実行する。 CLI にはclient_config.yamlが必要です。これをダウンロードするか、--configで指定してください。設定がないと、設定の不足に関するエラーが発生します。 - SUI/WAL トークンを保有していない。 書き込み操作には、ガス代として SUI、ストレージ用に WAL が必要です。Testnet では、Sui faucet（
sui client faucet）から SUI を取得し、walrus get-walで WAL に交換してください。Mainnet では、取引所または送金で WAL を入手してください。get-walは Mainnet では動作しません。 Cannot find gas coin for signer addressエラーが発生する。 ウォレットに SUI がありません。ガス代用の SUI をアドレスに補充してください。suiup switch walrus 1.48.1を使う（構文が誤っています）。 正しい構文はsuiup install walrus@mainnetまたはsuiup install walrus@testnetです。バージョン番号は直接指定しません。- Blob ID と Sui オブジェクト ID を混同する。
--blob-id（コンテンツハッシュ、URL セーフな base64）を指定するコマンドもあれば、--blob-obj-idまたは--object-id（Sui オブジェクト、0x...形式の 16 進数）を指定するコマンドもあります。各コマンドの--helpを確認してください。 - Testnet の blob がすぐに消える。 Testnet のエポック期間は Mainnet より短く（14 日）、少ないエポック数で保存すると、blob は予想より早く期限切れになります。現在のエポック期間を確認するには、
walrus infoを使用してください。