@xerg/cli 0.2.0 → 0.4.0

package/package.json

@@ -1,8 +1,20 @@
 {
   "name": "@xerg/cli",
-  "version": "0.2.0",
-  "description": "Audit OpenClaw workflows in dollars, compare fixes, and export daily spend and waste trends.",
-  "keywords": ["ai", "agents", "finops", "llm", "openclaw", "cost", "cli", "cursor", "analytics"],
+  "version": "0.4.0",
+  "description": "Audit OpenClaw and Hermes workflows in dollars, compare fixes, and export daily spend and waste trends.",
+  "keywords": [
+    "xerg",
+    "ai",
+    "agents",
+    "finops",
+    "llm",
+    "openclaw",
+    "hermes",
+    "cost",
+    "cli",
+    "cursor",
+    "analytics"
+  ],
   "homepage": "https://xerg.ai",
   "repository": {
     "type": "git",
@@ -40,6 +52,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
+    "@inquirer/prompts": "^8.4.1",
     "better-sqlite3": "^11.10.0"
   },
   "devDependencies": {

package/skills/xerg/SKILL.md

@@ -1,23 +1,30 @@
 ---
 name: xerg
-description: Audit OpenClaw workflows in dollars. Local-first audits with compare mode, remote and Railway support, CI gates, and structured recommendations.
+description: Audit OpenClaw and Hermes workflows in dollars. Local-first audits with init, compare mode, OpenClaw remote support, CI gates, and optional hosted follow-up.
 ---
 
 # Xerg
 
 Use `xerg` if it is already installed. If not, use `npx @xerg/cli` with the same arguments.
 
-Xerg audits OpenClaw workflows in dollars, not tokens. It reads gateway logs and session transcripts, surfaces five spend categories across confirmed waste and savings opportunities, and helps you measure fixes with `--compare`.
+Xerg audits OpenClaw and Hermes workflows in dollars, not tokens. It reads gateway logs and session transcripts, surfaces confirmed waste plus savings opportunities, and helps you measure fixes with `--compare`.
 
-Local audits need no account. No data leaves your machine unless you explicitly `--push` results to the Xerg API.
+Local audits need no account. Hosted sync and hosted MCP are optional paid workspace features. No data leaves your machine unless you explicitly push results to Xerg Cloud.
 
 ## Quick Start
 
+```bash
+xerg init
+xerg audit --compare
+```
+
+Use direct commands when you need explicit control, non-interactive behavior, JSON output, or CI gates:
+
 ```bash
 xerg doctor
-xerg doctor --verbose
 xerg audit
-xerg audit --compare
+xerg audit --json
+xerg audit --fail-above-waste-rate 0.30
 ```
 
 ## Inputs
@@ -27,6 +34,9 @@ Xerg needs one of these source inputs:
 - Local OpenClaw data at the default paths:
   - `/tmp/openclaw/openclaw-*.log`
   - `~/.openclaw/agents/*/sessions/*.jsonl`
+- Local Hermes data at the default paths:
+  - `~/.hermes/logs/agent.log*` with `gateway.log*` fallback
+  - `~/.hermes/sessions/`
 - Explicit paths via `--log-file` and/or `--sessions-dir`
 - An SSH target via `--remote`
 - A Railway target via `--railway`
@@ -35,13 +45,24 @@ Xerg needs one of these source inputs:
 Additional requirements:
 
 - `--compare` needs at least one previously stored compatible local snapshot
-- Pushing needs auth via `XERG_API_KEY`, `~/.xerg/config.json`, or `xerg login`
-- SSH audits require `ssh` and `rsync` on your local `PATH`
-- Railway audits require the `railway` CLI on your local `PATH`
+- Pushing needs auth via `XERG_API_KEY`, `~/.xerg/config.json`, or browser credentials from `xerg login`
+- SSH audits require `ssh` and `rsync` on your local `PATH` and are OpenClaw-only in this phase
+- Railway audits require the `railway` CLI on your local `PATH` and are OpenClaw-only in this phase
 
 ## Default Flow
 
-1. Detect sources first when paths or connectivity are uncertain:
+1. Start with the default first-run path when you want the fastest local result:
+
+```bash
+xerg init
+```
+
+- `init` detects local OpenClaw or Hermes data
+- it runs a first audit with local snapshot persistence enabled
+- it offers optional hosted follow-up after the audit completes
+- if no local data is found, it prints explicit local-path commands plus remote OpenClaw-only guidance
+
+2. Detect sources directly when paths or connectivity are uncertain:
 
 ```bash
 xerg doctor
@@ -53,13 +74,15 @@ xerg doctor --railway
 - `xerg doctor --verbose` shows progress on stderr while Xerg checks local paths or remote transports
 - If local defaults are empty, prefer `xerg doctor --remote ...` or `xerg doctor --railway` instead of guessing paths
 
-2. Run a baseline audit:
+3. Run a baseline audit explicitly when you want direct control:
 
 ```bash
 xerg audit
+xerg audit --runtime openclaw
+xerg audit --runtime hermes
 ```
 
-3. Choose the right output mode for the task:
+4. Choose the right output mode for the task:
 
 ```bash
 xerg audit
@@ -71,21 +94,27 @@ xerg audit --markdown
 - `xerg audit --json` is best for automation and agents
 - `xerg audit --markdown` is best for a shareable report
 
-4. After a workflow or model change, measure the delta:
+5. After a workflow or model change, measure the delta:
 
 ```bash
 xerg audit --compare
 xerg audit --compare --json
 ```
 
-5. Export or push only when needed:
+6. Export, push, or hosted-setup only when needed:
 
 ```bash
 xerg audit --markdown > xerg-audit.md
+xerg connect
+xerg mcp-setup
 xerg audit --push
 xerg push
 ```
 
+- `connect` is the guided hosted path: it reuses existing auth, prompts before browser login when needed, and offers to push the latest audit
+- `mcp-setup` prints or writes hosted MCP config for Cursor, Claude Code, or another client
+- local audits and compare remain available if you skip hosted setup
+
 ## Source Selection
 
 Local defaults:
@@ -94,11 +123,15 @@ Local defaults:
 xerg audit
 ```
 
+If both OpenClaw and Hermes are present locally, pass `--runtime openclaw` or `--runtime hermes` explicitly.
+
 Explicit local paths:
 
 ```bash
-xerg audit --log-file /path/to/openclaw.log
-xerg audit --sessions-dir /path/to/sessions
+xerg audit --runtime openclaw --log-file /path/to/openclaw.log
+xerg audit --runtime openclaw --sessions-dir /path/to/sessions
+xerg audit --runtime hermes --log-file ~/.hermes/logs/agent.log
+xerg audit --runtime hermes --sessions-dir ~/.hermes/sessions
 ```
 
 SSH remote:
@@ -166,7 +199,7 @@ Documented exit codes:
 
 - `0` success
 - `1` runtime error
-- `2` no OpenClaw data found
+- `2` no supported local runtime data found
 - `3` threshold exceeded
 
 Automation can branch on those codes instead of scraping terminal output.
@@ -202,6 +235,6 @@ Before finalizing work that used Xerg:
 - `--compare` and `--no-db` cannot be used together
 - Xerg is local-first: it stores economic metadata and audit snapshots locally, not prompt or response content
 - `XERG_API_KEY` is recommended for CI and non-interactive automation
-- If browser auth is needed locally, use `xerg login`; remove stored credentials with `xerg logout`
+- If browser auth is needed without the hosted setup flow, use `xerg login`; remove stored credentials with `xerg logout`
 - Pilot: [xerg.ai/pilot](https://xerg.ai/pilot)
 - Support: `query@xerg.ai`