Skip to main content
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 with no account. Pushing works with a free workspace, which keeps the last 30 days of pushed audits and up to 100 stored snapshots per month. Ask Xerg, hosted MCP, Slack, and policies require a Pro or Enterprise workspace.
After your first local audit:
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
  • sends pushed audits to the workspace shown in the hosted dashboard
You can skip it and keep using Xerg locally.

​
Explicit push flows

Push immediately after computing an audit:
Preview the exact payload without sending it:
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:
Preview it:
Push a specific saved payload file:
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:
Create or rotate workspace API keys from the hosted dashboard Overview or Settings pages. The same workspace API key can be used for hosted MCP access. See hosted dashboard and hosted MCP for setup details.

​
Browser login

Start browser auth directly when you want stored credentials without the hosted push prompt:
By default:
  • Xerg opens the hosted dashboard settings page in your browser
  • you create or copy a workspace API key there and paste it into the terminal
  • the terminal prompt masks typed and pasted key characters
  • Xerg verifies the key against https://api.xerg.ai and stores it at ~/.config/xerg/credentials.json
The signup-first wizard uses this secure login flow by default. Its optional one-command path places XERG_API_KEY=<key> inline with the audit command; that can save the key in shell history and expose it to other processes running as your user. Rotate an exposed key in Workspace Settings. If this machine already stores credentials for another workspace, use the wizard’s replacement command:
Xerg verifies the new key before atomically replacing the existing credential, so a rejected key does not log you out of the current workspace. At the Free limit of 100 distinct stored snapshots in a UTC month, new distinct pushes return a structured quota remedy with the reset time and Pro URL. Identical retries remain safe because they are deduplicated before quota accounting. To clear stored browser credentials:

​
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. review Optimizations or create a workspace API key in Settings
  5. run xerg mcp-setup or connect a remote client to hosted MCP

​
Important gotchas

  • xerg push reads from the default local snapshot store 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.