Skip to main content
Examples use npx @xerg/cli@latest. If you installed the CLI globally, substitute xerg.
Remote SSH, Railway, and --remote-config flows are OpenClaw-only. QM has a host-independent snapshot adapter plus separate strict-direct and certified Fly-contained collection, and is never auto-detected.
Use this page in order:
  • start with the init-first path
  • pick the source type you actually want to inspect
  • copy the exact command block for that workflow
  • come back to the later sections for push, CI, and troubleshooting

​
1. Init-first path

If you only remember four commands, remember these:
What they mean:
  • init: detects local OpenClaw, Hermes, or Claude Code data and runs the first audit
  • audit --compare: compares against the newest compatible saved snapshot
  • activate --push-latest: uses browser approval and pushes the latest audit; add --organization-id org_... to require one exact Clerk workspace
  • activate --connect-only --organization-id org_...: pairs the exact workspace and exits without source detection, audit, or push
  • mcp-setup: prints or writes hosted MCP config for a supported client
Quick utility commands:
Use these when you want the top-level command list or just the installed CLI version.

​
2. Command map

​
3. Choose the right starting command

Use this quick decision guide:
  • Brand-new first run: npx @xerg/cli@latest init
  • Not sure whether Xerg can see your data: npx @xerg/cli@latest doctor
  • Ready to run the first local audit: npx @xerg/cli@latest audit
  • Want machine-readable output: npx @xerg/cli@latest audit --json
  • Want machine-readable readiness and the exact recommended command: npx @xerg/cli@latest doctor --json
  • Want to drill into a displayed item: npx @xerg/cli@latest explain <eight-character-id>
  • Want a shareable report: npx @xerg/cli@latest audit --markdown
  • Want before/after deltas: npx @xerg/cli@latest audit --compare
  • Want to audit Claude Code sessions: npx @xerg/cli@latest audit --runtime claude-code
  • Want to analyze Cursor export data: npx @xerg/cli@latest audit --cursor-usage-csv [file]
  • Want to audit another framework’s events: npx @xerg/cli@latest ingest --file payload.json
  • Want to inspect a remote OpenClaw target first: npx @xerg/cli@latest doctor --remote [user@host] or npx @xerg/cli@latest doctor --railway
  • Want to see per-file extraction coverage (which signals the parser found): npx @xerg/cli@latest doctor --verbose
  • Want cost-per-outcome: npx @xerg/cli@latest outcome --workflow [name] --status success then rerun audit
  • Want to audit QM: npx @xerg/cli@latest doctor --runtime qm then npx @xerg/cli@latest audit --runtime qm --since 7d

​
4. Direct local audits

Default local detection:
Force a specific runtime:
Use --runtime when:
  • more than one local runtime is present
  • you want deterministic behavior in automation
  • you are passing explicit local paths and already know the runtime

​
5. Point Xerg at explicit local paths

OpenClaw:
The collector is an interactive local workload capture that ends on Ctrl-C. It binds only to loopback, receives traces only, sanitizes before persistence, and never pushes automatically. --otlp-file is an independent source and cannot be combined with the log or transcript commands above. See OpenClaw trace collection. Hermes:
--state-db is mutually exclusive with legacy --log-file and --sessions-dir. The observer directory is optional and supplies request/mechanical evidence without adding economic totals. Certified Hermes traces require state.db; see Hermes analysis and Hermes trace collection. Claude Code (defaults to ~/.claude/projects/):
QM (explicit, after secure setup):
The strict direct database mode uses the saved reader connection when --fly-app is omitted. Fly uses an operator-contained exporter and reports databaseLeastPrivilege: false; offline snapshots need no database access. QM collection is one-shot, never pushes automatically, and keeps unresolved openrouter/auto cost unpriced. Useful rule of thumb:
  • use doctor first when you are not sure the paths are correct
  • use audit once doctor shows the files you expect

​
6. Analyze a Cursor usage CSV

Inspect the CSV first:
Run the audit:
Use this path when you want to analyze Cursor export rows instead of agent logs and session transcripts. It is the best practical path for Cursor data today, with known limits: usage CSV rows carry no stable retry-attempt, tool-progress, or cache-entry-lifecycle evidence, so the three monetary findings are unavailable. Cursor may still emit the neutral cache-read-concentration and max-mode-concentration signals.

​
6b. Audit any framework with an event payload

If your framework is not a built-in source — or you have richer per-event data than a usage export — export a Xerg event payload and run:
The full audit pipeline (findings, compare, push) runs on the payload.

​
7. Output modes and compare

Human-readable terminal report:
Full human-readable terminal report:
JSON for automation:
Markdown for sharing:
Remember:
  • --details, --json, and --markdown are mutually exclusive output projections
  • plain audit is the compact manual view; --details is the exhaustive manual view
  • --json is best for agents and scripts
Compare against the newest compatible saved audit:
Limit the comparison window:
Important:
  • --compare needs saved local snapshots
  • --compare and --no-db cannot be used together

​
8. Remote OpenClaw audits

​
SSH

Inspect first:
Audit:
Custom remote paths:

​
Railway

Inspect the linked service:
Audit the linked service:
Use explicit Railway IDs:

​
Multi-source config

Run a multi-source OpenClaw audit:
Use this when one command needs to inspect several SSH and Railway sources.

​
9. Hosted follow-up, dashboard, push, and authentication

Guided hosted path:
Push as part of the audit:
Preview the exact push payload:
Push the newest cached snapshot later:
Push a saved payload file:
Advanced manual recovery:
Useful distinction:
  • use activate when you want browser-approved auth plus a detected first audit
  • use activate --push-latest when the local audit is already cached
  • use audit --push when you are computing a fresh audit right now
  • use push when you already have a saved audit snapshot and only want to send it
  • use the hosted dashboard when you want pushed audit history, sources, trends, Optimizations, policies, or workspace API keys

​
10. CI and automation

Threshold gates:
Machine-readable output:
For CI only, store XERG_API_KEY in the CI provider’s secret manager and use it for non-interactive hosted automation. Do not place the secret inline in an interactive shell command.

​
11. More CI gates and automation

Fail on identified waste rate:
Fail on confirmed waste dollars:
Require request-sequence detector coverage:
Push and gate in one command:
Remote CI gate for OpenClaw:
Exit codes: Standalone push uses 5 for hosted quota, member-limit, capability, and retained-history conditions. The compatibility path through audit --push still maps the same hosted rejection to general error 1.

​
12. Troubleshooting shortcuts

Verbose local discovery:
Force a runtime when local auto-detection is ambiguous:
Check a remote target directly:
Check the CLI help:

​
13. Common copy-paste sequences

First local audit:
Hermes local audit:
Before and after workflow test:
Export JSON for an agent:
Remote OpenClaw audit over SSH:
Push into the hosted Xerg workspace:

​
14. Flag reference

ingest accepts the same human-output, persistence, compare, and push flags as audit (--since, --details, --json, --markdown, --db, --no-db, --compare, --push, --dry-run, --verbose).