Using the Walrus Client

Use the command-line interface (CLI) to interact with the Walrus client. The CLI is available through installing the walrus binary. See the getting started documentation for prerequisites, installation, and configuration.

Detailed usage information including a full list of available commands can be viewed using:

$ walrus --help

Each subcommand of walrus can also be called with --help to print its specific arguments and their meaning.

If you have multiple contexts in your configuration file, you can specify the context for each command using the --context option. You can generate a bash, zsh, or fish completion script with walrus completion and place it in an appropriate directory like ~/.local/share/bash-completion/completions.

View Walrus system information

Information about the Walrus system is available through the walrus info command. It provides an overview of current system parameters, such as the current epoch, the number of storage nodes and shards in the system, the maximum blob size, and the current cost in WAL for storing blobs:

$ walrus info

The console responds:

Walrus system information

Epochs and storage duration
Current epoch: 1
Start time: 2025-03-25 15:00:24.408 UTC
End time: 2025-04-08 15:00:24.408 UTC
Epoch duration: 14days
Blobs can be stored for at most 53 epochs in the future.

Storage nodes
Number of storage nodes: 103
Number of shards: 1000

Blob size
Maximum blob size: 13.6 GiB (14,599,533,452 B)
Storage unit: 1.00 MiB

Storage prices per epoch
(Conversion rate: 1 WAL = 1,000,000,000 FROST)
Price per encoded storage unit: 0.0001 WAL
Additional price for each write: 20,000 FROST

...

You can view additional information with various subcommands, including encoding parameters and sizes, BFT system information, and details about storage nodes in the current committee and next committee, if already selected. This information includes node IDs, stake distribution, and shard allocation. Run walrus info --help for a complete list of available subcommands.

The health of storage nodes can be checked with the walrus health command. This command takes different options to select nodes to check, for example, walrus health --committee checks the status of all current committee members.

Store blobs

All blobs stored in Walrus are public and discoverable by all. To store sensitive data, use Seal or Nautilus to encrypt the data before storing it on Walrus.

Store blobs on Walrus with the following command:

$ walrus store <FILES> --epochs <EPOCHS>

After you upload a blob to Walrus, it has 2 identifiers:

Blob ID: oehkoh0352bRGNPjuwcy0nye3OLKT649K62imdNAlXg
Sui object ID: 0x1c086e216c4d35bf4c1ea493aea701260ffa5b0070622b17271e4495a030fe83

• Blob ID: A way to reference the blob on Walrus. The system generates the blob ID based on the blob's contents, meaning any file you upload to the network twice results in the same blob ID.

• Sui Object ID: The blob's corresponding newly created Sui object identifier, as the system binds all blobs to one or more Sui objects.

You use blob IDs to read blob data, while you use Sui object IDs to make modifications to the blob's metadata, such as its storage duration. You might also use them to read blob data.

You can store a single file or multiple files, separated by spaces. Notably, this is compatible with glob patterns; for example, walrus store *.png --epochs <EPOCHS> stores all PNG files in the current directory.

Blob lifetimes

A mandatory CLI argument must be set to specify the lifetime for the blob. There are currently 3 methods of setting a blob's lifetime:

1. The --epochs <EPOCHS> option indicates the number of epochs the blob should be stored for. There is an upper limit on the number of epochs a blob can be stored for, which is 53 and corresponds to 2 years. In addition to a positive integer, you can also use --epochs max to store the blob for the maximum number of epochs. The end epoch is defined as the current epoch plus the specified number of epochs.

2. The --earliest-expiry-time <EARLIEST_EXPIRY_TIME> option takes a date in either RFC3339 format (for example, 2024-03-20T15:00:00Z) or a more relaxed format (for example, 2024-03-20 15:00:00). It ensures the blob expires after the specified date if possible.

3. The --end-epoch <END_EPOCH> option takes a specific end epoch for the blob.

