> ## 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.

# Quickstart

> Use the init-first local path, compare the next run, and only opt into hosted follow-up if you want it.

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:

```bash theme={null}
npx skills add xergai/skills
```

The agent runs the CLI itself, finds your local data, and explains the findings — including the per-agent spend breakdown. See [agent clients](/docs/agent-clients) for client-specific setup.

## 1. Run the first-run flow

```bash theme={null}
npx @xerg/cli@latest init
```

`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.

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

```bash theme={null}
npx @xerg/cli@latest audit --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:

```bash theme={null}
npx @xerg/cli@latest doctor
npx @xerg/cli@latest audit
npx @xerg/cli@latest audit --json
npx @xerg/cli@latest audit --markdown
```

If more than one local runtime is present, add `--runtime openclaw`, `--runtime hermes`, or `--runtime claude-code`.

## 4. Export or automate

Shareable Markdown:

```bash theme={null}
npx @xerg/cli@latest audit --markdown > xerg-audit.md
```

Machine-readable JSON:

```bash theme={null}
npx @xerg/cli@latest audit --json
```

Fail CI if confirmed waste is too high:

```bash theme={null}
npx @xerg/cli@latest audit --fail-above-waste-rate 0.30
```

Push an audit summary to the Xerg API explicitly:

```bash theme={null}
npx @xerg/cli@latest audit --push
```

## 5. Optional hosted follow-up

If you want hosted features after the first local result, create a free workspace (or use an existing one):

```bash theme={null}
npx @xerg/cli@latest connect
npx @xerg/cli@latest mcp-setup
```

* `connect` reuses existing auth when present, or starts browser login and offers to push the latest 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.

## Common next steps

* Use [init](/docs/init) when you want the exact first-run behavior documented command-by-command.
* Use [skill bundle](/docs/skill-bundle) and [agent clients](/docs/agent-clients) to set up the skill in your coding agent.
* Use [audit](/docs/audit) to learn the full command surface.
* Use [remote audits](/docs/remote-audits) if OpenClaw is running on SSH or Railway.
* Use [compare](/docs/compare) if you want to understand how snapshot compatibility works.
* Use [waste taxonomy](/docs/waste-taxonomy) and [metrics](/docs/metrics) if you want the concepts behind the report.
* Use [hosted dashboard](/docs/hosted-dashboard), [authentication and push](/docs/auth-and-push), [hosted MCP](/docs/hosted-mcp), or [optimizations and policies](/docs/optimizations-and-policies) if you want the hosted workflow after your first audit.