Site Builder Commands

This section describes in more detail the commands available through the site-builder.

Add the --help flag to any command to get further details for the whole CLI (site-builder --help) or individual commands (for example, site-builder update --help).

deploy

The deploy command is the primary command for managing your Walrus Site. The command takes a directory as input and creates a new Walrus Site from the resources contained within, and on subsequent calls, it updates the existing site.

Behavior

The deploy command determines whether to publish a new site or update an existing one by looking for a site object ID. It finds the ID with the following priority:

• An ID provided directly through the --object-id <OBJECT_ID> command-line flag.

• An ID found in the object_id field of the ws-resources.json file.

• If no ID is found by either method, deploy publishes a new site.

When a new site is published, its object_id is automatically saved back to ws-resources.json, streamlining future updates.

The wallet you are using to update an existing site must be the owner of the Walrus Site object to be able to update it.

Usage

As shown by the command's help information, the typical usage is:

$ site-builder deploy [OPTIONS] --epochs <EPOCHS> <DIRECTORY>

The --epochs flag specifies the number of epochs for which the site's resources are stored on Walrus (for example, 10). You can also use max to store for the maximum allowed duration. It is required and its value must be greater than 0.

On Walrus Testnet, the epoch duration is 1 day. On Walrus Mainnet, the epoch duration is 14 days. Therefore, consider storing your site for a large number of epochs if you want to make it available for the following months. The maximum duration is set to 53 epochs.

If you are just uploading raw files without an index.html, you might want to use the --list-directory flag, which automatically creates an index page to browse the files.

Migrating from publish/update

If you have a site that was previously managed with the publish and update commands, you can easily switch to the deploy command using one of the following methods:

Recommended: Use the --object-id CLI flag

Simply run the deploy command and provide your existing Site's Object ID through the --object-id flag:

$ site-builder deploy --object-id <YOUR_EXISTING_SITE_ID> --epochs <NUMBER> ./path/to/your/site

On success, this updates your site and automatically creates (or updates if already existing) a ws-resources.json file with the site's object ID saved in the object_id field. Future deployments then use:

$ site-builder deploy --epochs <NUMBER> ./path/to/your/site

Manual ws-resources.json setup

You can manually create or update a ws-resources.json file in your site's root directory and add the object_id field with your existing site's object ID.

{
  "object_id": "0x123...abc"
}

Then, you can run:

$ site-builder deploy --epochs <NUMBER> ./path/to/your/site

convert

The convert command converts an object ID in hex format to the equivalent Base36 format. This command is useful if you have the Sui object ID of a Walrus Site and want to know the subdomain where you can browse it.

site-map

The sitemap command shows the resources that compose the Walrus Site at the given object ID.

list-directory

With list-directory, you can obtain the index.html file that would be generated by running publish or update with the --list-directory flag. This is useful to see how the index page would look like before publishing it, and possibly editing to make it look nicer.

destroy

Destroys both blockchain objects and Walrus assets of a site with the given object id.

update-resource

Adds or updates a single resource in a site, eventually replacing any pre-existing ones.

publish

The deploy command is the new standard for publishing and updating your Walrus Sites. Users are encouraged to migrate to the deploy command for a simpler and more robust experience.

The publish command publishes a new site on Sui. The command takes a directory as input and creates a new Walrus Site from the resources contained within.

The --epochs flag allows you to specify for how long the site data is stored on Walrus.

The publish command also respects the instructions in the ws-resources.json configuration file. To know more, see the section on specifying headers and routing.

update

The deploy command is the new standard for publishing and updating your Walrus Sites. Users are encouraged to migrate to the deploy command for a simpler and more robust experience.

This command is the equivalent of publish, but for updating an existing site. It takes the same arguments, with the addition of the Sui object ID of the site to update.

The wallet you are using to call update must be the owner of the Walrus Site object to be able to update it.