A blob expires at the beginning of its end epoch. For example, a blob with end epoch 314 becomes unavailable at the beginning of epoch 314. One consequence of this is that when storing a blob with --epochs 1 immediately before an epoch change, it expires and becomes unavailable almost immediately. Blobs can be extended only if they have not expired.

Blob permanence

You can specify whether a newly stored blob is deletable or permanent through the --deletable and --permanent option, respectively:

• A permanent blob remains available until its expiry epoch. Not even the uploader can delete it beforehand.

• In contrast, a deletable blob can be deleted at any point during its lifetime by the owner of the corresponding Sui object. See the deletable blobs for more details.

Newly stored blobs are deletable by default.

Automatic optimizations

When storing a blob, the client performs a number of automatic optimizations, including the following:

• If the blob is already stored as a permanent blob on Walrus for a sufficient number of epochs, the command does not store it again. This behavior can be overwritten with the --force CLI option, which stores the blob again and creates a fresh Sui object belonging to the wallet address.

• If the user's wallet has a storage resource of suitable size and duration, it is used instead of requiring that the user buy a new one.

• If the blob is already certified on Walrus but it is a deletable blob or it is not stored for a sufficient number of epochs, the command skips sending encoded blob data to the storage nodes and just collects the availability certificate.

Use a Walrus upload relay

A Walrus upload relay is a third party service that can help clients with limited bandwidth and networking capabilities such as a browser, for example, in storing blobs on Walrus.

Asset management on-chain still happens on the client. The upload relay just takes the unencoded blob, encodes it, and sends the slivers to the storage nodes, before returning the certificate. See in-depth details in the Walrus upload relay documentation.

When storing blobs with the walrus store command, and also when storing quilts, you can use the --upload-relay flag with a URL to specify an upload relay server be used by the CLI.

The Walrus upload relay functionality is only available in the Walrus CLI version v1.29 or higher.

The upload relay is a third party service that might require a fee or tip. This tip might be a constant SUI amount per blob stored, or it might be dependent on the size of the blob being stored. The Walrus CLI shows you how much tip the upload relay requires and asks for confirmation before continuing.

View technical details on how the tip is computed and paid.

Query blob status

The status of a blob can be queried through one of the following commands:

$ walrus blob-status --blob-id <BLOB_ID>
$ walrus blob-status --file <FILE>

Each command returns output that indicates whether the specified blob is stored and its availability period. If you specify a file with the --file option, the CLI re-encodes the content of the file and derives the blob ID before checking the status.

When a blob is available, the blob-status command also returns the BlobCertified Sui event ID, which consists of a transaction ID and a sequence number in the events emitted by the transaction. The existence of this event certifies the availability of the blob.

Read blobs

Reading blobs from Walrus can be achieved using the following command:

$ walrus read <some blob ID>

By default, blob data is written to the standard output. The --out <OUT> CLI option can be used to specify an output file name. The --rpc-url <URL> can be used to specify a Sui RPC node to use instead of the currently configured RPC node set in the CLI configuration file or wallet configuration.

Check consistency

Walrus performs integrity and consistency checks to ensure that any data read from Walrus is what the writer intended, and that the writer encoded the blob correctly. See the data consistency documentation for further details.

Prior to v1.37, the Walrus CLI and aggregator always performed the strict consistency check. Starting with v1.37, the default is a more performant consistency check, which is sufficient for the majority of cases. The strict consistency check can be enabled through the flag --strict-consistency-check.

Consistency checks can be disabled completely with the flag --skip-consistency-check. This should only be used if the writer of the blob is known and trusted.

Extend the lifetime of a blob

Walrus blob lifetimes can be extended using the walrus extend --blob-obj-id <Sui object id> ... command as long as the blob is not expired. Both address owned blobs and shared blobs can have their lifetime extended. Shared blobs can be extended by anyone, but owned blobs can only be extended by their owner. When extending a shared blob, you need to supply the --shared flag to inform the command that the blob is shared.

The blob's object ID is needed in order to extend it. The blob ID is not needed. See walrus extend --help for more information on blob extension.

Reclaim space through deletable blobs

