hotato sweep connects once and ranks the turn-taking moments across your
recent calls, in three steps you can also run alone:
hotato connect <stack>-- store one stack's credentials, locally.hotato pull-- bulk-fetch your recent recordings into a folder.hotato sweep-- pull, then score every pulled call and write one offline dashboard ranking the turn-taking moments it measured.
Everything scores offline; the only network call is the direct recording download from vendor to machine. Your audio and keys stay between you and the vendor.
hotato connect vapi --api-key <key>
Runs a live auth check (lists one recent call), then writes the
credentials to ~/.hotato/connections.json (mode 0600, dir 0700). The
key never prints and reaches only the vendor's API. Credentials also fall
back to the environment:
VAPI_API_KEY=<key> hotato connect vapi
Per-stack credentials:
| Stack | Flags (or env vars) |
|---|---|
| vapi | --api-key / VAPI_API_KEY |
| retell | --api-key / RETELL_API_KEY |
| twilio | --account-sid --auth-token / TWILIO_ACCOUNT_SID TWILIO_AUTH_TOKEN |
| bland | --api-key / BLAND_API_KEY |
| elevenlabs | --api-key / ELEVENLABS_API_KEY |
| synthflow | --api-key / SYNTHFLOW_API_KEY (+ --model-id / SYNTHFLOW_MODEL_ID to list) |
| millis | --api-key / MILLIS_API_KEY (+ --base-url for the EU region) |
| cartesia | --api-key / CARTESIA_API_KEY (+ --agent-id / CARTESIA_AGENT_ID to list) |
Retell has no list endpoint, so connect retell stores the key and
validates it on first pull. --no-verify skips the live check for any
stack. LiveKit and Pipecat capture in your own infra: connect with hotato setup --stack livekit|pipecat instead.
Once connected, --stack and credential flags are optional for pull and
sweep when exactly one stack is connected.
hotato pull --stack vapi --since 7d --limit 50
hotato pull # the only connected stack
Lists recent recordings via the vendor's verified endpoint, then downloads
each into hotato-pull-<stack>/ (override --out DIR). --since accepts
7d, 12h, 30m, 2w. A recording that fails to fetch is a clean skip
with its reason; the pull continues. A pull in which every listed
recording failed to fetch exits 2 -- an outage, not a completed pull -- so
a cron or CI wrapper reading only the exit code sees it red.
Retell has no verified list endpoint. Pull it from explicit ids instead:
hotato pull --stack retell --call-id c1 --call-id c2
For Twilio, --call-id values are Recording SIDs (RE...).
Mono / mixed stacks (bland, elevenlabs, synthflow, millis, cartesia)
produce one combined recording with no per-party channel; attributing
talk-over needs --allow-mono, and results stay indicative only:
hotato pull --stack bland --allow-mono --limit 20
hotato sweep --stack vapi --since 7d
hotato sweep # the only connected stack
Pulls (as above) into hotato-sweep-<stack>/ (override --dir), runs the
same analyze scoring with nothing to configure, and writes one
self-contained offline HTML dashboard (hotato-sweep-<stack>.html, override
--out): every call's candidate moments ranked, with an inline player on the
top ones. --format json emits the candidates plus a pull summary instead.
Dual-channel stacks get separated scoring. Mono/mixed stacks need
--allow-mono; without per-party separation their calls land in the
dashboard's Skipped section.
A candidate is one measured timing moment you review and label with hotato fixture create: a timestamp and a magnitude, not a verdict on intent.
See docs/ADAPTER-STATUS.md for the full map: which
stacks auto-pull dual-channel, which arrive as one mixed channel, which
capture in your own infra, and which endpoint each uses.
You have caught a timing moment on a recorded call. The next move is
originating one against your live agent on demand, into this same
pull -> score path: docs/DRIVE-A-CALL.md.