DocsCLI & SDKsThe cave CLI

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:

terminal

cd public/cli
pnpm build

The 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 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

terminal

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

Wrapping agents in depth →

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.

Wrapping agents

Supported agents, driven by a data registry.

MIT

TypeScript SDK

When you'd rather call the gateway in code.

MIT