Handle Errors

Use a command's exit status as the primary success signal. When you request --json, parse stdout separately from stderr and allow for commands that still produce text.

This page describes @tetherto/wdk-cli@1.0.0-beta.7.

Handled Error Envelope

Errors that reach the WDK CLI command handler use this JSON shape:

{
  "error": "Wallet 'dev' is not unlocked.",
  "code": "WALLET_NOT_UNLOCKED",
  "suggestion": "Run: wdk wallet unlock --name dev"
}

--verbose adds error stacks. It does not enable general debug logging.

Exit Statuses

Do not treat the presence of stdout as success. Some handled failures emit a JSON object to stdout and exit with status 1.

JSON Output Contract

For most successful commands, --json emits one JSON value followed by a newline on stdout. Handled WDK CLI errors also emit one JSON object on stdout.

The current exceptions are:

--json changes output formatting; it does not make every command non-interactive or guarantee JSON-only stdout when a prompt opens. Wallet create, import, export, unlock, delete, default, rename, and change-passphrase flows can still request secret input. Set a non-empty WDK_PASSPHRASE only when you accept the environment-variable exposure described in Configuration. For a non-interactive import, combine wallet import --seed-stdin --json with WDK_PASSPHRASE; for passphrase rotation, --new-passphrase-stdin reads only the new value and WDK_PASSPHRASE supplies the current one.

Handle Output in a Shell Script

Capture the streams separately and inspect the exit status before parsing. This example requires jq:

#!/usr/bin/env bash
set -euo pipefail

stdout_file=$(mktemp)
stderr_file=$(mktemp)
trap 'rm -f "$stdout_file" "$stderr_file"' EXIT

if wdk get balance \
  --network ethereum \
  --wallet dev \
  --json >"$stdout_file" 2>"$stderr_file"; then
  jq . "$stdout_file"
elif jq -e 'type == "object" and has("code")' "$stdout_file" >/dev/null 2>&1; then
  jq . "$stdout_file" >&2
  exit 1
else
  cat "$stderr_file" >&2
  exit 1
fi

This pattern handles JSON command and argument errors while retaining a text fallback for output that is not part of the JSON contract.

Error Codes

The following names are defined by beta.7. A code can appear only on commands that reach the corresponding behavior.

The code set is not a closed protocol enum. The daemon and WDK dependencies can pass through additional codes. Beta.7 also recognizes and formats several dependency codes, including INSUFFICIENT_FUNDS, SERVER_ERROR, and TIMEOUT. Consumers should preserve unknown code strings instead of rejecting the response.

Common Recovery Paths

The table below describes beta.7. Use the Indexer provider configuration when upgrading an existing Indexer setup.

Partial Results

Some successful aggregate operations omit failed items:

• wdk get address --all skips networks that fail address derivation.
• wdk get balance --all skips networks that fail address or balance lookup.
• wdk get history without --token ignores failed token batch items and returns successful transfers.
• wdk swap and wdk bridge return successful route previews or executions with unsuccessful protocol quotes listed under skipped.

These commands can exit 0 with an incomplete aggregate or route result. If completeness matters, query each required network or token separately and inspect every skipped protocol before acting. A successful beta.7 cross-network swap preview is not proof that its selected provider received the destination network; do not execute that route shape.

Need Help?