JSON output

With --json, every opentide command prints exactly one JSON document on stdout, whether it succeeds, fails, or was called with a typo. Logs go to stderr, at WARNING and above (everything with --debug), so opentide --json validate 2>/dev/null is always parseable. This page describes the keys every document shares. Each command's own keys are on its page.

--json works before or after the command: opentide --json validate and opentide validate --json are the same. So do --no-color, --debug and --quiet. Options that take a value (--repo, --data, --proxy) stay before the command.

opentide validate --json
opentide --json info --platform sentinel

The document is indented when stdout is a terminal, and one compact line otherwise: in a pipe, a file, CI or a coding agent's shell. OPENTIDE_JSON_INDENT=0 prints one line everywhere and OPENTIDE_JSON_INDENT=2 indents by two spaces everywhere; any other value is ignored. Either way the document ends in exactly one newline, so opentide --json validate | jq .summary and json.loads read it the same.

The envelope

Every document carries these keys next to the command's own. Keys that existed before keep their name, type and meaning; new information is only ever added under new keys.

failure has five keys:

Failure codes

Exit codes are in Exit codes. opentide explain <code> prints the page for each failure code, as it does for findings (Diagnostic codes).

A usage error

A typo in a command, an option or a value exits 2 with the same document. Case and -/_ do not count against a suggestion: --type RULE suggests rule. Under --json nothing goes to stderr. In this tutorial repository, opentide --json info rulez exits 2:

opentide --json info rulez
opentide info rulez

{
  "error": "Unknown info section: rulez. Choose rules, threats, objectives, coverage, vocab.",
  "ok": false,
  "status": "failed",
  "message": "Unknown info section: rulez. Choose rules, threats, objectives, coverage, vocab.",
  "schema_version": 1,
  "command": "info",
  "duration_ms": "...",
  "exit_code": 2,
  "summary": {},
  "next_actions": [],
  "failure": {
    "code": "usage_invalid_choice",
    "message": "Unknown info section: rulez. Choose rules, threats, objectives, coverage, vocab.",
    "argument": "section",
    "suggestion": "rules",
    "crash_log": null
  }
}

Without --json the same error is one line on stderr, with the suggestion under it:

error: Unknown info section: rulez. Choose rules, threats, objectives, coverage, vocab.
  help: did you mean 'rules'?

An unexpected error

An exception no command handles is a bug in opentide. The run exits 1 and, under --json, still prints one document on stdout, with failure.code internal and failure.crash_log naming the log written for it. The message also goes to stderr, for the person reading the terminal. No command in a healthy repository prints this, so the sample is illustrative:

{
  "error": "RuntimeError: index exploded",
  "ok": false,
  "status": "failed",
  "message": "RuntimeError: index exploded",
  "command": "info",
  "exit_code": 1,
  "failure": {
    "code": "internal",
    "message": "RuntimeError: index exploded",
    "argument": null,
    "suggestion": null,
    "crash_log": "/home/me/.local/state/opentide/crash-20261023T110335102704Z-648.log"
  }
}

Where the log goes, what it holds and how to report the bug: Troubleshooting.

Output modes

opentide decides once per command who is reading. The first rule that matches wins:

OPENTIDE_OUTPUT=json is the same as passing --json to every command.

plain is human without colour or animation. Lines are never wrapped, so a long path stays on one line.

agent is plain, plus: a command that would prompt exits 2 at once with usage_needs_input and names the flags that answer the prompt, and a failure ends with tip: add --json for machine-readable output. Agents are detected from AI_AGENT first, then CLAUDECODE, CURSOR_AGENT, GEMINI_CLI, CODEX_CI, COPILOT_AGENT, COPILOT_CLI, OPENCODE, AMP_CURRENT_THREAD_ID, AUGMENT_AGENT and CLINE_ACTIVE. Detection changes presentation only: it never relaxes a confirmation, a --yes requirement or a strategy check.

Human output

Without --json, a command prints its warnings first (warning: … on stderr), then exactly one outcome line, then at most three next steps:

warning: Query validation reported warnings for sentinel
✓ Query validation passed for sentinel

validate and lint print each finding as a code frame before the outcome line, and their outcome line counts them (✗ 2 errors in 1 file · 3 objects checked · 0.9s). See Diagnostic codes.

A console that cannot encode ✓, ✗ or → (a Windows code page, PYTHONIOENCODING=ascii) gets ok, x and ->.

The command tree

opentide --json commands describes every command an agent can run, with its options, types, choices, defaults, environment variables and an example. See Command tree for agents.

Output schemas

Each command in opentide --json commands carries output_schema: the JSON Schema of the document it prints, generated from the typed result models in src/opentide/cli/ui/results/. It is a $ref into the $defs of the same document, anyOf the command's own result and CommandError, the document of a usage error. To check a document against its command's schema:

opentide --json commands > commands.json
jq '{"$defs": ."$defs"} + (.commands[] | select(.path == "validate") | .output_schema)' \
  commands.json > validate.schema.json
opentide --json validate > validate.json
check-jsonschema --schemafile validate.schema.json validate.json

The schemas allow keys they do not name, because new keys are added without notice. A key a schema names keeps its type.

Related

• Exit codes
• Global options