CLI cheat sheet

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:

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:

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:

npx @xerg/cli@latest doctor
npx @xerg/cli@latest audit

Force a specific runtime:

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:

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. Hermes:

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 and Hermes trace collection. Claude Code (defaults to ~/.claude/projects/):

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:

npx @xerg/cli@latest doctor --cursor-usage-csv ~/Downloads/usage-events.csv

Run the audit:

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 and run:

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:

npx @xerg/cli@latest audit

JSON for automation:

npx @xerg/cli@latest audit --json

Markdown for sharing:

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:

npx @xerg/cli@latest audit --compare
npx @xerg/cli@latest audit --compare --json

Limit the comparison window:

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:

npx @xerg/cli@latest doctor --remote deploy@prod.example.com

Audit:

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:

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:

npx @xerg/cli@latest doctor --railway

Audit the linked service:

npx @xerg/cli@latest audit --railway

Use explicit Railway IDs:

npx @xerg/cli@latest doctor \
  --railway \
  --project <project-id> \
  --environment <environment-id> \
  --service <service-id>

npx @xerg/cli@latest audit \
  --railway \
  --project <project-id> \
  --environment <environment-id> \
  --service <service-id>

Multi-source config

Run a multi-source OpenClaw audit:

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:

npx @xerg/cli@latest connect
npx @xerg/cli@latest mcp-setup

Push as part of the audit:

npx @xerg/cli@latest audit --push

Preview the exact push payload:

npx @xerg/cli@latest audit --push --dry-run

Push the newest cached snapshot later:

npx @xerg/cli@latest push
npx @xerg/cli@latest push --dry-run

Push a saved payload file:

npx @xerg/cli@latest push --file ./audit-payload.json

Browser auth:

npx @xerg/cli@latest login
npx @xerg/cli@latest login --replace
npx @xerg/cli@latest logout

Non-interactive auth:

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:

npx @xerg/cli@latest audit --fail-above-waste-rate 0.25
npx @xerg/cli@latest audit --fail-above-waste-usd 100

Machine-readable output:

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:

npx @xerg/cli@latest audit --fail-above-waste-rate 0.30

Fail on confirmed waste dollars:

npx @xerg/cli@latest audit --fail-above-waste-usd 50

Push and gate in one command:

npx @xerg/cli@latest audit --push --fail-above-waste-rate 0.25

Remote CI gate for OpenClaw:

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:

npx @xerg/cli@latest doctor --verbose

Force a runtime when local auto-detection is ambiguous:

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:

npx @xerg/cli@latest doctor --remote deploy@prod.example.com
npx @xerg/cli@latest doctor --railway

Check the CLI help:

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:

npx @xerg/cli@latest init

Hermes local audit:

npx @xerg/cli@latest doctor --runtime hermes
npx @xerg/cli@latest audit --runtime hermes

Before and after workflow test:

npx @xerg/cli@latest audit
# make one workflow or model change
npx @xerg/cli@latest audit --compare

Export JSON for an agent:

npx @xerg/cli@latest audit --json > xerg-audit.json

Remote OpenClaw audit over SSH:

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:

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

Concepts

Hosted workspace

Automate and share

Releases

CLI cheat sheet

1. Init-first path

2. Command map

3. Choose the right starting command

4. Direct local audits

5. Point Xerg at explicit local paths

6. Analyze a Cursor usage CSV

6b. Audit any framework with an event payload

7. Output modes and compare

8. Remote OpenClaw audits

SSH

Railway

Multi-source config

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

10. CI and automation

11. More CI gates and automation

12. Troubleshooting shortcuts

13. Common copy-paste sequences

14. Flag reference

​1. Init-first path

​2. Command map

​3. Choose the right starting command

​4. Direct local audits

​5. Point Xerg at explicit local paths

​6. Analyze a Cursor usage CSV

​6b. Audit any framework with an event payload

​7. Output modes and compare

​8. Remote OpenClaw audits

​SSH

​Railway

​Multi-source config

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

​10. CI and automation

​11. More CI gates and automation

​12. Troubleshooting shortcuts

​13. Common copy-paste sequences

​14. Flag reference

1. Init-first path

2. Command map

3. Choose the right starting command

4. Direct local audits

5. Point Xerg at explicit local paths

6. Analyze a Cursor usage CSV

6b. Audit any framework with an event payload

7. Output modes and compare

8. Remote OpenClaw audits

SSH

Railway

Multi-source config

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

10. CI and automation

11. More CI gates and automation

12. Troubleshooting shortcuts

13. Common copy-paste sequences

14. Flag reference