JSON output

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.

npx @xerg/cli@latest audit --json

Shape:

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

npx @xerg/cli@latest audit --remote-config ./remotes.json --json

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

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

npx @xerg/cli@latest audit --push --dry-run
npx @xerg/cli@latest push --dry-run

Shape:

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

Concepts

Hosted workspace

Automate and share

Releases

JSON output

Audit summary JSON

Multi-source JSON

Push payload JSON

Wire schema notes

When to use which JSON

​Audit summary JSON

​Multi-source JSON

​Push payload JSON

​Wire schema notes

​When to use which JSON

Audit summary JSON

Multi-source JSON

Push payload JSON

Wire schema notes

When to use which JSON