Output and Errors

The CLI output envelope, metadata fields, table-vs-JSON behavior, and canonical error taxonomy.

Output Envelope

Successful and failed operations are normalized into the same top-level shape:

{
  "ok": true,
  "data": {},
  "meta": {
    "command": "peer quote",
    "env": "production",
    "chain": "base",
    "timestamp": "2026-03-27T00:00:00.000Z",
    "duration_ms": 123
  }
}

Error shape:

{
  "ok": false,
  "error": {
    "code": "AUTH_REQUIRED",
    "category": "auth",
    "message": "A signer is required for this operation.",
    "retryable": false,
    "suggestion": "Provide a wallet via --private-key, PEER_PRIVATE_KEY, or --wallet-path."
  },
  "meta": {
    "command": "peer transfer",
    "env": "production",
    "chain": "base",
    "timestamp": "2026-03-27T00:00:00.000Z",
    "duration_ms": 87
  }
}

Metadata

The meta block is useful for logging and traceability.

Field	Meaning
`command`	Human-readable command path
`env`	Active runtime environment
`chain`	Currently normalized chain label
`timestamp`	UTC timestamp
`duration_ms`	End-to-end execution time

Table Output

--format table is a human convenience mode.

Important constraints:

It only applies to successful CLI output.
Errors remain JSON-shaped.
Nested objects are truncated for readability.
MCP always returns structured JSON, not tables.

Canonical Error Codes

The error catalog currently exposes these stable codes:

Code	Meaning
`VALIDATION_ERROR`	Bad or incomplete user input
`AUTH_REQUIRED`	Missing signer or required auth context
`CONFIG_ERROR`	Missing or invalid configuration
`API_ERROR`	Upstream HTTP/API failure
`NETWORK_ERROR`	Connectivity or transport failure
`TIMEOUT`	Request or operation timed out
`RATE_LIMITED`	Upstream throttling
`CONTRACT_ERROR`	Revert, ABI mismatch, or contract-level failure
`UNSUPPORTED_OPERATION`	Action is not supported in the current runtime or deployment
`INTERNAL_ERROR`	Unexpected local failure

Retry Semantics

Errors carry retryable explicitly.

Use it as a signal, but not as a blind rule. A retryable network error still needs context:

transient provider outage: retry may help
missing auth: retry will not help
rate limited: backoff first
contract revert: inspect state before any retry

Debug Logging

Enable extra diagnostics with:

peer --debug <command>

Debug logs go to stderr and should not be treated as the canonical machine result.