# JSON results

Source: https://tapid.dev/docs/json-results

Read versioned package-operation results without mixing them with child output.

## Status

Global `--json` is published in v0.0.13. Published v0.0.12 has human diagnostics, not this JSON protocol.

```bash
$ tapid --json install
$ tapid --json outdated --json-limit 250
$ tapid --json --version
```

Supported handled operations emit one newline-terminated object on stdout with empty stderr. OS termination or a broken pipe can prevent delivery. Coverage includes `install` and `i`, `add`, `remove`, `update`, `prune` and `outdated`, plus help and version. Other commands, including `ci`, import, upgrade and `run`, fail before execution with `JSON_UNSUPPORTED_COMMAND`.

## Interpret the result

| Field                           | Use                                                                                          |
| ------------------------------- | -------------------------------------------------------------------------------------------- |
| `schema_version`                | Require a version your consumer understands; the current schema is `1`.                      |
| `operation`, `outcome`          | Identify the operation and `success`, `failure` or `partial` result.                         |
| `changes.state`                 | `unchanged`, `rolled_back`, `committed`, `committed_cleanup_pending` or `recovery_required`. |
| `errors`, `warnings`, `retry`   | Read stable codes and typed retry advice.                                                    |
| `project_path`, `changes.paths` | Use lossless native path records for filesystem inspection.                                  |
| `data`                          | Read package count/replay status or sorted outdated entries.                                 |
| `truncated_fields`              | Identify shortened display values; never use them as mutation identities.                    |

Handled operational failures exit `1`; argument errors exit `2`. A partial `outdated` report still exits `0`, so inspect `outcome` and entry errors. Its default output limit is 100 entries; `--json-limit 0` returns all entries and affects rendering only.

`do_not_repeat` means the change committed. `recover_first` requires recovery inspection. Package text is untrusted data, not executable retry instructions. Ignore additive fields and handle unknown codes conservatively. Stop automatic recovery if a required lossless path is unavailable or uses an unknown encoding.

## Decide whether to retry

Read `changes.state` together with typed `retry` advice. A nonzero exit can follow a durable commit.

| Retry advice       | Response                                                                              |
| ------------------ | ------------------------------------------------------------------------------------- |
| `after_correction` | Correct the reported failure before trying again.                                     |
| `after_contention` | Wait for the competing project or store operation.                                    |
| `do_not_repeat`    | Review the committed change; repeating may perform another mutation.                  |
| `recover_first`    | Preserve evidence and inspect the affected paths before recovery or another mutation. |

A null or unknown retry value grants no permission for an automatic retry. Read [Troubleshooting](https://tapid.dev/docs-markdown/troubleshooting/content.md) for unmanaged installations, missing store inputs and lock recovery.

## Script receipts are separate

`tapid run SCRIPT --receipt-json` streams arbitrary child output and appends a receipt to stderr. Later diagnostics can follow it. Do not parse the whole stream as one JSON object or trust its last line as a receipt. Global `--json` rejects `run` before launch. A receipt does not certify code safety or descendant cleanup.

Read the [pinned JSON schema contract](https://github.com/LimeTip/tapid/blob/v0.0.13/docs/json-results.md) for field types, path encodings and code meanings.