Skip to main content
Audit data stays on your machine unless you choose to push it.

​
1. Choose a setup path

​
With a terminal-capable agent

Copy/paste this prompt to Claude Code, Codex, Cursor, Hermes, OpenClaw, or another agent that can run terminal commands on the machine holding your data:
Fetching the skill requires network access. The agent runs the audit locally and asks before any hosted push. See agent clients for client-specific setup.

​
Run the CLI yourself

No install:
Or install once with npm:
The CLI requires Node.js 22.13.0 or newer. Setup needs terminal access to the machine or environment holding your agent data. Package-runner commands may fetch the published package before execution.

​
Connect and push in one explicit command

activate is noninteractive-friendly: it connects a workspace through browser approval, detects a source, audits locally, and then pushes. A missing source exits 2 with recovery instructions; --connect-only deliberately stops before detection and exits 0.

​
2. Run the first-run flow

init is interactive and walks you through your first audit. It:
  • checks local OpenClaw, Hermes, and Claude Code defaults (current Hermes uses read-only ~/.hermes/state.db; Claude Code transcripts are read from ~/.claude/projects/)
  • asks you to choose the runtime when more than one is detected
  • runs the first audit and stores the local snapshot
  • prints the normal terminal summary
  • offers optional hosted follow-up after the audit succeeds
If no local data is found, init prints the default paths it checked plus the next-step commands for:
  • explicit local paths
  • Claude Code transcripts elsewhere via --claude-code-dir
  • Cursor usage CSV exports via --cursor-usage-csv
  • event payloads from any framework via npx @xerg/cli@latest ingest --file payload.json
  • optional OpenClaw trace collection via npx @xerg/cli@latest collect openclaw; stop with Ctrl-C, then review the local audit
  • optional certified Hermes trace enrichment via npx @xerg/cli@latest collect hermes --state-db ~/.hermes/state.db; the first-party observer remains the recommended parity path
  • npx @xerg/cli@latest audit --remote user@host
  • npx @xerg/cli@latest audit --railway
Remote SSH and Railway audits are OpenClaw-only. QM is deliberately not auto-detected. A QM administrator first chooses strict direct or Fly-contained collection, installs the reviewed export views, and provisions the deployment identity key. For the certified Fly path:
See secure QM setup. Never paste a QM database URL or identity key into a command or chat.

​
3. Make one workflow or model change, then compare

--compare looks for the newest compatible cached snapshot on your machine and adds before and after deltas. If no compatible baseline exists yet, Xerg does not fail. It adds a note telling you to run the same audit again after a fix.

​
4. Use direct commands when you want explicit control

Use the direct flows instead of init when you need non-interactive behavior, CI gates, or a specific output mode immediately:
If more than one local runtime is present, add --runtime openclaw, --runtime hermes, or --runtime claude-code. QM is always explicit with --runtime qm plus a saved connection, --fly-app, or --qm-snapshot.

​
5. Export or automate

Shareable Markdown:
Machine-readable JSON:
Fail CI if confirmed waste is too high:
Push an audit summary to the Xerg API explicitly:

​
6. Optional hosted follow-up

If you want hosted features after the first local result, create a free workspace (or use an existing one):
  • activate opens Xerg for explicit browser approval, shows the exact organization/plan/environment, encrypts the workspace credential to this CLI, and stores it with owner-only environment binding; add --organization-id org_... when the intended workspace is known, --connect-only to stop without an audit or push, or --push-latest to push the cached audit
  • mcp-setup prints or writes hosted MCP config for Cursor, Claude Code, Codex, or another client (hosted MCP requires Team, Growth, Scale, or Enterprise)
  • the hosted dashboard groups incremental pushed-audit snapshots and shows sources, trends, Optimizations, policies, and workspace API keys
  • the same workspace API key works for CLI push and hosted MCP
You can skip both and keep using Xerg locally. If you have not run a local audit yet, use npx @xerg/cli@latest activate instead. It connects the workspace, detects a supported local source, runs the audit, and pushes it.

​
Common next steps