Using the CLI

Automation and JSON

Use --json to read Super CLI’s output in scripts and coding agents. This page documents the response format and behavior. You don’t need to read it to use the CLI 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 SUPER_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.

$ super 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`	The check 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 super status --run <run-id> --json in the same linked repository. Use --check <number> for one check. Plain super status and check --problems select the latest run, which can change.

History

super 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
`super check --json`	Wait for checks to finish, then emit one `results` response.
`super check --json --detach`	Emit one `results` response on acceptance.
`super check --json --stream`	Emit initial `results`, live events, then final `results`.
`super 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

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

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

Usage output

super usage --json emits one type: "usage" response. Its data contains exact totalTokens and totalChecks for the selected activity period and repository, with up to ten recent checks. repositories lists the account’s repository names and IDs. start, end, and asOf describe the report’s time window and snapshot time.

quota is account-wide, independent of the activity filters. It includes limit, used, remaining, exhausted, and nextAvailableAt. A null quota means quota information is unavailable; a null quota.limit means there is no limit. Token measurements can also be null. Check usageAvailable, pending, and each check’s usagePending before treating totals as final.

A successfully loaded report exits 0, including when quota is exhausted or recent checks failed. Invalid arguments, authentication failures, and request errors exit 2.

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#

Usage output#

Exit codes#