> ## Documentation Index
> Fetch the complete documentation index at: https://xerg.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON output

> Use Xerg's machine-readable summary and push payload formats for automation.

Xerg has two related JSON outputs:

* `xerg audit --json` returns the local audit summary including recommendations
* `xerg audit --push --dry-run` and `xerg push --dry-run` return the push payload that would be sent to the Xerg API

The shared wire types are published in `@xerg/schemas`.

## Audit summary JSON

Hermes audits can include a local-only `mechanicalEfficiency` block with `metrics`, separate non-monetary `findings`, `coverage`, and optional `comparison` deltas. Mechanical findings do not have `classification` or `costImpactUsd`. The entire block—including event IDs, fingerprints, session IDs, and mechanical kinds—is removed recursively before any push payload is built.

OpenClaw and Hermes audits can include local-only `analysisCoverage`, `toolActivity`, and `workloadEconomics` blocks. They contain eligibility, neutral tool-association, and lineage economics—not findings or savings claims—and are removed before push payload construction. Request correlation evidence and orchestration events also remain local-only.

```bash theme={null}
npx @xerg/cli@latest audit --json
```

Shape:

```json theme={null}
{
  "auditId": "...",
  "generatedAt": "...",
  "comparisonKey": "...",
  "comparison": null,
  "since": "24h",
  "runCount": 12,
  "callCount": 83,
  "totalSpendUsd": 148.0,
  "observedSpendUsd": 105.0,
  "estimatedSpendUsd": 43.0,
  "wasteSpendUsd": 19.5,
  "opportunitySpendUsd": 28.2,
  "structuralWasteRate": 0.1318,
  "wasteBySignalSource": {
    "observedUsd": 12.4,
    "inferredUsd": 7.1,
    "declaredUsd": 0,
    "unknownUsd": 0,
    "inferredShare": 0.3641
  },
  "wasteByKind": [],
  "opportunityByKind": [],
  "spendByWorkflow": [],
  "spendByModel": [],
  "spendByDay": [],
  "wasteByDay": [],
  "findings": [],
  "notes": [],
  "sourceFiles": [],
  "dbPath": "...",
  "recommendations": []
}
```

Key details:

* `recommendations` are part of the audit summary itself
* `sourceFiles` and `dbPath` are present here because this is the local summary format
* local findings may include `signalSource`, `ruleId`, and `evidence`; `ruleId` and `evidence` are local-only, while `signalSource` also crosses the wire
* `wasteBySignalSource.unknownUsd` is used for older summaries that predate provenance fields
* `comparison` is `null` unless a compatible baseline was found
* `spendByDay` and `wasteByDay` use UTC `YYYY-MM-DD` buckets
* `pricingCoverage` reports how many calls had resolvable pricing; unpriced calls are counted as \$0 and flagged rather than silently zeroed
* `pricingCoverage.pricedTokenCount` and `unpricedTokenCount` count priced input plus output tokens. Cache buckets remain visible in token economics and are included in total run tokens and cost.
* Cursor CSV audits also add a local-only `cursorUsage` token/mode breakdown

## Multi-source JSON

```bash theme={null}
npx @xerg/cli@latest audit --remote-config ./remotes.json --json
```

If more than one source succeeds, the JSON output becomes:

```json theme={null}
{
  "sources": [
    {
      "name": "prod",
      "auditId": "...",
      "recommendations": []
    },
    {
      "name": "railway-api",
      "auditId": "...",
      "recommendations": []
    }
  ]
}
```

If exactly one configured source succeeds, Xerg returns a single summary object rather than a top-level `sources` wrapper.

## Push payload JSON

Preview the push payload without sending it:

```bash theme={null}
npx @xerg/cli@latest audit --push --dry-run
npx @xerg/cli@latest push --dry-run
```

Shape:

```json theme={null}
{
  "version": 3,
  "summary": {
    "auditId": "...",
    "generatedAt": "...",
    "comparisonKey": "...",
    "runCount": 12,
    "callCount": 83,
    "totalSpendUsd": 148.0,
    "observedSpendUsd": 105.0,
    "estimatedSpendUsd": 43.0,
    "wasteSpendUsd": 19.5,
    "opportunitySpendUsd": 28.2,
    "structuralWasteRate": 0.1318,
    "wasteByKind": [],
    "opportunityByKind": [],
    "spendByWorkflow": [],
    "spendByModel": [],
    "spendByDay": [],
    "wasteByDay": [],
    "findings": [],
    "recommendations": [],
    "notes": [],
    "comparison": null,
    "wasteBySignalSource": {
      "observedUsd": 12.4,
      "inferredUsd": 7.1,
      "declaredUsd": 0,
      "unknownUsd": 0,
      "inferredShare": 0.3641
    },
    "pricingCoverage": {
      "pricedCallCount": 80,
      "unpricedCallCount": 3,
      "pricedTokenCount": 410000,
      "unpricedTokenCount": 9000
    }
  },
  "meta": {
    "cliVersion": "...",
    "sourceId": "...",
    "sourceHost": "...",
    "environment": "local",
    "pushedAt": "...",
    "dedupKey": "..."
  }
}
```

Key details:

* the push payload does not include `sourceFiles` or `dbPath`
* findings carry an optional `signalSource` (observed, inferred, or declared); `ruleId`, `evidence`, and `details` never cross the wire
* `wasteBySignalSource` and `pricingCoverage` are optional rollup-level provenance fields; no raw prompts, paths, per-call request evidence, analysis coverage, tool activity, workload lineage, or mechanical data are included
* payload version 3 includes `recommendations`, token economics, outcomes, provenance rollups, pricing coverage counts, and the content-addressed dedup key
* the push payload now includes daily spend and confirmed waste rollups for charting
* `meta.dedupKey` is the content-addressed audit ID; the API deduplicates repeat pushes within its server-side window
* `audit --push --dry-run` prints only the payload, not the normal audit report
* `meta.environment` is `local`, `remote`, or `railway` depending on how the audit was run

## Wire schema notes

The push payload is a mapped wire contract, not a raw dump of the internal local summary.

* `AuditPushPayload` is the top-level type sent by the CLI
* `WireFinding` intentionally excludes internal `details`, `ruleId`, and `evidence`; it carries an optional `signalSource`
* `WireComparison` includes the top-line delta fields only
* per-workflow deltas and per-model deltas are not part of the push payload
* `summary.recommendations` is part of payload version 3

## When to use which JSON

* use `audit --json` for local automation that needs recommendations or source metadata
* use `--push --dry-run` when you want the exact wire payload that would be sent to the API