Site Builder Reference

This reference page provides details on site-builder configuration and CLI commands.

Configuration file

The site-builder tool requires a configuration file sites-config.yaml in one of the following default locations:

• The current directory
• $XDG_CONFIG_HOME/walrus/
• ~/.config/walrus/
• ~/.walrus/

The configuration file specifies which Sui package to use, which wallet to use, the gas budget, and other operational details. The following is an example sites-config.yaml:

contexts:
  testnet:
    # module: site
    # portal: wal.app
    package: 0xf99aee9f21493e1590e7e5a9aea6f343a1f381031a04a732724871fc294be799
    staking_object: 0xbe46180321c30aab2f8b3501e24048377287fa708018a5b7c2792b35fe339ee3
    general:
        wallet_env: testnet
        walrus_context: testnet # Assumes a Walrus CLI setup with a multi-config containing the "testnet" context.
        walrus_package: 0xd84704c17fc870b8764832c535aa6b11f21a95cd6f5bb38a9b07d2cf42220c66
        # wallet_address: 0x1234...
        # rpc_url: https://fullnode.testnet.sui.io:443
        # wallet: /path/to/.sui/sui_config/client.yaml
        # walrus_binary: /path/to/walrus
        # walrus_config: /path/to/testnet/client_config.yaml
        # gas_budget: 500000000
  mainnet:
    # module: site
    # portal: wal.app
    package: 0x26eb7ee8688da02c5f671679524e379f0b837a12f1d1d799f255b7eea260ad27
    staking_object: 0x10b9d30c28448939ce6c4d6c6e0ffce4a7f8a4ada8248bdad09ef8b70e4a3904
    general:
        wallet_env: mainnet
        walrus_context: mainnet # Assumes a Walrus CLI setup with a multi-config containing the "mainnet" context.
        walrus_package: 0xfdc88f7d7cf30afab2f82e8380d11ee8f70efb90e863d1de8616fae1bb09ea77
        # wallet_address: 0x1234...
        # rpc_url: https://fullnode.mainnet.sui.io:443
        # wallet: /path/to/.sui/sui_config/client.yaml
        # walrus_binary: /path/to/walrus
        # walrus_config: /path/to/mainnet/client_config.yaml
        # gas_budget: 500000000

default_context: mainnet

site-builder CLI commands

info

Add --help to any command for full details: site-builder --help or site-builder deploy --help.

deploy

Publishes a new site or updates an existing one. This is the recommended command for all publishing and update workflows.

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

How does deploy determine whether to publish or update a site?

If an object ID from --object-id <OBJECT_ID> or the object_id field in ws-resources.json is provided, the site is updated. When updating an existing site, your configured wallet must own the corresponding Walrus Site object.

If no ID is found, deploy publishes a new site. The new site's object_id is automatically written to ws-resources.json for use in future updates.

Flag	Description
--epochs <EPOCHS>	Required; Number of epochs to store the site. Use max for the maximum allowed duration. See the Walrus network release schedule.
--object-id <OBJECT_ID>	The object ID of an existing site to update.
--list-directory	Generates an index page for browsing uploaded files. Useful when deploying raw files without an index.html.

Migrating from publish and update

Recommended

Pass your existing site's object ID with --object-id on the first run:

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

The object ID is automatically saved to ws-resources.json. Subsequent deployments no longer need the flag:

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

Manual

Manually add the object_id field to ws-resources.json in your site's root directory:

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

Then deploy normally:

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

convert

Converts a Walrus Site object ID from hex format to Base36. Use this to find the subdomain where a site is accessible.

site-builder convert <OBJECT_ID>

sitemap

Lists all resources that make up the Walrus Site at the given object ID.

site-builder sitemap --id <OBJECT_ID>

list-directory

Generates the index.html that would be created by running deploy with --list-directory, without actually deploying. Use this to preview the directory index before publishing.

site-builder list-directory <BUILD_DIRECTORY>

update-resource

Adds or replaces a single resource in an existing site.

site-builder update-resource --id <OBJECT_ID> <RESOURCE_PATH>

destroy

Permanently destroys the a site's object.

warning

This action is irreversible. Ensure you no longer need the site before running this command.

site-builder destroy --id <OBJECT_ID>

Legacy commands

The following commands are still supported but superseded by deploy. Migrate to deploy for a simpler and more reliable experience.

publish

Publishes a new site from a directory.

site-builder publish --epochs <EPOCHS> <BUILD_DIRECTORY>

Respects routing and header instructions in ws-resources.json. See specifying headers and routing.

update

Updates an existing site. Requires the Sui object ID of the site to update. The configured wallet must own the site object.

site-builder update --epochs <EPOCHS> --object <OBJECT_ID> <BUILD_DIRECTORY>