> ## 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. # CLI cheat sheet > A sequenced Xerg CLI reference covering init-first onboarding, direct audit flows, hosted follow-up, remote OpenClaw audits, and CI gates. Examples use `npx @xerg/cli@latest`. If you installed the CLI globally, substitute `xerg`. > Remote SSH, Railway, and `--remote-config` flows are OpenClaw-only. 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: ```bash theme={null} npx @xerg/cli@latest init npx @xerg/cli@latest audit --compare npx @xerg/cli@latest connect npx @xerg/cli@latest mcp-setup ``` 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 * `connect`: handles hosted auth and offers to push the latest audit * `mcp-setup`: prints or writes hosted MCP config for a supported client Quick utility commands: ```bash theme={null} npx @xerg/cli@latest --help npx @xerg/cli@latest --version npx @xerg/cli@latest -v ``` Use these when you want the top-level command list or just the installed CLI version. ## 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 | | Audit any framework's events | `ingest --file` | Your framework is not a built-in source and you exported a Xerg event payload | | 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 | | Declare a run or workflow outcome | `outcome` | You want cost-per-outcome ("was it worth it") in your audits | | 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 | | Switch stored workspace credentials | `login --replace` | This machine is already logged into another Xerg workspace | | 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@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 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` ## 4. Direct local audits Default local detection: ```bash theme={null} npx @xerg/cli@latest doctor npx @xerg/cli@latest audit ``` Force a specific runtime: ```bash theme={null} npx @xerg/cli@latest doctor --runtime openclaw npx @xerg/cli@latest doctor --runtime hermes npx @xerg/cli@latest doctor --runtime claude-code npx @xerg/cli@latest audit --runtime openclaw npx @xerg/cli@latest audit --runtime hermes npx @xerg/cli@latest audit --runtime claude-code ``` 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: ```bash theme={null} npx @xerg/cli@latest doctor --runtime openclaw --log-file /path/to/openclaw.log npx @xerg/cli@latest doctor --runtime openclaw --sessions-dir /path/to/sessions npx @xerg/cli@latest audit --runtime openclaw --log-file /path/to/openclaw.log npx @xerg/cli@latest audit --runtime openclaw --sessions-dir /path/to/sessions npx @xerg/cli@latest collect openclaw --output ./openclaw.capture.jsonl npx @xerg/cli@latest audit --otlp-file ./openclaw.capture.jsonl ``` 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](/docs/openclaw-traces). Hermes: ```bash theme={null} npx @xerg/cli@latest doctor --runtime hermes --state-db ~/.hermes/state.db npx @xerg/cli@latest audit --runtime hermes --state-db ~/.hermes/state.db npx @xerg/cli@latest audit --runtime hermes --hermes-events-dir ~/.hermes/xerg/events npx @xerg/cli@latest collect hermes --state-db ~/.hermes/state.db npx @xerg/cli@latest audit --runtime hermes --state-db ~/.hermes/state.db --otlp-file ./hermes.capture.jsonl ``` `--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](/docs/hermes-analysis) and [Hermes trace collection](/docs/hermes-traces). Claude Code (defaults to `~/.claude/projects/`): ```bash theme={null} npx @xerg/cli@latest doctor --runtime claude-code npx @xerg/cli@latest doctor --runtime claude-code --claude-code-dir /path/to/projects npx @xerg/cli@latest audit --runtime claude-code npx @xerg/cli@latest audit --runtime claude-code --claude-code-dir /path/to/projects ``` 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: ```bash theme={null} npx @xerg/cli@latest doctor --cursor-usage-csv ~/Downloads/usage-events.csv ``` Run the audit: ```bash theme={null} npx @xerg/cli@latest audit --cursor-usage-csv ~/Downloads/usage-events.csv npx @xerg/cli@latest audit --cursor-usage-csv ~/Downloads/usage-events.csv --json ``` 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 retry, loop, or runtime structure and no true workflow traces, so Cursor audits produce Cursor-specific findings (like `cache-carryover` and `max-mode-concentration`) rather than structural ones. ## 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](/docs/ingest) and run: ```bash theme={null} npx @xerg/cli@latest ingest --file payload.json npx @xerg/cli@latest ingest --file payload.json --json npx @xerg/cli@latest ingest --file payload.json --compare npx @xerg/cli@latest ingest --file payload.json --push ``` The full audit pipeline (findings, compare, push) runs on the payload. ## 7. Output modes and compare Human-readable terminal report: ```bash theme={null} npx @xerg/cli@latest audit ``` JSON for automation: ```bash theme={null} npx @xerg/cli@latest audit --json ``` Markdown for sharing: ```bash theme={null} npx @xerg/cli@latest audit --markdown > xerg-audit.md ``` Remember: * `--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: ```bash theme={null} npx @xerg/cli@latest audit --compare npx @xerg/cli@latest audit --compare --json ``` Limit the comparison window: ```bash theme={null} npx @xerg/cli@latest audit --since 24h --compare npx @xerg/cli@latest audit --since 7d --compare ``` Important: * `--compare` needs saved local snapshots * `--compare` and `--no-db` cannot be used together ## 8. Remote OpenClaw audits ### SSH Inspect first: ```bash theme={null} npx @xerg/cli@latest doctor --remote deploy@prod.example.com ``` Audit: ```bash theme={null} npx @xerg/cli@latest audit --remote deploy@prod.example.com npx @xerg/cli@latest audit --remote deploy@prod.example.com --since 24h ``` Custom remote paths: ```bash theme={null} npx @xerg/cli@latest doctor \ --remote deploy@prod.example.com \ --remote-log-file /var/log/openclaw \ --remote-sessions-dir /srv/openclaw/sessions npx @xerg/cli@latest audit \ --remote deploy@prod.example.com \ --remote-log-file /var/log/openclaw \ --remote-sessions-dir /srv/openclaw/sessions ``` ### Railway Inspect the linked service: ```bash theme={null} npx @xerg/cli@latest doctor --railway ``` Audit the linked service: ```bash theme={null} npx @xerg/cli@latest audit --railway ``` Use explicit Railway IDs: ```bash theme={null} npx @xerg/cli@latest doctor \ --railway \ --project \ --environment \ --service npx @xerg/cli@latest audit \ --railway \ --project \ --environment \ --service ``` ### Multi-source config Run a multi-source OpenClaw audit: ```bash theme={null} npx @xerg/cli@latest audit --remote-config ~/.xerg/remotes.json ``` Use this when one command needs to inspect several SSH and Railway sources. ## 9. Hosted follow-up, dashboard, push, and authentication Guided hosted path: ```bash theme={null} npx @xerg/cli@latest connect npx @xerg/cli@latest mcp-setup ``` Push as part of the audit: ```bash theme={null} npx @xerg/cli@latest audit --push ``` Preview the exact push payload: ```bash theme={null} npx @xerg/cli@latest audit --push --dry-run ``` Push the newest cached snapshot later: ```bash theme={null} npx @xerg/cli@latest push npx @xerg/cli@latest push --dry-run ``` Push a saved payload file: ```bash theme={null} npx @xerg/cli@latest push --file ./audit-payload.json ``` Browser auth: ```bash theme={null} npx @xerg/cli@latest login npx @xerg/cli@latest login --replace npx @xerg/cli@latest logout ``` Non-interactive auth: ```bash theme={null} XERG_API_KEY=sk_live_or_test_key npx @xerg/cli@latest audit --push ``` Useful distinction: * 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 * use the hosted dashboard when you want pushed audit history, sources, trends, Optimizations, policies, or workspace API keys ## 10. CI and automation Threshold gates: ```bash theme={null} npx @xerg/cli@latest audit --fail-above-waste-rate 0.25 npx @xerg/cli@latest audit --fail-above-waste-usd 100 ``` Machine-readable output: ```bash theme={null} npx @xerg/cli@latest audit --json npx @xerg/cli@latest audit --compare --json ``` Use `XERG_API_KEY` for non-interactive hosted automation. ## 11. More CI gates and automation Fail on confirmed waste rate: ```bash theme={null} npx @xerg/cli@latest audit --fail-above-waste-rate 0.30 ``` Fail on confirmed waste dollars: ```bash theme={null} npx @xerg/cli@latest audit --fail-above-waste-usd 50 ``` Push and gate in one command: ```bash theme={null} npx @xerg/cli@latest audit --push --fail-above-waste-rate 0.25 ``` Remote CI gate for OpenClaw: ```bash theme={null} npx @xerg/cli@latest audit --remote deploy@prod.example.com --fail-above-waste-rate 0.20 ``` Exit codes: | Code | Meaning | | ---- | ------------------------------------- | | `0` | success | | `1` | general failure | | `2` | no supported local runtime data found | | `3` | waste threshold exceeded | ## 12. Troubleshooting shortcuts Verbose local discovery: ```bash theme={null} npx @xerg/cli@latest doctor --verbose ``` Force a runtime when local auto-detection is ambiguous: ```bash theme={null} npx @xerg/cli@latest doctor --runtime openclaw npx @xerg/cli@latest doctor --runtime hermes npx @xerg/cli@latest doctor --runtime claude-code ``` Check a remote target directly: ```bash theme={null} npx @xerg/cli@latest doctor --remote deploy@prod.example.com npx @xerg/cli@latest doctor --railway ``` Check the CLI help: ```bash theme={null} npx @xerg/cli@latest --help npx @xerg/cli@latest audit --help npx @xerg/cli@latest doctor --help ``` ## 13. Common copy-paste sequences First local audit: ```bash theme={null} npx @xerg/cli@latest init ``` Hermes local audit: ```bash theme={null} npx @xerg/cli@latest doctor --runtime hermes npx @xerg/cli@latest audit --runtime hermes ``` Before and after workflow test: ```bash theme={null} npx @xerg/cli@latest audit # make one workflow or model change npx @xerg/cli@latest audit --compare ``` Export JSON for an agent: ```bash theme={null} npx @xerg/cli@latest audit --json > xerg-audit.json ``` Remote OpenClaw audit over SSH: ```bash theme={null} npx @xerg/cli@latest doctor --remote deploy@prod.example.com npx @xerg/cli@latest audit --remote deploy@prod.example.com --since 24h ``` Push into the hosted Xerg workspace: ```bash theme={null} npx @xerg/cli@latest connect npx @xerg/cli@latest mcp-setup ``` ## 14. Flag reference `ingest` accepts the same output, persistence, compare, and push flags as `audit` (`--since`, `--json`, `--markdown`, `--db`, `--no-db`, `--compare`, `--push`, `--dry-run`, `--verbose`). | Flag | Applies to | What it does | | | | ------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------ | | \`--runtime \[openclaw | hermes | claude-code]\` | `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 | | | | `--otlp-file [path]` | `audit` | Audits an independent OpenClaw capture by default; with `--runtime hermes`, enriches an auditable `state.db` from a certified Hermes capture | | | | `--state-db [path]` | `doctor`, `audit`, `collect hermes` | Uses a specific read-only Hermes database; required for certified Hermes trace reconciliation | | | | `--hermes-events-dir [path]` | `doctor`, `audit`, `collect hermes` | Uses a specific first-party Hermes observer ledger | | | | `--claude-code-dir [path]` | `doctor`, `audit` | Points Xerg at a Claude Code projects directory other than `~/.claude/projects/` | | | | `--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 JSON snapshot 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]` | `ingest`, `push` | For `ingest`: audits a Xerg event payload from any framework. For `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 | | | | `--port [n]` | `collect openclaw`, `collect hermes` | Chooses the loopback OTLP/HTTP port (default `4318`) | | | | `--output [path]` | `collect openclaw`, `collect hermes` | Chooses a no-overwrite sanitized capture path | | | | `-h`, `--help` | root, `doctor`, `audit`, `push` | Prints help for the selected command | | | | `-v`, `--version` | root | Prints the installed CLI version | | |