Skip to main content
npx @xerg/cli@latest doctor is the fastest way to confirm that Xerg can see local OpenClaw, Hermes, or Claude Code data before you run an audit. QM checks are explicit because they inspect a configured database export or snapshot. Examples use npx @xerg/cli@latest. If you installed the CLI globally, substitute xerg.

​
Local checks

The default compact report answers four questions: what source was inspected, whether it is auditable, which truth limitation matters, and the exact command to run next. Use --details for complete checked paths, source lists, pricing evidence, defaults, notes, and readiness distinctions. Because --details is a human projection, it cannot be combined with --json. Xerg can report:
  • the default gateway pattern
  • the default sessions pattern
  • detected source files
  • notes about what is missing
Every runtime and transport mode also supports machine-readable doctor output:
The JSON envelope contains the CLI version, runtime/product name, canAudit, checked sources, the runtime-specific evidence report, notes, a shell-safe recommendedCommand, and pricing-catalog provenance. Agents should execute that recommendation rather than reconstructing an audit command from prose. Use --verbose when you want progress messages on stderr while doctor is checking paths and transports. For local sources it also prints an extraction-coverage appendix to stdout after the main report: per source file, how many calls were extracted and which economic signals the parser found (tokens, observed cost, cache tokens, stop reasons, tool names, latency), plus any unpriced models. Detected files that produced zero included calls are listed too, with their full local paths and an explicit calls: 0 row — including total extraction failure, where a file parses but no record carries usage. Use it to spot silent extraction gaps before they show up as $0 spend. This per-file breakdown is local-only; audit reports and pushed payloads carry a count-only note instead. --details --verbose combines the complete readiness report with this appendix without duplicating it. For local OpenClaw data, doctor reports the gateway and transcript call counts used to resolve source authority. The CLI doctor has no --since filter, so these diagnostics cover the available detected evidence; the subsequent audit resolves authority again inside its requested window. If both kinds produce calls, transcripts are authoritative and gateway economics are excluded. doctor --verbose lists non-empty gateway files under Excluded by source authority, separately from files that produced zero included calls. Paths remain local; the audit summary and push wire receive only a count-and-kind note. Use --sessions-dir by itself for transcript-only diagnostics or --log-file by itself for gateway-only diagnostics. Use explicit local paths when your data is not in the defaults:
If OpenClaw and Hermes are both present locally, pass --runtime openclaw or --runtime hermes so doctor checks the exact runtime you mean. Claude Code checks are always explicit via --runtime claude-code. Hermes doctor opens state.db read-only and reports schema/read failures, observer installation, current-process liveness, malformed records, unmatched sessions, writer drop counts, and request-reconciliation readiness (full, partial, or none). observerLiveness distinguishes not-installed, installed-not-loaded, running, stopped, and stale operation; observerHealth reports the selected process heartbeat and writer health. The legacy hermesObserverStatus remains available, but stale can now describe missing current-process liveness when no audit-window verdict exists. The strict --require-observer-live preflight exits 5 unless a process is running and its writer is not known unhealthy. Observer liveness is a continuous production-coverage concern, not a test-only prerequisite. Run the strict preflight before any new Xerg-directed Hermes workload. A sequence-dependent or observer-validation workload must stop on failure. Existing and historical aggregate audits may continue after a mandatory warning; restarting never reconstructs their old request sequence. Lifecycle observation is separate from liveness: pinned v0.20.1 is complete-capable, pinned v0.20.6/v0.21.0 is partial, and unverified versions are unknown. A running writer with zero local drops cannot prove that all callbacks were delivered; upstream suppression counts remain unavailable. Even complete-capable evidence needs actual unique correlations before Xerg can report timing or request order. The adapter targets schemas 25–26; exact Hermes v0.20.1/v0.20.6/v0.21.0 runtime acceptance remains pending. Older formats and schema 27+ are best-effort, uncertified readers. For schema 22 and newer, doctor also warns when the usage table omits task from the expected six-column primary key. Hermes may then have dropped distinct task rows, so totals may be floors for affected periods; totals remain exact for rows Hermes recorded. Xerg reports this locally and never repairs the source. The observer is optional; an observer ledger or Hermes trace capture by itself is not an auditable monetary source. Xerg 0.24.0 was not certified for Hermes v0.20.x terminal mechanics. Its generated and truncated terminal-byte metrics could be understated even when an observer ledger parsed successfully. State-only economics remained sound for rows Hermes successfully recorded. Upgrade Xerg and the Hermes observer to 0.24.2; affected terminal quantities then render as “At least” when only a conservative floor is available, and doctor can enforce live observer preflight. To inspect Claude Code session transcripts:
Claude Code doctor reports the projects directory it checked (default ~/.claude/projects), the transcript files it found, and the exact audit command to run next.

