walrus-cli

Walrus CLI

源约束： 本技能中的所有信息均来自 Walrus 客户端文档。 扩展本技能时，只能使用这些来源。

walrus CLI 是与 Walrus 交互的主要命令行工具。它支持存储和读取 blob、检查 blob 状态、管理 blob 生命周期（扩展、删除、销毁、共享），以及处理 quilts。所有命令都支持 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；大型上传
Quilts	walrus-quilts	使用 store-quilt/read-quilt 批量处理小型 blob
HTTP API	walrus-http-api	使用 REST 端点而非 CLI
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> 指定自定义配置位置。使用 --wallet <PATH> 指定非标准的 Sui 钱包配置。使用 --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>	Epoch 数量（最多 53 个，即 2 年）。使用 --epochs max 设为最长时间。
--earliest-expiry-time <TIME>	RFC 3339 日期或宽松格式（例如，2025-06-20 15:00:00）
--end-epoch <N>	指定结束 epoch 编号

Blob 会在其结束 epoch 开始时过期。在 epoch 即将切换时使用 --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 模式的选项名称使用 camelCase，而不是 kebab-case（blob-status 会变为 blobStatus）；config、context、wallet 和 gasBudget 等全局选项则位于根级，与 command 并列。不带参数运行 walrus json，即可从标准输入读取 JSON（echo '{...}' | walrus json）。输出始终为 JSON 格式，适合传递给 jq。若失败，CLI 会向 stderr 输出易于理解的错误信息，并以非零状态码退出。

在任何标准命令中使用 --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 会显示当前 epoch 编号、epoch 时长、每个存储单位的价格、写入费用以及可提前的最大 epoch 数（53）。大规模上传前可用此命令核对价格。子命令可缩小输出范围：walrus info epoch、walrus info committee、walrus info bft 和 walrus info coin（当前配置上下文中 WAL 币的 StructTag）。

在 Testnet 上获取 WAL

存储需要花费 WAL，每笔交易都需要花费 SUI。在 Testnet 上，可通过 CLI 按 1:1 的比例用 SUI 兑换 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 没有转账命令；WAL 在 Sui 上是一种币类型，因此可以用 sui client 转账（例如为发布者钱包、团队共享钱包或 Agent 钱包充值）：

# 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 支付 Gas。

检查网络运行状况

上传偶尔失败，通常是因为存储节点无法访问，而不是客户端配置有误：

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

使用 --gas-budget <MIST> 设置命令可花费的 SUI 上限。若未指定，系统会自动估算 Gas 预算。

规则

1. 始终指定 Blob 的存续时间。 walrus store 的 --epochs 参数是必需的，没有默认值。
2. 所有 Blob 都是公开的。 存储前请加密敏感数据。请参阅 walrus-data-security 技能。
3. 自动化场景请使用 JSON 模式。 walrus json 命令和 --json 标志会生成可供 CI/CD 流水线和脚本解析的输出。
4. Blob ID 不等于对象 ID。 Blob ID 用于标识内容，Sui 对象 ID 用于标识链上对象。有些命令接受前者，有些接受后者。请查看各命令的 --help。
5. 存储池目前还不是 CLI 功能。 存储池是通过 Rust SDK 和 Move 合约提供的预览功能；walrus store 没有池标志。请参阅 walrus-blob-lifecycle。
6. 怪罪客户端之前，先检查 walrus health --committee。 时好时坏的上传失败通常是由存储节点无法访问导致的。
7. 生成 Shell 补全。 运行 walrus completion bash|zsh|fish，并将输出放入相应的补全目录。

常见错误

• 在 epoch 即将结束时使用 --epochs 1 存储。 Blob 会在其结束 epoch 开始时过期，因此可能几乎立即过期。请使用较大的 epoch 数。
• 以为删除会让数据无法访问。 删除操作只会从当前和未来的存储节点中移除分片。如果同一 Blob 还有其他副本（由他人上传），数据仍可访问。所有 Blob 都是公开的。
• 在脚本中忘记使用 --json。 默认输出为人类可读格式。自动化场景请使用 --json 或 walrus json 来生成可解析的输出。
• 未配置就运行 walrus。 CLI 需要 client_config.yaml。请下载该文件，或使用 --config 指定文件。没有该文件时会报缺少配置的错误。
• 没有 SUI/WAL 代币。 写操作需要 SUI 支付 Gas 费，并需要 WAL 支付存储费用。在 Testnet 上，请从 Sui 水龙头申请 SUI（sui client faucet），再通过 walrus get-wal 将其兑换为 WAL。在 Mainnet 上，请通过交易所获取 WAL，或通过转账获取；get-wal 在那里不可用。
• 出现 Cannot find gas coin for signer address 错误。 钱包中没有 SUI。请向该地址充值 SUI，用于支付 Gas 费。
• 使用 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... 十六进制）。请查看相应命令的 --help。
• Testnet 上的 Blob 很快消失。 Testnet 的 epoch 时长比 Mainnet 短（14 天）。如果存储时指定的 epoch 数较少，Blob 会比预期更快过期。请使用 walrus info 查看当前 epoch 时长。