Output contract
How tardigrada talks on stdout/stderr — the machine-readable surface --json and scripts rely on. Verbs and flags: CLI (generated from --help).
Streams
- stdout carries the payload: the bare
age1…recipient forshow/init/import, the keyfile secret line for bareexport, the resolved backend (keyring/file) forbackend, JSON under--json. - stderr carries context notes (
tardigrada: …) and errors — including backend fallback notes (no session keyring reachable (…) — using the identity file). Under--jsonnotes are silenced so stderr stays clean for piping; errors still emit{"error": "…"}on stderr.
--json shapes
init, show, import, export --out share one envelope:
{"backend":"keyring","recipient":"age1…","source":"system keyring (entry tardigrada/age-identity)"}backendis the resolved source kind —"keyring"or"file".sourcedescribes it — a keyfile path or the store entry.initadds"created": true|false; a keyring init that adopted an existing keyfile adds"migrated_from": "<keyfile path>".importadds"imported_from": "<keyfile path>"and, when it replaces a different stored identity,"replaced_recipient";export --outreports the same field when the destination held a different identity.backendemits{"backend","mode","pinned","source"}:backend= resolved kind,mode= the configuredTARDIGRADA_IDENTITY_BACKEND(keyring/auto/file),pinned= an explicit--identity-file/TARDIGRADA_IDENTITY_FILE(or legacyCUORA_/ARCA_IDENTITY_FILE) pin is in effect.manifestis always JSON (flag or not): verbs, globals, env vars, backends, cuora interop note.
Bare export --json is refused (export --json needs --out PATH) — a secret inside a JSON envelope invites accidental logging. Use --out or bare export for the pipeable form.
Warnings
Routine context notes are suppressed under --json, but warnings are not — conditions that changed what the verb did emit {"warning": "<message>"} on stderr (plain mode: tardigrada: warning: <message>). Watch for: backend fallbacks (auto → keyfile), an env pin overriding backend=keyring, an unrecognized TARDIGRADA_IDENTITY_BACKEND, and identity replacements.
Errors
Any failure exits 1:
- plain mode:
tardigrada: error: <message>on stderr --json:{"error": "<message>"}on stderr
Missing identity is actionable: no identity at <source> — run tardigrada init first. A keyring backend with no reachable session store fails closed: identity backend unavailable: backend=keyring: … — set TARDIGRADA_IDENTITY_BACKEND=auto|file for headless/CI. clap usage errors keep clap's own exit codes (2 for parse failures).