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.
Examples use npx @xerg/cli. If you installed the CLI globally, substitute xerg.
Remote SSH, Railway, and --remote-config flows are OpenClaw-only in this phase. Hermes support is local-only.
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:
npx @xerg/cli init
npx @xerg/cli audit --compare
npx @xerg/cli connect
npx @xerg/cli mcp-setup
init: detects local OpenClaw or Hermes data and runs the first auditaudit --compare: compares against the newest compatible saved snapshotconnect: handles hosted auth and offers to push the latest auditmcp-setup: prints or writes hosted MCP config for a supported client
Quick utility commands:
npx @xerg/cli --help
npx @xerg/cli --version
npx @xerg/cli -v
2. Command map
| Goal | Command | Use when |
|---|
| Guided first audit | init | You want the fastest local-first onboarding path |
| Check local readiness | doctor | You want to confirm paths and detection before auditing |
| Run an audit | audit | You want spend, waste, opportunities, workflows, and models |
| Compare before and after | audit --compare | You already have a prior compatible cached snapshot |
| Connect to hosted Xerg | connect | You want guided auth and an optional push prompt |
| Push a new result immediately | audit --push | You want to compute and push in one step |
| Push a cached result later | push | You already ran an audit and want to send the latest saved snapshot |
| Configure hosted MCP | mcp-setup | You want Cursor, Claude Code, Codex, or another client to use hosted MCP |
| Authenticate in browser | login | You want hosted push or other API-backed features |
| Remove saved credentials | logout | You want to clear local auth state |
3. Choose the right starting command
Use this quick decision guide:
- Brand-new first run:
npx @xerg/cli init
- Not sure whether Xerg can see your data:
npx @xerg/cli doctor
- Ready to run the first local audit:
npx @xerg/cli audit
- Want machine-readable output:
npx @xerg/cli audit --json
- Want a shareable report:
npx @xerg/cli audit --markdown
- Want before/after deltas:
npx @xerg/cli audit --compare
- Want to analyze Cursor export data:
npx @xerg/cli audit --cursor-usage-csv [file]
- Want to inspect a remote OpenClaw target first:
npx @xerg/cli doctor --remote [user@host] or npx @xerg/cli doctor --railway
4. Direct local audits
Default local detection:
npx @xerg/cli doctor
npx @xerg/cli audit
npx @xerg/cli doctor --runtime openclaw
npx @xerg/cli doctor --runtime hermes
npx @xerg/cli audit --runtime openclaw
npx @xerg/cli audit --runtime hermes
--runtime when:
- both OpenClaw and Hermes are present locally
- 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:
npx @xerg/cli doctor --runtime openclaw --log-file /path/to/openclaw.log
npx @xerg/cli doctor --runtime openclaw --sessions-dir /path/to/sessions
npx @xerg/cli audit --runtime openclaw --log-file /path/to/openclaw.log
npx @xerg/cli audit --runtime openclaw --sessions-dir /path/to/sessions
npx @xerg/cli doctor --runtime hermes --log-file ~/.hermes/logs/agent.log
npx @xerg/cli doctor --runtime hermes --sessions-dir ~/.hermes/sessions
npx @xerg/cli audit --runtime hermes --log-file ~/.hermes/logs/agent.log
npx @xerg/cli audit --runtime hermes --sessions-dir ~/.hermes/sessions
- 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:
npx @xerg/cli doctor --cursor-usage-csv ~/Downloads/usage-events.csv
npx @xerg/cli audit --cursor-usage-csv ~/Downloads/usage-events.csv
npx @xerg/cli audit --cursor-usage-csv ~/Downloads/usage-events.csv --json
7. Output modes and compare
Human-readable terminal report:
JSON for automation:
npx @xerg/cli audit --json
npx @xerg/cli audit --markdown > xerg-audit.md
--json and --markdown are mutually exclusive- plain
audit is best for manual inspection
--json is best for agents and scripts
Compare against the newest compatible saved audit:
npx @xerg/cli audit --compare
npx @xerg/cli audit --compare --json
npx @xerg/cli audit --since 24h --compare
npx @xerg/cli audit --since 7d --compare
--compare needs saved local snapshots--compare and --no-db cannot be used together
8. Remote OpenClaw audits
SSH
Inspect first:
Audit:
Custom remote paths:
npx @xerg/cli doctor \
--remote [email protected] \
--remote-log-file /var/log/openclaw \
--remote-sessions-dir /srv/openclaw/sessions
npx @xerg/cli audit \
--remote [email protected] \
--remote-log-file /var/log/openclaw \
--remote-sessions-dir /srv/openclaw/sessions
Railway
Inspect the linked service:
npx @xerg/cli doctor --railway
npx @xerg/cli audit --railway
npx @xerg/cli doctor \
--railway \
--project <project-id> \
--environment <environment-id> \
--service <service-id>
npx @xerg/cli audit \
--railway \
--project <project-id> \
--environment <environment-id> \
--service <service-id>
Multi-source config
Run a multi-source OpenClaw audit:
npx @xerg/cli audit --remote-config ~/.xerg/remotes.json
9. Hosted follow-up, push, and authentication
Guided hosted path:
npx @xerg/cli connect
npx @xerg/cli mcp-setup
npx @xerg/cli audit --push
npx @xerg/cli audit --push --dry-run
npx @xerg/cli push
npx @xerg/cli push --dry-run
npx @xerg/cli push --file ./audit-payload.json
npx @xerg/cli login
npx @xerg/cli logout
XERG_API_KEY=sk_live_or_test_key npx @xerg/cli audit --push
- use
connect when you want guided auth and an optional push prompt
- 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
10. CI and automation
Threshold gates:
npx @xerg/cli audit --fail-above-waste-rate 0.25
npx @xerg/cli audit --fail-above-waste-usd 100
npx @xerg/cli audit --json
npx @xerg/cli audit --compare --json
XERG_API_KEY for non-interactive hosted automation.
11. More CI gates and automation
Fail on confirmed waste rate:
npx @xerg/cli audit --fail-above-waste-rate 0.30
npx @xerg/cli audit --fail-above-waste-usd 50
npx @xerg/cli audit --push --fail-above-waste-rate 0.25
| Code | Meaning |
|---|
0 | success |
1 | general failure |
2 | no supported local runtime data found |
3 | waste threshold exceeded |
12. Troubleshooting shortcuts
Verbose local discovery:
npx @xerg/cli doctor --verbose
npx @xerg/cli doctor --runtime openclaw
npx @xerg/cli doctor --runtime hermes
npx @xerg/cli --help
npx @xerg/cli audit --help
npx @xerg/cli doctor --help
13. Common copy-paste sequences
First local audit:
Hermes local audit:
npx @xerg/cli doctor --runtime hermes
npx @xerg/cli audit --runtime hermes
npx @xerg/cli audit
# make one workflow or model change
npx @xerg/cli audit --compare
npx @xerg/cli audit --json > xerg-audit.json
npx @xerg/cli connect
npx @xerg/cli mcp-setup
14. Flag reference
| Flag | Applies to | What it does | |
|---|
| `—runtime [openclaw | hermes]` | doctor, audit | Chooses the local runtime explicitly |
--log-file [path] | doctor, audit | Points Xerg at one explicit local gateway log | |
--sessions-dir [path] | doctor, audit | Points Xerg at one explicit local sessions directory | |
--cursor-usage-csv [path] | doctor, audit | Uses a local Cursor usage export instead of runtime files | |
--since [duration] | audit | Limits the audit window, for example 24h, 7d, or 30m | |
--compare | audit | Compares against the newest compatible saved snapshot | |
--json | audit | Emits JSON output | |
--markdown | audit | Emits Markdown output | |
--db [path] | audit | Uses a custom SQLite path for local snapshot storage | |
--no-db | audit | Skips local persistence | |
--remote [user@host] | doctor, audit | Targets an SSH OpenClaw host | |
--remote-log-file [path] | doctor, audit | Overrides the remote OpenClaw log path | |
--remote-sessions-dir [path] | doctor, audit | Overrides the remote OpenClaw sessions path | |
--remote-config [path] | audit | Runs a multi-source remote OpenClaw audit | |
--keep-remote-files | audit | Keeps pulled remote files under ~/.xerg/remote-cache/ | |
--railway | doctor, audit | Targets a Railway OpenClaw service | |
--project [id] | doctor, audit | Chooses a Railway project explicitly | |
--environment [id] | doctor, audit | Chooses a Railway environment explicitly | |
--service [id] | doctor, audit | Chooses a Railway service explicitly | |
--push | audit | Pushes the summary after computing it | |
--dry-run | audit --push, push | Prints the payload instead of sending it | |
--file [path] | push | Pushes one saved payload file instead of the most recent cached audit | |
--fail-above-waste-rate [n] | audit | Exits 3 when waste rate is above the threshold | |
--fail-above-waste-usd [n] | audit | Exits 3 when confirmed waste dollars are above the threshold | |
--verbose | doctor, audit | Prints progress updates to stderr | |
-h, --help | root, doctor, audit, push | Prints help for the selected command | |
-v, --version | root | Prints the installed CLI version | |