A blob that was set as deletable upon creation can be deleted before its expiry, but only by the owner of the Sui object corresponding to the blob. Deletable blobs are indicated as such in the Sui events that certify them, and should not be relied upon by others for availability.

Delete a blob with the command:

$ walrus delete --blob-id <BLOB_ID>

The delete command can also be invoked by specifying a --file <PATH> option to derive the blob ID from a file, or using --object-id <SUI_ID>. Before deleting a blob, the walrus delete command asks for confirmation unless the --yes option is specified.

The delete command reclaims the storage object associated with the deleted blob, which is re-used to store new blobs automatically. The delete operation provides flexibility around managing storage costs and re-using storage.

The delete operation has limited utility for privacy. It only deletes slivers from the current epoch storage nodes, and subsequent epoch storage nodes, if no other user has uploaded a copy of the same blob. If another copy of the same blob exists in Walrus, the delete operation does not make the blob unavailable for download, and walrus read invocations will still download it. After the deletion is finished, the CLI checks the updated status of the blob to see if it is still accessible in Walrus, unless the --no-status-check option was specified. However, even if the blob is not accessible, copies of the public blob might be cached or downloaded by users, and these copies are not deleted.

danger

All blobs stored in Walrus are public and discoverable by all. The delete command does not delete slivers if other copies of the blob are stored on Walrus, possibly by other users. It does not delete blobs from caches, slivers from past storage nodes, or copies that could have been made by users before the blob was deleted.

Shared blobs

Shared blobs are shared Sui objects wrapping standard Blob objects that can be funded and whose lifetime can be extended by anyone. See the shared blobs contracts for further details.

You can create a shared blob from an existing Blob object you own with the walrus share command:

$ walrus share --blob-obj-id <SUI_OBJ_ID>

The resulting shared blob can be directly funded by adding an --amount, or you can fund an existing shared blob with the walrus fund-shared-blob command. Additionally, you can immediately share a newly created blob by adding the --share option to the walrus store command.

Shared blobs can only contain permanent blobs and as such cannot be deleted before their expiry.

Learn more about blob extension.

Store blobs as a quilt

For efficiently storing large numbers of small blobs, Walrus provides the Quilt. It batches multiple blobs into a single storage unit, significantly reducing overhead and cost. You can find a more detailed overview of the feature Quilt.

You can interact with quilts using a dedicated set of walrus subcommands.

Blobs within a quilt are retrieved by a QuiltPatchId, not their standard BlobId. This ID is generated based on all blobs in the quilt, so a blob's QuiltPatchId changes if it's moved to a different quilt.

Standard blob operations like delete, extend, or share cannot target individual blobs inside a quilt; they must be applied to the entire quilt.

To store all files from one or more directories recursively, use the --paths flag. The filename of each file is used as its unique identifier within the quilt. Regular expressions are supported for uploading from multiple paths.

Like the regular store command, you can specify the storage duration using --epochs, --earliest-expiry-time, or --end-epoch.

$ walrus store-quilt --epochs <EPOCHS> --paths <path-to-directory-1> <path-to-directory-2> <path-to-blob>

You must ensure that all the identifiers are unique within a quilt, the operation fails otherwise. Identifiers are the unique names used to retrieve individual blobs from within the quilt.

To specify a list of blobs as JSON objects, use the --blobs flag. This gives you more control, allowing you to set a custom identifier and tags for each file. If identifier is null or omitted, the file's name is used instead.

$ walrus store-quilt \
    --blobs '{"path":"<path-to-blob-1>","identifier":"walrus","tags":{"color":"grey","size":"medium"}}' \
            '{"path":"<path-to_blob-2>","identifier":"seal","tags":{"color":"grey","size":"small"}}' \
    --epochs <EPOCHS>

Read blobs from a quilt

You can retrieve individual blobs from a quilt without downloading the entire quilt. The read-quilt command allows you to query for specific blobs by their identifier, tags, or unique blob ID.

To read blobs by their identifiers, use the --identifiers flag:

