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 on success the CLI prints JSON-formatted results to stdout.

How do I structure a JSON mode command?

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.

How do I 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

How do I 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.

How do I handle errors in JSON mode?

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.

Store result variants

The blobStoreResult object contains exactly one of 4 sibling variants: newlyCreated, alreadyCertified, markedInvalid, or error. Variant and field names use camelCase. Both markedInvalid and error mean the CLI did not store the blob. The error variant has the errorMsg and failurePhase strings plus an optional blob ID, which is absent when the failure occurs before the client knows the blob ID. A markedInvalid result points to a bug in the client or the storage nodes, or to more than a third of the storage nodes acting maliciously.

Select a configuration context

The context key is the JSON equivalent of the --context flag. Use it when your client configuration file defines multiple contexts and you want a command to run against a specific one. Set it to the name of a context in that file. The client loads the configuration from the config path, or from the default locations, using that context. Omit context to keep the context that the configuration file selects on its own.

How do I structure a JSON mode command?​

How do I pass input through stdin?​

How do I parse the output?​

How do I handle errors in JSON mode?​

Store result variants​

Select a configuration context​