Вывод JSON

Команды с поддержкой --json возвращают структурированный версионированный вывод для скриптов и интеграций. Используйте его всегда, когда вывод Istok читает программа: человекочитаемый формат рассчитан на людей и может меняться.

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

Поддерживает ли команда --json, видно в её --help.

Версии схем

У каждого результата есть поле верхнего уровня schema_version. Разные части Istok версионируют свои контракты независимо:

Проверяйте schema_version, прежде чем полагаться на структуру.

Вложенные данные

Результаты поиска и графа несут собственный контракт внутри внешней обёртки, так что они могут развиваться независимо:

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 пишет файл с собственным контрактом istok.knowledge-export.v1. Экспорт в Markdown содержит тот же идентификатор в заголовке метаданных.

Результаты запусков

Результаты запусков в CLI и MCP используют версию "2". В них есть идентификатор запуска, идентификатор задачи внутри проекта, ревизия, состояние аренды, выполнения, доказательства проверки, артефакты и конечное состояние.

Идентификатор задачи

Результаты задач содержат и канонический UUID задачи, и номер внутри проекта, который используют команды вроде istok task show 12. Сохраняйте UUID, когда нужна стабильная ссылка, например для источника заметки знаний.

Ревизии

Результаты содержат ревизию, нужную для операций сравнения с обменом (compare-and-swap). Прочитайте объект, сохраните его ревизию и передайте её как ожидаемую (--expected-revision в CLI, expected_revision в структурированных входных данных). Если объект за это время изменился, операция завершится ошибкой, а не перезапишет более новое состояние; прочитайте объект снова и решите, повторять ли операцию.

Пустые коллекции

Пустые коллекции — это [], никогда не null. Это касается наборов результатов задач, запусков, поиска, графа и MCP, так что коллекцию всегда можно считать массивом.

Ошибки

JSON-операции возвращают структурированные версионированные ошибки со стабильными кодами. Ориентируйтесь на код, а не на текст сообщения.

Неинтерактивное использование

В режиме JSON команда никогда не ждёт интерактивного подтверждения. Разрушительным командам, которые обычно спрашивают подтверждение, нужен явный флаг:

istok project delete --json --yes

Типичный скрипт

прочитать структурированное состояние   istok task show 12 --json
проверить schema_version
сохранить ID и ревизию
выполнить операцию                      с --expected-revision
прочитать структурированный результат