Skip to main content
Scripts and agents can read TaskGraph’s output as JSON. Every JSON payload the CLI prints is one object whose first key is schemaVersion:
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

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.
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.

​
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). 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.