$ walrus read-quilt --out <download dir> \
    --quilt-id 057MX9PAaUIQLliItM_khR_cp5jPHzJWf-CuJr1z1ik --identifiers walrus.jpg another-walrus.jpg

Blobs within a quilt can be accessed and filtered based on their tags. For instance, if you have a collection of animal images stored in a quilt, each labeled with a species tag such as species=cat, you can download all images labeled as cats with the following command:

$ walrus read-quilt --out <download dir> \
    --quilt-id 057MX9PAaUIQLliItM_khR_cp5jPHzJWf-CuJr1z1ik --tag species cat

You can also read a blob using its QuiltPatchId, which can be retrieved using walrus list-patches-in-quilt:

$ walrus read-quilt --out <download dir> \
  --quilt-patch-ids GRSuRSQ_hLYR9nyo7mlBlS7MLQVSSXRrfPVOxF6n6XcBuQG8AQ \
  GRSuRSQ_hLYR9nyo7mlBlS7MLQVSSXRrfPVOxF6n6XcBwgHHAQ

To see all the patches contained within a quilt, along with their identifiers and QuiltPatchIds, use the list-patches-in-quilt command.

$ walrus list-patches-in-quilt 057MX9PAaUIQLliItM_khR_cp5jPHzJWf-CuJr1z1ik

Use Sui object and blob ID utilities

The command walrus blob-id <FILE> can be used to derive the blob ID of any file. The blob ID is a commitment to the file, and any blob with the same ID decodes to the same content. The blob ID is a 256 bit number and represented on some Sui explorers as a decimal large number. The command walrus convert-blob-id <BLOB_ID_DECIMAL> can be used to convert it to a base64 URL to be used by the command line tools and other APIs.

The walrus list-blobs command lists all non-expired Sui objects that the current account owns, including their blob ID, object ID, and metadata about expiration and deletable status. The option --include-expired also lists expired Sui objects.

The Sui storage cost associated with Sui objects can be reclaimed by burning the Sui object. This does not lead to the Walrus blob being deleted, but means that operations such as extending its lifetime, deleting it, or modifying attributes are not available. The walrus burn-blobs --object-ids <SUI_OBJ_IDS> command can be used to burn a specific list of Sui object IDs. The --all flag burns the Sui objects for all blobs under the user account, and --all-expired burns all expired blobs under the user account.

Manage blob attributes

Walrus allows a set of key-value attribute pairs to be associated with a Sui object. While the keys and their values can be arbitrary strings to accommodate any needs, specific keys are converted to HTTP headers when serving blobs through aggregators. Each aggregator can decide which headers it allows through the --allowed-headers CLI option. The defaults can be viewed through walrus aggregator --help.

The following command sets attributes key1 and key2 to values value1 and value2, respectively. The command walrus get-blob-attribute <SUI_OBJ_ID> returns all attributes associated with a blob ID.

$ walrus set-blob-attribute <SUI_OBJ_ID> --attr "key1" "value1" --attr "key2" "value2"

The following command deletes the attributes with keys listed, separated by commas or spaces. All attributes of a Sui object can be deleted by the command walrus remove-blob-attribute <SUI_OBJ_ID>.

$ walrus remove-blob-attribute-fields <SUI_OBJ_ID> --keys "key1,key2"

Attributes are associated with Sui object IDs rather than the blob themselves on Walrus. This means that the gas for storage is reclaimed by deleting attributes and that the same blob contents can have different attributes for different Sui objects for the same blob ID.

Change the default configuration

Use the --config option to specify a custom path to the configuration location.

The --wallet <WALLET> argument can be used to specify a non-standard Sui wallet configuration file and a --gas-budget <GAS_BUDGET> argument can be used to change the maximum amount of Sui (in MIST) that the command is allowed to use.

Configure logging and metrics

The walrus CLI allows for multiple levels of logging, which can be turned on through an environment variable:

$ RUST_LOG=walrus=trace walrus info

By default info level logs are enabled, but debug and trace can give a more in depth understanding of what a command does or how it fails.