Skip to main content
If you install @xerg/cli globally, replace npx @xerg/cli@latest with xerg.

​
Using a coding agent? Install the skill instead

If you work inside Claude Code, Codex, Cursor, or another agent that supports the Agent Skills standard, the fastest path is to install the Xerg skill and ask your agent to audit your AI spend:
The agent runs the CLI itself, finds your local data, and explains the findings — including the per-agent spend breakdown. See agent clients for client-specific setup.

​
1. Run the first-run flow

init is interactive and walks you through your first audit. It:
  • checks local OpenClaw, Hermes, and Claude Code defaults (current Hermes uses read-only ~/.hermes/state.db; Claude Code transcripts are read from ~/.claude/projects/)
  • asks you to choose the runtime when more than one is detected
  • runs the first audit and stores the local snapshot
  • prints the normal terminal summary
  • offers optional hosted follow-up after the audit succeeds
If no local data is found, init prints the default paths it checked plus the next-step commands for:
  • explicit local paths
  • Claude Code transcripts elsewhere via --claude-code-dir
  • Cursor usage CSV exports via --cursor-usage-csv
  • event payloads from any framework via npx @xerg/cli@latest ingest --file payload.json
  • optional OpenClaw trace collection via npx @xerg/cli@latest collect openclaw; stop with Ctrl-C, then review the local audit
  • optional certified Hermes trace enrichment via npx @xerg/cli@latest collect hermes --state-db ~/.hermes/state.db; the first-party observer remains the recommended parity path
  • npx @xerg/cli@latest audit --remote user@host
  • npx @xerg/cli@latest audit --railway
Remote SSH and Railway audits are OpenClaw-only. QM is deliberately not auto-detected. A QM administrator first chooses strict direct or Fly-contained collection, installs the reviewed export views, and provisions the deployment identity key. For the certified Fly path:
See secure QM setup. Never paste a QM database URL or identity key into a command or chat.

​
2. Make one workflow or model change, then compare

--compare looks for the newest compatible cached snapshot on your machine and adds before and after deltas. If no compatible baseline exists yet, Xerg does not fail. It adds a note telling you to run the same audit again after a fix.

​
3. Use direct commands when you want explicit control

Use the direct flows instead of init when you need non-interactive behavior, CI gates, or a specific output mode immediately:
If more than one local runtime is present, add --runtime openclaw, --runtime hermes, or --runtime claude-code. QM is always explicit with --runtime qm plus a saved connection, --fly-app, or --qm-snapshot.

​
4. Export or automate

Shareable Markdown:
Machine-readable JSON:
Fail CI if confirmed waste is too high:
Push an audit summary to the Xerg API explicitly:

​
5. Optional hosted follow-up

If you want hosted features after the first local result, create a free workspace (or use an existing one):
  • activate opens Xerg for explicit browser approval, shows the exact organization/plan/environment, encrypts the workspace credential to this CLI, and stores it with owner-only environment binding; add --organization-id org_... when the intended workspace is known, --connect-only to stop without an audit or push, or --push-latest to push the cached audit
  • mcp-setup prints or writes hosted MCP config for Cursor, Claude Code, Codex, or another client (hosted MCP requires Pro or Enterprise)
  • the hosted dashboard shows pushed audits, sources, trends, Optimizations, policies, and workspace API keys
  • the same workspace API key works for CLI push and hosted MCP
You can skip both and keep using Xerg locally. If you have not run a local audit yet, use npx @xerg/cli@latest activate instead. It connects the workspace, detects a supported local source, runs the audit, and pushes it.

​
Common next steps