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 four-command 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. Four-command path
If you only remember four commands, remember these:doctor: checks whether Xerg can see your local source filesaudit: runs the baseline auditaudit --compare: compares against the newest compatible saved snapshotaudit --push: sends the resulting summary to the hosted Xerg API
2. Command map
| Goal | Command | Use when |
|---|---|---|
| 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 |
| 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 |
| 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:- 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]ornpx @xerg/cli doctor --railway
4. Pick the source you want to audit
| Source | Best first command | Notes |
|---|---|---|
| Local OpenClaw | npx @xerg/cli doctor --runtime openclaw | Use this when both local runtimes exist and you want OpenClaw specifically |
| Local Hermes | npx @xerg/cli doctor --runtime hermes | Hermes support is local-only in this phase |
| Local auto-detect | npx @xerg/cli doctor | Best when only one supported local runtime is present |
| Local Cursor CSV | npx @xerg/cli doctor --cursor-usage-csv [file] | Uses exported usage rows instead of runtime logs and transcripts |
| Remote OpenClaw over SSH | npx @xerg/cli doctor --remote [user@host] | Pulls remote files to your machine and analyzes them locally |
| Remote OpenClaw on Railway | npx @xerg/cli doctor --railway | Uses your linked Railway context unless you pass explicit IDs |
5. Local runtime basics
Default local detection:--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
6. Point Xerg at explicit local paths
OpenClaw:- use
doctorfirst when you are not sure the paths are correct - use
auditoncedoctorshows the files you expect
7. Analyze a Cursor usage CSV
Inspect the CSV first:8. Output modes
Human-readable terminal report:--jsonand--markdownare mutually exclusive- plain
auditis best for manual inspection --jsonis best for agents and scripts
9. Compare and local snapshot storage
Compare against the newest compatible saved audit:--compareneeds saved local snapshots--compareand--no-dbcannot be used together
10. Remote OpenClaw audits
SSH
Inspect first:Railway
Inspect the linked service:Multi-source config
Run a multi-source OpenClaw audit:11. Push and authentication
Push as part of the audit:- use
audit --pushwhen you are computing a fresh audit right now - use
pushwhen you already have a saved audit snapshot and only want to send it
12. CI gates and automation
Fail on confirmed waste rate:| Code | Meaning |
|---|---|
0 | success |
1 | general failure |
2 | no supported local runtime data found |
3 | waste threshold exceeded |
13. Troubleshooting shortcuts
Verbose local discovery:14. Common copy-paste sequences
First local audit:15. 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 |