JSON output

Commands that support --json return structured, versioned output for scripts and integrations. Use it whenever a program reads Istok’s output; the human-readable format is for people and may change.

istok task list --json
istok project show --json
istok search "order not found" --json

Each command’s --help shows whether it supports --json.

Schema versions

Every result has a top-level schema_version. Parts of Istok version their contracts independently:

Check schema_version before relying on a structure.

Nested payloads

Search and graph results carry their own contract inside the outer envelope, so the two can evolve independently:

CLI or MCP envelope   schema_version: "1"
  └── payload         contract: istok.retrieval.v1   (search)
                      contract: istok.graph.v1       (graph symbol, neighbors, path)

istok knowledge export --format json writes a file with its own contract, istok.knowledge-export.v1. The Markdown export carries the same identifier in its metadata header.

Run results

Run results, in the CLI and in MCP, use version "2". They include the run identity, the project-scoped task identity, revision, lease state, executions, validation evidence, artifacts, and the terminal state.

Task identity

Task results include both the canonical task UUID and the project-scoped number used by commands like istok task show 12. Keep the UUID when you need a stable reference, for example for a knowledge provenance source.

Revisions

Results include the revision that compare-and-swap operations need. Read the object, keep its revision, and pass it as the expected revision (--expected-revision in the CLI, expected_revision in structured inputs). If the object changed in the meantime, the operation fails instead of overwriting newer state; read again and decide whether to retry.

Empty collections

Empty collections are [], never null. This applies to task, run, search, graph, and MCP result sets, so you can always treat a collection as an array.

Errors

JSON operations return structured, versioned errors with stable error codes. Branch on the code, not on the message text.

Non-interactive use

JSON mode never waits for an interactive confirmation. Destructive commands that normally ask need the explicit flag:

istok project delete --json --yes

A typical script

read structured state      istok task show 12 --json
check schema_version
keep IDs and revision
perform the operation      with --expected-revision
read the structured result