Using the CLI

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

$ pup check --commit HEAD --json

See Check commands 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:

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

Automation and JSON

Run without prompts#

Response format#

Check results#

History#

Stream updates#

Fix output#

Cancellation output#

Exit codes#