Skip to main content

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.

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

npx @xerg/cli 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,
  "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
  • comparison is null unless a compatible baseline was found
  • spendByDay and wasteByDay use UTC YYYY-MM-DD buckets
  • Cursor CSV audits also add local-only pricingCoverage and cursorUsage fields

​
Multi-source JSON

npx @xerg/cli 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 audit --push --dry-run
npx @xerg/cli push --dry-run
Shape: 
{
  "version": "...",
  "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
  },
  "meta": {
    "cliVersion": "...",
    "sourceId": "...",
    "sourceHost": "...",
    "environment": "local",
    "pushedAt": "..."
  }
}
Key details:
  • the push payload does not include sourceFiles or dbPath
  • in payload v2, the push payload does include recommendations
  • the push payload now includes daily spend and confirmed waste rollups for charting
  • 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
  • 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 2

​
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