JSON Contract

JSON Contract

English · 繁體中文

The stable surface for shell scripts, CI jobs, and LLM agents.

Asking for JSON is explicit

The CLI never changes its output format just because the output was piped. Machine-readable output requires --json:

taiga issue view example-project#42 \
  --json \
  --fields id,ref,subject,status,version \
  --no-input

{
  "data": {
    "id": 123,
    "ref": 42,
    "subject": "Fix token refresh",
    "status": "In progress",
    "version": 7
  },
  "meta": {
    "contract": 1
  }
}

Automation should add --no-input as well, so that anything requiring interaction becomes an explicit error rather than a hung process.

Four envelopes

Situation	Shape
Single record	{ "data": {...}, "meta": {...} }
List	{ "items": [...], "page": {...}, "meta": {...} }
Dry run	{ "plan": {...}, "meta": {...} }
Error	{ "error": { "code", "message", "retryable", ... }, "meta": {...} }

Successful data goes to stdout and errors go to stderr; the two are never mixed into one stream.

Field selection

--fields takes a comma-separated list of field names and only works together with --json. Naming a field that does not exist produces an error listing the available fields, rather than silently returning nothing.

Contract versioning

meta.contract is currently 1. Within one version only optional fields are added. Removing a field, renaming it, or changing the type of an existing one requires a contract version bump and migration notes in the release.

Schema descriptors

taiga schema issue view --json
taiga schema --json

Each command's descriptor carries input and output JSON Schema (draft 2020-12) plus two annotations meant for automated decisions:

• safety: read, write, or local
• idempotency: idempotent or non_idempotent

An agent can use these to decide whether a command may run without confirmation.

Exit codes

Code	Meaning
0	success
1	unexpected internal failure
2	usage / schema
3	authentication
4	forbidden
5	not found
6	OCC conflict
7	validation / ambiguity
8	throttled
9	transport / upstream
10	confirmation required
11	ambiguous commit
130	interrupted before finishing

Code 11 matters most: it means the write may have reached Taiga but the CLI could not confirm the outcome. Query the real state before resending.

Code 130 follows the shell convention of 128 plus the signal number rather than taking a place in the table above, because stopping a command is a decision rather than a way it failed. It carries the contract code interrupted, or timeout when a deadline ran out. An interrupt that stopped a write in flight reports 11 instead, because Taiga does not undo a write when the client stops listening.

Dry runs

taiga issue edit 42 \
  --subject "New subject" \
  --dry-run \
  --json \
  --no-input

A dry run really does contact Taiga to query and resolve data — turning a status name into an ID, checking that an assignee exists — so it catches genuine configuration mistakes, while guaranteeing that no POST, PATCH, or DELETE is sent. The output carries would_write: true and performed: false.

Global flags

Flag	Purpose
--json	Emit the versioned JSON contract
--fields	Select JSON fields (requires --json)
--no-input	Never prompt; fail instead of waiting
--quiet / -q	Suppress non-essential human output
--verbose / -v	Print redacted HTTP diagnostics to stderr
--no-color	Disable color (also honours the NO_COLOR environment variable)
--profile	Select the profile
--api-url	Give the complete API base URL
--project / -p	Select the project slug