The cave CLI
The CLI is one TypeScript file with no runtime dependencies. It builds to one executable exposed as both caveman and cave. Logged out, it starts the local proxy, wraps agents, delegates compression to the engine, and reads local stats.
What it does locally
Local commands shell out to the public Go binaries. CAVEMAN_PROXY_BIN selects the proxy binary, and CAVEMAN_ENGINE_BIN selects the engine binary. If a binary is missing, the CLI prints a local setup path instead of pretending the command succeeded.
Built from source today
Build from source today:
cd public/cli
pnpm buildThe package is not documented as published until registry ownership is confirmed.
Local verbs
These commands need local binaries and your provider key:
| Command | What it does |
|---|---|
caveman start | launch caveman-proxy (from CAVEMAN_PROXY_BIN or PATH) |
caveman wrap [agent] | start an agent with provider base URLs pointed at the proxy |
caveman compress | pipe a payload through the engine (--type <content-type>, --toon) |
caveman convert | pixel-compress installed agent skills to PNG pages; --dry-run first, --revert restores the original — see pixel compression |
caveman verify | confirm a request actually reached the proxy (polls local stats for a fresh row, exits non-zero if none show up) |
caveman snippets [id] [--app <slug>] | print a framework integration snippet from the recipe registry; bare caveman snippets lists every recipe id |
caveman evals run | run the local quality gate (non-zero exit on any failure) |
caveman stats | print the local inferred spend summary |
caveman version | print the version |
caveman start # proxy comes up on 127.0.0.1:8787
caveman wrap claude # starts Claude Code with ANTHROPIC_BASE_URL set
echo '{"a":[1,1,1]}' | caveman compress --type json
caveman convert --dry-run # preview pixel-compressing installed skills
caveman verify --app checkout --timeout 30
caveman snippets openai-py --app checkoutcaveman verify is the first-request sanity check: point an agent at the gateway, run one request, then run caveman verify to confirm the proxy actually saw it (--app filters by attribution slug, --timeout/--timeout-ms bound how long it polls). No fresh row within the window is a non-zero exit with a hint to check the base URL and that caveman start is running.
caveman snippets prints ready-to-paste integration code for one SDK or framework at a time — the same recipe registry backs the framework integrations pages on this site, so a snippet reads identically whether you copy it from the CLI or the docs.
Account commands
The CLI source also includes login and account commands. They are real commands in public/cli/src/index.ts; they call hosted API endpoints and require a configured account.
| Command | What it does |
|---|---|
| Command group | Notes |
| --- | --- |
login · logout · whoami | device-flow auth and identity |
projects · keys · providers | account and provider setup |
score · costs · plan · traces · opportunities · experiments | reports returned by the hosted API |
receipts · billing | account-only commands; output comes from the API or a local receipt bundle |
Honesty rule
providers verify echoes the API response; tests assert it does not return a hardcoded placeholder. Plan output keeps the server's basis label and does not multiply per-day figures into monthly projections.
Where your credentials live
Non-secret config sits at ~/.caveman-cloud/config.json with mode 0600. Auth tokens go to the OS keychain when available, with a ~/.caveman/credentials fallback. CI can set CAVE_TOKEN; logged-out account commands exit non-zero instead of hanging.