sumvin command accepts --json. Instead of formatted text, it prints exactly one JSON document to standard output and nothing else — no progress messages, no partial output, nothing on standard error to interleave with it.
The envelope
Success:data is present only when ok is true; error is present only when ok is false. error’s fields are always present — null rather than omitted — so a script never has to check for a missing key before reading one.
ok is not the verdict
ok means the command completed — it reached your account, got an answer, and didn’t crash. It does not mean “the answer is yes.”
The clearest example: verifying a Stamped Mandate that turns out to be invalid is a completely successful run whose answer is no.
exit_code (or the command’s own verdict field, such as data.valid) for check-style commands. Never branch on ok alone.
Exit codes
Every other command uses only
0 and 1. A bare sumvin kyc status or sumvin sigil show reports state rather than judging it, so even an unwelcome result — a rejected verification, a failed Sigil — is still a successful read and exits 0.
_links vs next
_links— what can be done to this result, translated into a runnablesumvincommand. Reflects what’s actually available right now: it only lists actions your account can currently take.next— what the CLI suggests you do now. Appears on errors (pointing at how to fix the problem) and on results with an obvious follow-up.
command in either field is always a complete, runnable command with real arguments filled in — never a placeholder.
Discovery
Runningsumvin --json with no command returns the entire command surface as one catalog: every command, its flags, its arguments, and what each exit code means. An agent can learn the whole CLI from a single call, without reading text written for humans.
sumvin <command> --help --json returns just that command’s descriptor the same way.
The stdout/stderr guarantee
Under--json, nothing the CLI writes for a human — error lines, progress narration, --debug diagnostics — reaches standard error. Everything is either a field of the envelope or suppressed entirely. sumvin <command> --json 2>&1 is always safe to parse.
Long-running commands (sumvin kyc status --wait, sumvin keys add-to-safe) print nothing at all until they finish. Silence under --json is expected, not a hang.
An env var, if you’d rather not repeat the flag
--json on a single call always wins over the environment variable.
Credential safety
--json never emits a signing key or an access token. sumvin login --json returns the token’s id and expiry, never the token; sumvin whoami --json returns token metadata, never the token; sumvin keys add-to-safe --json returns the registered address, never the key.