Skip to main content
Use activate to connect a workspace through explicit browser approval and push your first or latest audit. Use audit --push or xerg push later 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, policies, and one-way Linear issue creation require Team, Growth, Scale, or Enterprise.
For a website-first setup or a first audit:
activate:
  • creates a ten-minute, single-use pairing code and opens Xerg in the browser
  • preserves that code through SignUp, SignIn, and automatic first-workspace creation
  • shows the workspace name, full Clerk organization ID, live plan, and API environment
  • requires an administrator to approve the active workspace explicitly
  • receives the workspace key only as ciphertext sealed to this CLI’s temporary key
  • stores the decrypted credential at ~/.config/xerg/credentials.json with owner-only permissions
  • detects, audits, and pushes a supported local source after approval
If a local audit is already cached, avoid rerunning it:
You can skip activation and keep using Xerg locally. When an operator already knows the intended Clerk organization, bind the request to it:
The organization switcher preserves the pairing code. Approval is disabled, and the API independently rejects it, until the active workspace matches the requested ID. When approval covers credential pairing but not an audit or push, stop after the verified connection:
The approval page explicitly says that no audit or push is requested. After encrypted delivery, live entitlement verification, and owner-only storage, the CLI exits without source detection. --connect-only cannot be combined with --push-latest, --runtime, --cursor-usage-csv, or --ingest-file.

​
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.

​
Execution-context metadata

Local commands remain telemetry-free and add no analytics call. Pairing creation and explicit push requests include a fixed, content-free envelope with its version, coarse execution context, a bounded native-agent marker or skill-provided host hint when present, and the package invocation path. The hint is best-effort analytics metadata, not authentication. The envelope is not sent on pairing polls, acknowledgement, cancellation, entitlement verification, local analysis, doctor, explain, outcome, or update-check suppression. It excludes prompts, responses, findings, recommendations, costs, paths, source identifiers or hostnames, URLs, IP/geography, names, email addresses, user IDs, and Clerk organization IDs. Missing, old, or malformed envelopes never make pairing or push fail.

​
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.

​
Paired credential behavior

The browser never displays the workspace key. The short code in the URL cannot poll for or decrypt the key. The CLI acknowledges the exchange only after it has decrypted the credential and verified its organization and current plan through /v1/entitlements. Pairing expires after ten minutes and can be denied or cancelled without sharing a credential. New credential files retain the API origin, approved organization ID, plan at pairing, and storage timestamp alongside the token. The live plan is re-resolved whenever activate reuses the connection. A staging credential therefore remains on staging; a conflicting XERG_API_URL is rejected instead of silently redirecting it to production. Existing token-only credential files remain supported. Xerg reuses an existing valid connection unless you run:
If --organization-id does not match an existing valid connection, Xerg refuses reuse and directs you to add --replace. Re-pairing reuses the active recoverable workspace key rather than rotating it. Rotating the workspace API key in Settings revokes the credential for every paired CLI.

​
Advanced authentication

Browser pairing is the normal interactive path. The older masked-paste flow remains available for manual recovery:
The prompt masks typed and pasted key characters and verifies the replacement before atomically overwriting a stored credential. For non-interactive CI only, store XERG_API_KEY in the CI provider’s secret manager. Do not put the key inline in a shell command; shell history and same-user process listings can expose it. ~/.xerg/config.json remains supported for managed automation. XERG_API_URL overrides the API endpoint for staging or self-managed environments. Credential resolution for automation remains:
  1. XERG_API_KEY
  2. the credential stored by activate or advanced login
  3. legacy ~/.xerg/config.json
Create or rotate workspace API keys only in Dashboard Settings. The same workspace API key can be used for hosted MCP access. 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 pricing 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 identified-waste rollups
  • content-free detector coverage, assessed request/spend totals, source stability, and shared economic identity
  • 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 activate --push-latest
  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.
  • Hosted MCP clients still use a workspace API key. Create or rotate it in Settings and place it in the client’s secret configuration.