JSON Mode

JSON mode exposes every Walrus client command and simplifies programmatic access to the CLI. You specify the command and all of its options as a single JSON string, and the CLI prints JSON-formatted results to stdout.

Command structure

Pass a single JSON object to walrus json. The object contains the global options (such as config, context, wallet, and gasBudget) at the root level, plus a command object that holds exactly one command (for example, store, read, or blobStatus) with its options.

All commands, options, and default values are the same as those in the standard CLI mode, except that the JSON keys use camelCase instead of kebab-case: the blob-status command becomes blobStatus, and the --strict-consistency-check flag becomes strictConsistencyCheck. Run walrus --help for the full list of commands, and walrus <COMMAND> --help for the options of each command. The json command ignores any other command-line flags, so specify every option inside the JSON string.

To store two files for 5 epochs, run the following command:

$ walrus json \
    '{
        "config": "path/to/client_config.yaml",
        "command": {
            "store": {
                "files": ["README.md", "LICENSE"],
                "epochs": 5
            }
        }
    }'

To read a blob using the blob ID and write it to a file:

$ walrus json \
    '{
        "config": "path/to/client_config.yaml",
        "command": {
            "read": {
                "blobId": "4BKcDC0Ih5RJ8R0tFMz3MZVNZV8b2goT6_JiEEwNHQo",
                "out": "blob.bin"
            }
        }
    }'

If you omit config, the client searches for client_config.yaml (or client_config.yml) in the default locations: the current directory, $XDG_CONFIG_HOME/walrus/, ~/.config/walrus/, and ~/.walrus/. If the specified path is invalid, the command fails with an error. JSON mode uses no separate authentication: commands that create or modify Sui objects sign transactions with the configured Sui wallet, which you can override with the wallet key.

Pass input through stdin

When you run walrus json without an argument, the command reads the JSON string from stdin. This lets you pipe input from another program or a file:

$ echo '{
    "command": {
        "read": {
            "blobId": "4BKcDC0Ih5RJ8R0tFMz3MZVNZV8b2goT6_JiEEwNHQo",
            "out": "blob.bin"
        }
    }
}' | walrus json

Parse the output

On success, the command prints only JSON to stdout, with keys in camelCase. You can pipe the output to jq to extract relevant fields.

The read command without an out file returns the full blob content as a Base64-encoded string in the blob field:

{
  "blobId": "4BKcDC0Ih5RJ8R0tFMz3MZVNZV8b2goT6_JiEEwNHQo",
  "blob": "SGVsbG8sIFdhbHJ1cyE="
}

When you set out, the CLI writes the bytes to that file and omits the blob field from the JSON output. For large blobs, always set out: this keeps the JSON output small and avoids Base64 encoding the entire blob into memory.

The store command returns an array with one result per file. Each entry contains the path and a blobStoreResult object, which holds one of the variants newlyCreated, alreadyCertified, markedInvalid, or error. The variant contents match the store responses documented for the HTTP API. For example, the following command stores a file and extracts the blob ID of a newly created blob:

$ walrus json '{"command": {"store": {"files": ["README.md"], "epochs": 5}}}' \
    | jq -r '.[0].blobStoreResult.newlyCreated.blobObject.blobId'

To store many files in one batch, list them all in the files array. The CLI encodes and uploads them in a single run and reports a result for each file.

Handle errors

When a command fails, the CLI prints a human-readable error message to stderr and exits with a non-zero status code. JSON mode produces no JSON error object on stdout, so scripts should check the exit code first and parse stdout as JSON only when the command succeeds:

if output=$(walrus json "$request"); then
    echo "$output" | jq .
else
    echo "walrus command failed" >&2
fi

Two error cases are worth distinguishing:

Invalid input, such as malformed JSON or an unknown key, fails before the command runs and reports a parse error on stderr.
When storing multiple files, an individual file can fail while others succeed. The JSON output then contains an error variant for that file, with an errorMsg string and a failurePhase field indicating where the store failed.

Command structure​

Pass input through stdin​

Parse the output​

Handle errors​

Command structure

Pass input through stdin

Parse the output

Handle errors