JSON mode exposes every Walrus client command and simplifies programmatic access to the [CLI](/docs/walrus-client/walrus-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:

```sh
$ 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:

```sh
$ 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](/docs/walrus-client/walrus-cli#configuration): 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:

```sh
$ 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:

```json
{
  "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](/docs/http-api/storing-blobs). For example, the following command stores a file and extracts the blob ID of a newly created blob:

```sh
$ 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:

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

Two error cases are worth distinguishing:

1. Invalid input, such as malformed JSON or an unknown key, fails before the command runs and reports a parse error on stderr.
2. 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.