@xerg/cli 0.1.3 → 0.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -13
- package/dist/index.js +3605 -36
- package/dist/index.js.map +1 -0
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,53 +1,125 @@
|
|
|
1
1
|
# xerg
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Audit OpenClaw agent spend, waste, and before/after improvements.
|
|
4
4
|
|
|
5
|
-
It reads your
|
|
5
|
+
Xerg audits OpenClaw workflows in dollars, not tokens. It reads your gateway logs and session transcripts, shows where money is leaking, classifies waste into five categories, and lets you re-run the same audit with `--compare` so you can see what changed after a fix.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## 30-second quick start
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
-
|
|
10
|
+
npx @xerg/cli doctor
|
|
11
|
+
npx @xerg/cli audit
|
|
12
|
+
npx @xerg/cli audit --compare
|
|
11
13
|
```
|
|
12
14
|
|
|
13
|
-
|
|
15
|
+
Prefer a global install?
|
|
14
16
|
|
|
15
17
|
```bash
|
|
16
|
-
|
|
18
|
+
npm install -g @xerg/cli
|
|
19
|
+
xerg doctor
|
|
20
|
+
xerg audit
|
|
17
21
|
```
|
|
18
22
|
|
|
19
|
-
|
|
23
|
+
## Supported runtime
|
|
20
24
|
|
|
21
|
-
|
|
22
|
-
|
|
25
|
+
`@xerg/cli` supports Node `20`, `22`, and `24`.
|
|
26
|
+
|
|
27
|
+
If you are developing in this repo, `.nvmrc` still pins the default local toolchain to Node `24.14.0`.
|
|
28
|
+
|
|
29
|
+
## Sample output
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
Total spend: $148.00
|
|
33
|
+
Observed spend: $105.00
|
|
34
|
+
Estimated spend: $43.00
|
|
35
|
+
|
|
36
|
+
Waste taxonomy
|
|
37
|
+
- Retry waste: $12.40
|
|
38
|
+
- Context bloat: $18.90
|
|
39
|
+
- Loop waste: $7.10
|
|
40
|
+
- Downgrade candidates: $4.80
|
|
41
|
+
- Idle waste: $3.37
|
|
42
|
+
|
|
43
|
+
First savings test
|
|
44
|
+
- Move heartbeat_monitor from Claude Opus to Sonnet
|
|
23
45
|
```
|
|
24
46
|
|
|
25
47
|
## Commands
|
|
26
48
|
|
|
27
|
-
Inspect local audit readiness:
|
|
49
|
+
- Inspect local audit readiness:
|
|
28
50
|
|
|
29
51
|
```bash
|
|
30
52
|
xerg doctor
|
|
31
53
|
```
|
|
32
54
|
|
|
33
|
-
Run the first audit:
|
|
55
|
+
- Run the first audit:
|
|
34
56
|
|
|
35
57
|
```bash
|
|
36
58
|
xerg audit
|
|
37
59
|
```
|
|
38
60
|
|
|
39
|
-
Compare the latest run against the newest compatible prior local snapshot:
|
|
61
|
+
- Compare the latest run against the newest compatible prior local snapshot:
|
|
40
62
|
|
|
41
63
|
```bash
|
|
42
64
|
xerg audit --compare
|
|
43
65
|
```
|
|
44
66
|
|
|
45
|
-
Audit a specific window:
|
|
67
|
+
- Audit a specific window:
|
|
46
68
|
|
|
47
69
|
```bash
|
|
48
70
|
xerg audit --since 24h --compare
|
|
49
71
|
```
|
|
50
72
|
|
|
73
|
+
## Works where your OpenClaw logs live
|
|
74
|
+
|
|
75
|
+
- Local machine: yes
|
|
76
|
+
- VPS or remote server: yes
|
|
77
|
+
- If OpenClaw runs remotely, SSH into the machine where the logs live and run Xerg there
|
|
78
|
+
- Or point Xerg at exported files directly with flags
|
|
79
|
+
|
|
80
|
+
Remote prerequisites:
|
|
81
|
+
|
|
82
|
+
- SSH audits require `ssh` and `rsync` on your `PATH`
|
|
83
|
+
- Railway audits require the `railway` CLI on your `PATH`
|
|
84
|
+
|
|
85
|
+
## Default paths
|
|
86
|
+
|
|
87
|
+
By default, Xerg checks:
|
|
88
|
+
|
|
89
|
+
- `/tmp/openclaw/openclaw-*.log`
|
|
90
|
+
- `~/.openclaw/agents/*/sessions/*.jsonl`
|
|
91
|
+
|
|
92
|
+
Use explicit paths when needed:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
xerg audit --log-file /path/to/openclaw.log
|
|
96
|
+
xerg audit --sessions-dir /path/to/sessions
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Authentication and config
|
|
100
|
+
|
|
101
|
+
Push commands resolve credentials in this order:
|
|
102
|
+
|
|
103
|
+
1. `XERG_API_KEY`
|
|
104
|
+
2. `~/.xerg/config.json`
|
|
105
|
+
3. `xerg login` browser credentials stored at `~/.config/xerg/credentials.json`
|
|
106
|
+
|
|
107
|
+
Optional API URL overrides:
|
|
108
|
+
|
|
109
|
+
- `XERG_API_URL`
|
|
110
|
+
- `apiUrl` in `~/.xerg/config.json`
|
|
111
|
+
|
|
112
|
+
Example `~/.xerg/config.json`:
|
|
113
|
+
|
|
114
|
+
```json
|
|
115
|
+
{
|
|
116
|
+
"apiKey": "sk_live_or_test_key",
|
|
117
|
+
"apiUrl": "https://api.xerg.ai"
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`xerg login` stores a browser-issued token in `~/.config/xerg/credentials.json`. That token store is separate from `~/.xerg/config.json`.
|
|
122
|
+
|
|
51
123
|
## What the audit shows
|
|
52
124
|
|
|
53
125
|
- Total spend by workflow and model, in dollars
|
|
@@ -59,3 +131,21 @@ xerg audit --since 24h --compare
|
|
|
59
131
|
## Privacy
|
|
60
132
|
|
|
61
133
|
Xerg v0 stores economic metadata and audit summaries locally. It does not store prompt or response content.
|
|
134
|
+
|
|
135
|
+
## Exit codes
|
|
136
|
+
|
|
137
|
+
- `0`: success
|
|
138
|
+
- `1`: general failure
|
|
139
|
+
- `2`: no OpenClaw data was found
|
|
140
|
+
- `3`: a `--fail-above-waste-rate` or `--fail-above-waste-usd` threshold was exceeded
|
|
141
|
+
|
|
142
|
+
## Troubleshooting
|
|
143
|
+
|
|
144
|
+
- `better-sqlite3` is a native dependency. If install fails, retry on a supported Node version and make sure standard native build tooling is available for your platform.
|
|
145
|
+
- If `xerg audit --remote ...` fails before pulling files, verify that both `ssh` and `rsync` are installed and reachable on your `PATH`.
|
|
146
|
+
- If `xerg audit --railway` fails immediately, verify that the `railway` CLI is installed, authenticated, and can access the target project.
|
|
147
|
+
|
|
148
|
+
## Pilot and support
|
|
149
|
+
|
|
150
|
+
- Pilot: [xerg.ai/pilot](https://xerg.ai/pilot)
|
|
151
|
+
- Support: `query@xerg.ai`
|