Skip to main content
Use --push when you want the audit summary sent as part of the same command that computed it. Use xerg push when you want to send the most recent cached snapshot later.
Hosted features such as the dashboard, Ask Xerg, and the hosted MCP server require a Pro or Enterprise workspace.
Push immediately after computing an audit: 
npx @xerg/cli audit --push
Preview the exact payload without sending it: 
npx @xerg/cli audit --push --dry-run
audit --push --dry-run prints the push payload to stdout and suppresses the normal audit report.

​
Re-push a cached audit later

Push the most recent cached local snapshot: 
npx @xerg/cli push
Preview it: 
npx @xerg/cli push --dry-run
Push a specific saved payload file: 
npx @xerg/cli push --file ./audit-payload.json
xerg push --file expects a JSON file that already matches the AuditPushPayload wire shape. It does not read an arbitrary local audit summary.

​
Authentication precedence

Xerg resolves API credentials in this order:
  1. XERG_API_KEY
  2. ~/.xerg/config.json
  3. stored browser credentials from xerg login
Optional API URL overrides:
  • XERG_API_URL
  • apiUrl in ~/.xerg/config.json
Example config: 
{
  "apiKey": "sk_live_or_test_key",
  "apiUrl": "https://api.xerg.ai"
}
The same workspace API key can be used for hosted MCP access. See hosted MCP for client configuration.

​
Browser login

Start the device flow: 
npx @xerg/cli login
By default:
  • Xerg starts device authentication against https://api.xerg.ai
  • it opens the verification URL in your browser when possible
  • it stores the resulting token at ~/.config/xerg/credentials.json
To clear stored browser credentials: 
npx @xerg/cli logout

​
What gets pushed

The push payload contains:
  • a versioned audit summary
  • daily spend and confirmed waste rollups
  • top-level findings and taxonomy buckets
  • optional comparison deltas
  • metadata such as CLI version, source ID, source host, environment, and push timestamp
The push payload does not include raw prompt or response content. It also omits local-only sourceFiles and dbPath fields from the audit summary.

​
Push versus hosted MCP

Use push when you want to send audit summaries from the CLI into your hosted workspace. Use hosted MCP when you want a remote MCP client to read hosted audit history, trends, recommendations, or selected hosted control actions from that workspace. A common sequence is:
  1. run xerg audit --push
  2. verify the hosted audit in the dashboard
  3. connect a remote client to hosted MCP

​
Important gotchas

  • xerg push reads from the default local database path. It does not accept --db.
  • If you used xerg audit --db /custom/path, push immediately with xerg audit --push, or export the payload and use xerg push --file.
  • --dry-run on xerg audit requires --push.
  • If hosted MCP returns empty audit results, push an audit first so the workspace has hosted data to query.