> Canonical HTML: [https://docs.schematic.tech/pup/reference/automation/](https://docs.schematic.tech/pup/reference/automation/)

# Automation and JSON

Use `--json` to read Pup's output in scripts and coding agents. This page documents the response
format and behavior. You don't need to read it to use Pup interactively.

## Run without prompts

Every public command accepts `--json`. It disables prompts and the interactive view and includes
full result details. Use your saved login or
[`PUP_ACCESS_TOKEN`](/pup/commands/account/#authenticate-automated-commands) for authentication.

If your repository has uncommitted changes, JSON mode can't prompt you about including them.
Use `--dirty` to include them or `--commit HEAD` to check committed code.

**Bash**

```console
$ pup check --commit HEAD --json
```

See [Check commands](/pup/commands/checks/) for command options and usage.

## Response format

Each response has `schema_version` (currently `1`), `type`, and `data`. The `type` identifies
the kind of response; `data` contains its fields. For a `results` response, the checks are in
`data.rows`. JSON goes to stdout; diagnostics go to stderr.

This excerpt shows a completed check that found a problem; other fields are omitted:

**Check response (excerpt)**

```json
{
  "schema_version": 1,
  "type": "results",
  "data": {
    "finished": true,
    "rows": [
      {
        "current": {
          "number": 42,
          "result": {
            "outcome": "fail",
            "assurance": "uncertified"
          },
          "terminal": true,
          "problematic": true,
          "operational_error": null
        }
      }
    ]
  }
}
```

Command errors use `type: "error"`, with an error code in `data.code` and a readable explanation
in `data.message`. See [Exit codes](#exit-codes) for command success and failure.

When `check --problems` has nothing to recheck, it returns one `success` response and exits `0`,
including with `--stream`.

## Check results

A `results` response has `data.rows`, with one row per selected supertest. Each row contains
`supertest`, `current`, and `previous`; either check can be `null`. Each check includes its
`number`, the source checked in `revision`, and these result fields:

| Field               | Meaning                                                                             |
| ------------------- | ----------------------------------------------------------------------------------- |
| `result`            | `null` if no conclusion has been reported.                                          |
| `result.outcome`    | `pass` indicates a passing result; `fail` indicates a reported problem.             |
| `result.assurance`  | `certified` or `uncertified`, independent of the outcome.                           |
| `terminal`          | A result or operational failure has been reported.                                  |
| `operational_error` | `null` if no operational error; otherwise an error code. Can coexist with a result. |
| `problematic`       | Pup reported problems with the checked behavior.                                    |
| `updates_pending`   | Further updates may arrive.                                                         |
| `fix_pending`       | A fix proposal may still arrive.                                                    |
| `fix`               | The full proposal when available; otherwise omitted.                                |

`data.finished` means all loaded current checks are terminal, not that they all passed. Check
for missing (`current: null`) or inconclusive results and pending updates separately.

Use the result fields above for decisions. Status labels in `presentation.status.label`, text
in `presentation.details`, and error messages are for display. Their wording can change, so
don't rely on exact text in scripts.

To retrieve the same run, use `data.run.id` with `pup status --run <run-id> --json` in the same
linked repository. Use `--check <number>` for one check. Plain `pup status` and `check --problems`
select the latest run, which can change.

### History

`pup status --history --json` adds a page of checks in `data.history`. Pass a non-null
`data.next_before` as `--before <number>` with the same selection for the next page.
`previous: null` means no previous check was loaded; earlier checks may still exist.

## Stream updates

Streaming output is newline-delimited JSON: parse one object per line.

| Command                     | Behavior                                                                                 |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `pup check --json`          | Wait for checks to finish, then emit one `results` response.                             |
| `pup check --json --detach` | Emit one `results` response on acceptance.                                               |
| `pup check --json --stream` | Emit initial `results`, live events, then final `results`.                               |
| `pup status --watch --json` | Emit initial `results`, follow results and pending updates, then emit `closed` and exit. |

`--stream` requires `--json` and cannot be combined with `--detach`. Read through process exit,
including both `results` responses when results are already available. A streaming check stops
when checks are terminal; `status --watch --json` also waits until `updates_pending` is false.

| Event type      | Data                                                                           |
| --------------- | ------------------------------------------------------------------------------ |
| `check_updated` | `check_number` and the full updated `check`. Replace the stored check with it. |
| `connection`    | `connected`: whether the followed connections are up.                          |
| `closed`        | `target` to resume and `detached`: whether checks were still unfinished.       |

Ctrl+C closes observation without canceling checks. A streaming `check` returns its final,
possibly unfinished, `results` instead of `closed`. A failure may end the stream with `error`.

## Fix output

`pup fix --check <number> --dry-run --json` returns `fix_proposal`. Its `data` contains the full
`proposal` (diff, instructions, and validation), plus:

| Field             | Meaning                                                 |
| ----------------- | ------------------------------------------------------- |
| `applies_cleanly` | Whether the patch can be applied to your working files. |
| `apply_error`     | Why the patch cannot be applied, or `null` if it can.   |
| `source_changed`  | Whether working source differs from the checked source. |

`pup fix --check <number> --yes --json` applies the patch and returns one `success` response
with `message`, `check_number`, and `source_changed`.

## Cancellation output

Cancellation returns `results` with a `data.interrupted` flag and a `data.cancellation` array.
Each entry has `check_number`, `outcome`, and an optional `error` message:

| Outcome                                 | Meaning                                                    |
| --------------------------------------- | ---------------------------------------------------------- |
| `canceled`                              | Cancellation stopped the check.                            |
| `background_stopped`                    | Background work stopped; the result is retained.           |
| `already_finished` / `already_canceled` | Already stopped; no request was sent.                      |
| `finished`                              | Finished before cancellation took effect.                  |
| `requested`                             | Accepted, but stopping is not yet confirmed.               |
| `unconfirmed`                           | Unconfirmed, including interruption before acknowledgment. |

Check data retains the last observed state. Inspect each entry for partial success; follow
`requested` outcomes with `status` to confirm cancellation.

## Exit codes

| Code | Meaning                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------- |
| `0`  | The command succeeded. For a completed `check`, no current check has an operational error or `problematic: true`.      |
| `1`  | A completed `check` reported problems, with no operational errors.                                                     |
| `2`  | An operational failure, including blocked or canceled checks, invalid arguments, authentication, or connection errors. |

Operational failures take precedence over reported problems. `status` can exit `0` regardless
of the results it displays. `check --detach` and Ctrl+C after acceptance can also exit `0` with
unfinished checks; interruption before acceptance exits `2`.

`cancel` exits `0` for accepted requests or when nothing remains to cancel. It exits `2` on
interruption or a request or confirmation failure. Individual outcomes remain in its report.