Walrus CLI

Walrus CLI

Source constraint: All information in this skill is sourced from the Walrus client documentation. When extending this skill, only pull from these sources.

The walrus CLI is the primary command-line tool for interacting with Walrus. It supports storing and reading blobs, checking blob status, managing blob lifecycle (extend, delete, burn, share), and working with quilts. All commands support JSON output for scripting.

All patterns in this skill are derived from:

• 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

If unsure about any CLI command, fetch the relevant page before answering.

Related skills

Skill Content

Installation

Install with suiup:

curl -sSfL https://raw.githubusercontent.com/Mystenlabs/suiup/main/install.sh | sh
suiup install sui
suiup install walrus

Update to the latest version:

suiup update walrus

Switch to a specific network version:

# Correct syntax: walrus@<network>
suiup install walrus@mainnet
suiup install walrus@testnet

Verify with walrus --help. Each subcommand also supports --help. If you get spawn walrus ENOENT or command not found, the binary is not in your PATH. Re-run the suiup installer or add ~/.suiup/bin to your PATH.

Configuration

The CLI reads client_config.yaml from the current directory, $XDG_CONFIG_HOME/walrus/, ~/.config/walrus/, or ~/.walrus/. Download the latest config:

curl --create-dirs https://docs.wal.app/setup/client_config.yaml \
  -o ~/.config/walrus/client_config.yaml

Use --config <PATH> to specify a custom config location. Use --wallet <PATH> for a non-standard Sui wallet config. Use --context <NAME> to switch between multiple contexts in the config.

Storing blobs

# 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 lifetime options

A blob expires at the beginning of its end epoch. Storing with --epochs 1 right before an epoch change means near-immediate expiration.

Blob permanence

Automatic optimizations

• If a permanent blob with the same content and sufficient lifetime exists, the client skips re-upload (override with --force).
• If a suitable storage resource exists in your wallet, it is reused instead of buying a new one.
• If the blob is already certified but deletable or has insufficient lifetime, the client skips sending encoded data and just collects the certificate.

Reading blobs

# 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

# Read a blob to stdout
walrus read <BLOB_ID>

# Read a blob to a file
walrus read <BLOB_ID> --out output.dat

Consistency checks

Starting with v1.37, the CLI uses a performant consistency check by default. Use --strict-consistency-check for the full check or --skip-consistency-check if the writer is known and trusted.

JSON mode

All commands are available in JSON mode for scripting:

# 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 mode uses camelCase instead of kebab-case for option names. It also accepts input from stdin. Output is always JSON-formatted, suitable for piping to jq.

Use --json with any standard command to get JSON output without full JSON mode:

walrus store myfile.png --epochs 5 --json

Querying system info

# Show current epoch, pricing, and network parameters
walrus info

# Show with JSON output
walrus info --json

walrus info shows the current epoch number, epoch duration, price per storage unit, write fee, and maximum epochs ahead. Use this to verify pricing before large uploads.

Switching between testnet and mainnet

The config file supports multiple contexts. Switch with:

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

Contexts are defined in client_config.yaml under the contexts: key. Each context specifies system_object, staking_object, n_shards, and rpc_urls.

Contract parameters

These are the current Walrus contract parameters for each network:

These values are also available in the default client_config.yaml and via walrus info --json.

Logging

# 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

Use --gas-budget <MIST> to set the maximum SUI the command can spend. If omitted, the gas budget is estimated automatically.

Rules

1. Always specify blob lifetime. The --epochs argument is mandatory for walrus store. There is no default.
2. All blobs are public. Encrypt sensitive data before storing. See the walrus-data-security skill.
3. Use JSON mode for automation. The walrus json command and --json flag produce machine-parseable output for CI/CD pipelines and scripts.
4. Blob ID is not object ID. Blob ID identifies content. Sui object ID identifies the on-chain object. Some commands take one, some take the other. Check --help for each command.
5. Generate shell completions. Run walrus completion bash|zsh|fish and place the output in the appropriate completions directory.

Common mistakes

• Storing with --epochs 1 near an epoch boundary. The blob expires at the beginning of its end epoch, which could be almost immediately. Use a generous epoch count.
• Expecting delete to make data unavailable. Delete only removes slivers from current and future storage nodes. If another copy of the same blob exists (uploaded by someone else), the data remains accessible. All blobs are public.
• Forgetting --json in scripts. Human-readable output is the default. Use --json or walrus json for parseable output in automation.
• Running walrus without configuration. The CLI needs client_config.yaml. Download it or specify with --config. Without it, you get an error about missing configuration.
• Not having SUI/WAL tokens. Write operations require SUI for gas and WAL for storage. On testnet, request tokens from the Sui faucet (sui client faucet) and the WAL faucet. On mainnet, acquire SUI and WAL through exchanges.
• Cannot find gas coin for signer address error. The wallet has no SUI. Fund the address with SUI for gas fees.
• Using suiup switch walrus 1.48.1 (wrong syntax). The correct syntax is suiup install walrus@mainnet or suiup install walrus@testnet. Version numbers are not used directly.
• Confusing blob ID with Sui object ID. Some commands take --blob-id (content hash, URL-safe base64), others take --blob-obj-id or --object-id (Sui object, 0x... hex). Check --help for the specific command.
• Testnet blobs disappearing quickly. Testnet epoch duration is shorter than mainnet (14 days). If you store with low epochs, blobs expire faster than expected. Use walrus info to check current epoch duration.