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.

Use connect when you want the guided hosted path after the first local audit. Use audit --push or xerg push when you want explicit push behavior.
Local audits and compare are free. Hosted features such as the dashboard, Ask Xerg, and the hosted MCP server require a Pro or Enterprise workspace.
After your first local audit: 
npx @xerg/cli connect
connect:
  • reuses auth from XERG_API_KEY, ~/.xerg/config.json, or stored browser credentials when available
  • prompts before browser login when auth is missing
  • offers to push the latest cached audit, or the in-memory audit when called from init
  • stays non-interactive when auth is already configured and no prompt is needed
You can skip it and keep using Xerg locally.

​
Explicit push flows

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 directly when you want browser auth without the hosted push prompt: 
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
  • ranked recommendations with where-to-change and validation guidance
  • 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 init or xerg audit
  2. run xerg connect
  3. verify the hosted audit in the dashboard
  4. run xerg mcp-setup or 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.
  • If you authenticated with a stored browser login and hosted MCP still needs a workspace API key, create one in the dashboard and set XERG_API_KEY.