> ## Documentation Index
> Fetch the complete documentation index at: https://taskgraph-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON Output

> Which commands print JSON, the schemaVersion every payload carries, and what stays stable within a version

Scripts and agents can read TaskGraph's output as JSON. Every JSON payload the CLI prints is one object whose first key is `schemaVersion`:

```bash theme={null}
taskgraph next --json
```

```json theme={null}
{
  "schemaVersion": 2,
  "found": true,
  "task": { "id": "2", "title": "Add Postgres", "status": "pending", ... },
  "tag": "master",
  "hasAnyTasks": true
}
```

Every command that takes `--format` also takes `--json` as its shorthand, so `next --json` and `next --format json` print the same thing. A `--format` typed on the same line wins over `--json`.

Check `schemaVersion` before you parse. If it is higher than the version your script was written for, a key you read may have been renamed or removed.

## Commands

| Command | Flag | Top-level keys besides `schemaVersion` |
| - | - | - |
| `list` | `--json` or `--format json` | `tasks`, `metadata` |
| `show <id>` | `--json` or `--format json` | `found`, `task` (one ID, plus `originalTaskId` for a subtask); `tasks`, `notFound` (several IDs) |
| `next` | `--json` or `--format json` | `found`, `task`, `tag`, `hasAnyTasks`, `checklist` (when the task has acceptance criteria) |
| `next --claim` | `--json` or `--format json` | `claimed`, `task`, `claimedBy`, `claimedAt`, `tag`, `hasAnyTasks` |
| `graph` | `--json` or `--format json` | `tag`, `total`, `roots`, `criticalPath`, `bottlenecks`, `cyclic`, `nextId`, `waves` (each node also has `wave`) |
| `why <id>` | `--json` or `--format json` | `id`, `title`, `status`, `tag`, `blocked`, `blockers`, `rootCauses` |
| `tags`, `tags list` | `--json` | `tags`, `currentTag`, `totalTags` |
| `prime` | `--json` | `tag`, `counts`, `inProgress`, `ready`, `rules` |
| `prime --unnoted-since <time>` | `--json` | `unnoted` |
| `generate` | `--json` or `--format json` | `success`, `count`, `directory`, `orphanedFilesRemoved` |
| `set-status` | `--json` or `--format json` | `success`, `updatedTasks`; on failure `success`, `error`, `taskId`, `timestamp` |
| `archive` | `--json` or `--format json` | `tasks` (each with `id`, `title`, `status`), `tag`, `olderThanDays`, `dryRun` |
| `archive restore <id>` | `--json` or `--format json` | `restored`, `tag`, `task` |
| `github status` | `--json` | `ghAvailable`, `repo`, `linkedTasks`, `unlinkedTasks` |
| `github push` | `--json` (with `--yes` or `--dry-run`) | `dryRun`, `plan`, `created`, `updated`, `skipped`, `closed`, `orphans` |
| `github pull` | `--json` (with `--yes` or `--dry-run`) | `dryRun`, `plan`, `applied`, `synced`, `conflicts`, `skipped` |
| `github unlink <id>` | `--json` | `tag`, `taskId`, `issueNumber`, `url` |
| `parse-prd --clarify` | `--json` | `prd`, `questions` |

In `list` JSON, each task's `blocks` lists the IDs of the tasks that depend on it, whatever their status. `--status` filters the rows, not `blocks`.

`set-status` prints its JSON on one line, including when it fails. Other commands print an error as text on stderr and exit with a non-zero code, leaving stdout empty.

In a JSON run, stdout holds only the JSON: banners, the update check and other notices are skipped, and warnings (such as a missing config file) go to stderr.

Some keys are only present when they apply. For example, a task has `acceptanceCriteria` only when it has criteria, and `tags` has `subtaskCounts` only for tags with subtasks. Treat a missing key as "not set".

## Plain lines from `list` in a pipe

When stdout isn't a terminal (a pipe, a file, or an agent's shell) and no `--format` is given, `taskgraph list` prints one plain line per task instead of the summary and table: full titles, no color codes, no box characters.

```
1  done         high    Set up the database
2  in-progress  high    Sign-in with sessions  deps:1
3  pending      medium  Bookmark endpoints  deps:2
```

The columns are ID, status, priority and title, separated by two or more spaces, then `deps:` with the task's dependencies when it has any. `--with-subtasks` adds a line for each subtask with its dotted ID (`2.1`), and `--all-tags` puts the tag first. Pass `--format text` to get the summary and table in a pipe, or `--json` for every field.

## What stays the same within a version

For a given `schemaVersion`:

* Keys already in a payload keep their names.
* Each key keeps its type. A string stays a string, an array stays an array.
* New keys can be added. Ignore keys you don't recognise.

Removing or renaming a key, or changing its type, raises `schemaVersion`. A new key does not.

The current version is `2`.

| Version | Change |
| - | - |
| `2` | `show` gives task IDs, task `dependencies` and subtask IDs as strings, as `list` and `next` do, and its subtasks gain `parentId`. A subtask's `dependencies` keep their stored type: a bare number names a sibling subtask, a string names a task or a dotted subtask. |
| `1` | First versioned output. |

## Not the same as the tasks file version

The output's `schemaVersion` is not the `metadata.schemaVersion` stored on each tag in `.taskgraph/tasks/tasks.json` (see [Schema version](https://taskgraph-ai.com/capabilities/dependency-graph.md#schema-version)). They change independently: a new field in the file does not have to change the output, and a new key in the output does not change the file.

## How the contract is kept

Each command's shape (keys and value types) is pinned in a test. A change to the shape fails CI until the pinned shape is updated, and a breaking change also needs a version bump:

* `apps/cli/tests/integration/json-output/json-contract.test.ts` runs the built CLI on a fixture project.
* `apps/cli/src/commands/github/github.command.spec.ts` covers `github push`, `pull` and `unlink`, which need a GitHub repository to run for real.
* `apps/cli/tests/integration/commands/parse-prd-clarify.command.test.ts` covers `parse-prd --clarify --json`, which needs a model to answer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.