​
Hermes profile checks

--hermes-profile <name> selects one consistent home. --all-hermes-profiles reports per-profile readiness and identity/conflict diagnostics without creating registry bindings. With --require-observer-live, every included profile must have a live healthy observer. Legacy unscoped evidence is accepted only for an explicitly paired single-profile audit. Invalid profiles, divergent copies, and unresolved registry history remain actionable limitations, not automatic repairs.

​
QM checks

Database and Fly doctor verify the exact xerg_export/v1 fingerprint, required column names and types, bounded-query indexes, identity-key continuity, and collection provenance. Strict direct mode refuses a role that can read base tables, write, own the database/schema, create in the export schema, inherit another role, or bypass row-level security. Fly-contained mode reports the broader core role as warnings, requires the explicit process-containment controls, and states that database least privilege is false. Snapshot doctor validates the strict schema, digest, trailer, limits, pseudonymous IDs, and internally consistent trust metadata. Run xerg connect qm --print-sql for the views plus strict-reader setup, or --print-views-sql for Fly-contained views and indexes only. Public direct commands accept only XERG_QM_DATABASE_URL or a suffixed variant and never accept a DSN argument. See secure QM setup. To inspect a local Cursor usage export instead:
Cursor CSV doctor validates the file shape, row count, date range, and current pricing coverage.

​
SSH checks

SSH doctor checks:
  • SSH connectivity
  • whether rsync exists locally and remotely
  • default remote paths
  • optional custom remote paths when you pass --remote-log-file or --remote-sessions-dir
Remote doctor checks availability and file counts without downloading and normalizing the evidence. The subsequent remote audit resolves OpenClaw source authority after the files are pulled locally. Custom remote paths:

​
Railway checks

By default, Railway doctor uses the Railway service linked to the current working directory in your local railway CLI context. If railway link in this directory points at a database, sidecar, or another non-OpenClaw service, doctor can authenticate successfully but still report that the linked service is unreachable or has no OpenClaw data. Re-run railway link in the directory where you invoke Xerg and choose the OpenClaw app service. Use explicit --project, --environment, and --service values when you want a deterministic Railway target instead of the service linked to the current directory. You can also target a specific service:
Railway doctor checks:
  • whether the railway CLI is installed
  • whether the railway CLI is authenticated
  • whether the target service is reachable
  • default and alternate OpenClaw paths
  • optional custom remote paths when you pass --remote-log-file or --remote-sessions-dir
Railway checks these paths by default:
  • /tmp/openclaw for gateway logs
  • ~/.openclaw/agents for session files
  • /data/.clawdbot/agents/main/sessions as an alternate session directory when the default one is empty

​
When doctor says no data

If doctor cannot find any local OpenClaw or Hermes data:
  • for Hermes, verify the selected profile’s state.db exists or pass --hermes-profile / --state-db
  • for legacy Hermes or OpenClaw data, pass explicit paths with --log-file and --sessions-dir
  • run npx @xerg/cli@latest doctor --runtime claude-code if you use Claude Code; transcripts are created automatically under ~/.claude/projects
  • run npx @xerg/cli@latest doctor --remote user@host to inspect an SSH target directly from your machine
  • run npx @xerg/cli@latest doctor --railway to inspect a linked Railway service
  • use --project, --environment, and --service when you want a deterministic Railway target instead of the service linked to the current directory
  • run npx @xerg/cli@latest audit --remote user@host or npx @xerg/cli@latest audit --railway when the data lives on another machine or service; see remote audits for the full workflow
  • remote audits still pull telemetry to the machine where you run Xerg and analyze it locally
QM is not part of this auto-detection path. Use doctor --runtime qm after the operator profile and secrets exist.