JSON output

Istok commands that support --json return structured, versioned output intended for scripts, integrations, and automated workflows.

Use human-readable output when working interactively and JSON when another program needs to consume the result.

Enable JSON output

Add --json to a supported command:

istok task list --json

For example:

istok project show --json

or:

istok search "authentication timeout" --json

Use command help to check whether JSON output is supported:

istok task list --help

Versioned envelopes

Structured Istok results include a top-level schema_version.

Most CLI command families use:

{
  "schema_version": "1"
}

Run results use:

{
  "schema_version": "2"
}

The version identifies the structure of the returned contract.

Scripts should use structured fields and the schema version rather than parsing human-readable terminal output.

Schema versions

Different parts of Istok can evolve independently.

The main structured contracts currently use:

Repository retrieval and graph results also contain their own versioned payload contracts inside the outer envelope.

Retrieval payloads

Search and repository retrieval use a versioned nested contract:

istok.retrieval.v1

The outer CLI or MCP response remains independently versioned.

Conceptually:

CLI envelope
schema_version: "1"
        │
        └── retrieval payload
            contract: istok.retrieval.v1

This lets the general Istok response envelope and the retrieval contract evolve independently.

Graph payloads

Code graph results use their own contract:

istok.graph.v1

For example, graph symbol, neighbor, and path operations return graph data through this versioned payload while still using the surrounding Istok result envelope.

Run output

Run commands use schema version "2".

This applies to structured run results and the corresponding MCP run results.

Run data can include information associated with the execution lifecycle such as:

• run identity;
• project-scoped task identity;
• revision;
• lease state;
• executions;
• validation evidence;
• artifacts;
• terminal run state.

Use the returned structured fields rather than extracting these values from human-readable run output.

Task identity

Task output exposes both forms of task identity used by Istok.

The canonical identity is a UUID.

The CLI also exposes the project-scoped task number used for convenient commands such as:

istok task show 12

This allows programmatic integrations to retain canonical identity while human CLI workflows can continue using short project-local numbers.

Revisions

Istok uses revisions for operations that protect against stale mutations.

Structured output exposes the revision needed for subsequent compare-and-swap operations.

A programmatic workflow should read the current object, keep its revision, and provide that revision when the mutation requires:

expected_revision

If the object changed in the meantime, the mutation fails instead of silently overwriting newer state.

The caller can then read the current state and decide whether to retry.

Empty collections

Empty collections are returned as JSON arrays:

[]

rather than:

null

This applies to collection-style results such as empty task, run, search, graph, and MCP result sets.

Consumers can therefore treat a collection as an array regardless of whether it contains any items.

Structured errors

JSON operations return structured errors with stable error codes.

Use the error code when program logic needs to distinguish conditions rather than matching the human-readable error message.

The error result is versioned using the same structured-output approach as successful results.

Human output and JSON output

Human-readable output is designed for terminal use:

istok task list

JSON output is designed for machines:

istok task list --json

Avoid parsing the formatted terminal representation in scripts.

Human output may contain presentation details intended to make interactive use easier, while JSON exposes the structured contract directly.

Non-interactive operations

Automation cannot respond to interactive confirmation prompts.

For destructive operations that require confirmation, provide the explicit confirmation flag when using JSON mode.

For example:

istok project delete --json --yes

Without --yes, the JSON command does not enter an interactive confirmation flow.

This keeps automation explicit around destructive operations.

Example workflow

A script can inspect a task as JSON:

istok task show 12 --json

read its canonical identity and current revision, perform the required work, and then use those structured values in subsequent operations.

The same principle applies across Istok:

read structured state
        ↓
inspect schema_version
        ↓
use IDs and revision
        ↓
perform operation
        ↓
consume structured result

This is preferable to relying on terminal formatting or extracting values from descriptive text.

JSON and MCP

The CLI and MCP both use versioned structured contracts.

They are separate interfaces, but the same domain concepts appear in both:

Project
Task
Context
Run
Validation
Retrieval

Run results use schema version "2" in both interfaces, while the general MCP envelope uses schema version "1".

Nested retrieval and graph payloads keep their own contract versions.

Command help

Use built-in help for exact JSON support on a command:

istok project --help
istok task --help
istok run --help
istok context --help
istok search --help
istok graph --help

For programmatic integrations, prefer the documented structured contracts over human-readable output.