agents,phone,conversations: post-ship review fixes + fresh defaults (v0.3.1)

Codex (gpt-5.4, xhigh) post-ship review of v0.3.0 caught six concrete
bugs + a batch of stale defaults and outdated copy. All fixed here.
Review report at docs/reference/post-ship-review-v0.3.0.md.

Response-shape bugs
- `agents llms`: now reads `llms[].llm` (not non-existent `llm_id`) and
  displays the fields that actually exist — max_context_limit,
  max_tokens_limit, supports_{image,document,parallel_tool}_input,
  available_reasoning_efforts, deprecation_info. Human-mode table was
  rendering blank IDs before; JSON mode always worked.
- `agents knowledge search`: now reads the spec-correct
  KnowledgeBaseContentSearchResult shape (document.{id,name,type} +
  search_snippet[].{value,is_hit} + score) and bolds matching
  snippet segments. Previous wiring looked for flat document_name /
  content that never existed.

Outbound-call body drift
- `phone call --dynamic-variables` deep-merges into any existing
  client-data.dynamic_variables map instead of wholesale replacement.
  Help text had promised merge; code now matches.
- `phone call --record` errors client-side on SIP-trunk numbers
  (exit 3). The OpenAPI spec only defines call_recording_enabled on
  the Twilio outbound-call body; SIP was silently dropping the field.
- `phone call --ringing-timeout-secs` clap-validated to 1..=999 per
  TelephonyCallConfig.ringing_timeout_secs spec range.

Shared client plumbing
- New `ElevenLabsClient::get_bytes` for binary-body GETs. Used by
  `conversations audio`. Replaces a private helper that had drifted
  from `check_status` (no detail.message extraction, no redaction
  parity). Same secret-redacting + short-message error shape as every
  other command.

Fresh defaults (cross-checked against the vendored OpenAPI spec + the
April 2026 ElevenLabs models doc)
- `agents create --llm`: gemini-3.1-flash-lite-preview →
  gemini-2.5-flash. Matches PromptAgentAPIModel.llm spec default.
- `agents create --max-duration-seconds`: 300 → 600. Matches
  ConversationConfig.max_duration_seconds spec default.
- AGENT_TTS_MODEL_IDS reordered: eleven_flash_v2_5 first (recommended),
  eleven_turbo_v2{,_5} last and marked DEPRECATED in gotchas/help.
- Two stale `gemini-3.1-flash-preview` help examples replaced with
  `gemini-2.5-flash` (the preview isn't in the LLM enum).
- Dropped "Creator+ at the time of writing" unverified tier claims;
  we now say "requires a plan with expressive TTS" and surface the
  API's own error string as the fallback.

Docs hygiene
- README: homebrew tap 199-biotechnologies/tap → paperfoot/tap; drop
  "grounded against elevenlabs-js v2.43" claim in favour of a pointer
  to the vendored OpenAPI spec; command summary lists every v0.3.0
  addition (agents llms/signed-url/knowledge, conversations audio,
  phone call --client-data / --record / --ringing-timeout-secs).
- docs/reference/spec-audit-v0.2.2.md renamed to
  spec-audit-pre-v0.3.0.md with a banner flagging it as historical.
- docs/reference/README.md fixed: removed broken reference to a
  non-existent audit-prompt.md; added "Historical audits" index
  linking the two captured reports.

Test suite still green (36 suites). cargo fmt + cargo clippy clean.
CHANGELOG: [0.3.1] — 2026-04-21.

Author: longevityboris

CHANGELOG.md

@@ -3,6 +3,92 @@
 All notable changes to `elevenlabs-cli` are listed here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning is [SemVer](https://semver.org).
 
+## [0.3.1] — 2026-04-21
+
+Post-ship review of v0.3.0 (Codex, gpt-5.4 xhigh) caught six real bugs +
+a batch of stale defaults. All fixed here. Review report vendored at
+`docs/reference/post-ship-review-v0.3.0.md`.
+
+### Fixed — response-shape bugs in the new v0.3.0 commands
+
+- `agents llms` now parses the real response shape. The spec's
+  `LLMListResponseModel` returns `llms[].llm` (plus `max_tokens_limit`,
+  `max_context_limit`, `supports_image_input`, `supports_document_input`,
+  `supports_parallel_tool_calls`, `available_reasoning_efforts`,
+  `deprecation_info`). The initial wiring looked for `llm_id` / `id` /
+  `display_name` / `provider` — which don't exist — so the human-mode
+  table was rendering blank IDs. JSON mode always worked.
+- `agents knowledge search` now parses the real response shape. The
+  spec's `KnowledgeBaseContentSearchResult` returns
+  `document.{id,name,type}` + `search_snippet[].{value,is_hit}` + `score`.
+  The initial wiring looked for flat `document_name` / `document_id` +
+  `content` / `chunk` — fields that don't exist. TTY output now renders
+  doc name + type + id, bolds the matching snippet segments, and shows
+  the relevance score.
+
+### Fixed — outbound-call body drift
+
+- **P0** `phone call --dynamic-variables` no longer replaces the full
+  `dynamic_variables` object when passed alongside `--client-data`.
+  Previous behaviour dropped any keys present in
+  `--client-data.dynamic_variables` that weren't also in
+  `--dynamic-variables`. Now deep-merges (incoming wins on key clash,
+  unrelated keys preserved). Help text promised a merge — now the code
+  matches.
+- **P0** `phone call --record` is now rejected client-side on SIP-trunk
+  numbers. The OpenAPI spec only defines `call_recording_enabled` on
+  the Twilio outbound-call body; SIP silently dropped the field. Exit 3
+  with a concrete suggestion when the provider isn't Twilio.
+- `phone call --ringing-timeout-secs` is now range-validated in clap
+  (1-999, matching `TelephonyCallConfig.ringing_timeout_secs` in the
+  spec). Bad values fail fast with an exit-3 clap error instead of a
+  422 at the server.
+
+### Fixed — shared client plumbing
+
+- `conversations audio` now goes through a new `ElevenLabsClient::get_bytes`
+  method that reuses `check_status` — so large error pages, proxy HTML,
+  and `detail.message`-style bodies get the same short, secret-redacted
+  error shape every other command produces. v0.3.0's private helper in
+  `conversations.rs` had drifted from `check_status` by skipping the
+  message extractor.
+
+### Changed — defaults now track the OpenAPI spec + public docs
+
+- `agents create --llm` default: `gemini-3.1-flash-lite-preview` →
+  `gemini-2.5-flash`. Matches `PromptAgentAPIModel.llm` default in the
+  current OpenAPI spec and the April 2026 ElevenLabs blog post naming
+  Gemini 2.5 Flash as the recommended default for Conversational AI.
+- `agents create --max-duration-seconds` default: 300 → 600. Matches
+  `ConversationConfig.max_duration_seconds` default in the OpenAPI spec.
+- The `AGENT_TTS_MODEL_IDS` allowlist is unchanged (server-enforced)
+  but re-ordered with `eleven_flash_v2_5` first and
+  `eleven_turbo_v2{_5,}` at the end, now marked **DEPRECATED** in the
+  gotchas / help copy per the public models docs.
+- Two stale `gemini-3.1-flash-preview` help examples replaced with
+  `gemini-2.5-flash` (the preview model isn't in the `LLM` enum).
+
+### Changed — doc copy hygiene
+
+- Dropped "Creator+ at the time of writing" tier language from
+  `agents create --help`, `agents update --help`, `agent-info`, and
+  `cli.rs`. The expressive-mode docs don't name a tier and tiers have
+  shifted; we now just say "requires a plan with expressive TTS — if
+  the API returns 'Expressive TTS is not allowed', upgrade".
+- README: homebrew tap switched from the deprecated
+  `199-biotechnologies/tap` to `paperfoot/tap`. The "grounded against
+  elevenlabs-js v2.43 SDK" statement is replaced by a pointer to the
+  vendored `docs/reference/openapi.elevenlabs.json` snapshot.
+- README command summary now lists every v0.3.0 addition (`agents llms`,
+  `agents signed-url`, `agents knowledge {list,search,refresh}`,
+  `conversations audio`, and the new `phone call` override flags).
+- `docs/reference/spec-audit-v0.2.2.md` renamed to
+  `spec-audit-pre-v0.3.0.md` with a banner flagging it as historical
+  and pointing at the v0.3.0 post-ship review.
+- `docs/reference/README.md` fixed: removed a broken reference to a
+  non-existent `audit-prompt.md`; added a "Historical audits" section
+  linking the two captured reports.
+
 ## [0.3.0] — 2026-04-21
 
 Driven by an OpenAPI spec audit (Codex, GPT-5.4 xhigh) against the

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "elevenlabs"
-version = "0.3.0"
+version = "0.3.1"
 edition = "2024"
 rust-version = "1.85"
 description = "Agent-friendly CLI for the ElevenLabs AI audio platform (TTS, STT, voices, agents, music)"

Cargo.toml

@@ -45,7 +45,7 @@ elevenlabs phone call agent_xxx --from-id phnum_yyy --to +14155551234
 
 Every command auto-switches between **coloured human output** (terminal) and **JSON envelopes** (piped / `--json`). Exit codes are semantic (`0=ok, 1=transient, 2=config, 3=bad input, 4=rate limited`). Errors carry a machine-readable `code` and an actionable `suggestion` an AI agent can follow literally.
 
-**Grounded against the official [elevenlabs-js v2.43 SDK](https://github.com/elevenlabs/elevenlabs-js)** — every request/response type in this CLI was verified against the Fern-generated schema that ElevenLabs ships for their own SDK.
+**Grounded against the live OpenAPI spec** — every request/response type is verified against the vendored snapshot at [`docs/reference/openapi.elevenlabs.json`](docs/reference/openapi.elevenlabs.json), refreshable in one command via [`./docs/reference/refresh.sh`](docs/reference/refresh.sh).
 
 ---
 
@@ -56,8 +56,9 @@ Every command auto-switches between **coloured human output** (terminal) and **J
 cargo install elevenlabs          # crate name is `elevenlabs`, binary name is `elevenlabs`
 
 # Homebrew (macOS, Linux)
-brew tap 199-biotechnologies/tap
+brew tap paperfoot/tap
 brew install elevenlabs
+# (old tap `199-biotechnologies/tap` is deprecated — `brew untap` it after switching)
 
 # Prebuilt binaries — Linux, macOS (x86_64 + arm64), Windows
 curl -L https://github.com/paperfoot/elevenlabs-cli/releases/latest/download/elevenlabs-$(uname -s)-$(uname -m).tar.gz | tar xz
@@ -271,21 +272,30 @@ elevenlabs agents show <agent_id>        # alias: get
 elevenlabs agents create <name>
     --system-prompt "..."
     [--first-message "Hi, how can I help?"]
-    [--voice-id ID] [--language en] [--llm gemini-3.1-flash-lite-preview]
+    [--voice-id ID] [--language en] [--llm gemini-2.5-flash]
     [--temperature 0.5] [--model-id eleven_flash_v2_5]
-    [--expressive-mode] [--max-duration-seconds 300]
+    [--expressive-mode] [--max-duration-seconds 600]
+    [--voicemail-detection] [--voicemail-message "..."]
 elevenlabs agents update <agent_id> --patch patch.json
-elevenlabs agents delete <agent_id>      # alias: rm
+elevenlabs agents duplicate <agent_id> [--name "Clone"]
+elevenlabs agents delete <agent_id>                 # alias: rm
+elevenlabs agents llms                              # list the backend-accepted LLM allowlist
+elevenlabs agents signed-url <agent_id>             # short-lived widget/web URL
 elevenlabs agents add-knowledge <agent_id> <name> (--url URL | --file PATH | --text "...")
+elevenlabs agents knowledge list [--search TERM]    # aliases: ls
+elevenlabs agents knowledge search <query> [--document-id ID] [--limit 10]
+elevenlabs agents knowledge refresh <document_id>
 
-# --model-id allowlist: eleven_turbo_v2, eleven_turbo_v2_5, eleven_flash_v2,
-# eleven_flash_v2_5, eleven_multilingual_v2, eleven_v3_conversational.
-# Pass `eleven_v3` and you'll get an exit-3 error — that's the dialogue/ttv
-# model, not the realtime agent model. Use eleven_v3_conversational instead.
-# --expressive-mode auto-upgrades to eleven_v3_conversational.
+# --model-id allowlist: eleven_flash_v2_5 (recommended), eleven_flash_v2,
+# eleven_multilingual_v2, eleven_v3_conversational. eleven_turbo_v2_5 and
+# eleven_turbo_v2 are accepted but deprecated — prefer flash equivalents.
+# Passing `eleven_v3` is caught pre-flight (exit 3) — that's the dialogue/ttv
+# model, not the realtime agent model. --expressive-mode auto-upgrades to
+# eleven_v3_conversational.
 
 elevenlabs conversations list [--agent-id ID] [--page-size 30] [--cursor TOKEN]
 elevenlabs conversations show <conversation_id>
+elevenlabs conversations audio <conversation_id> [-o call.mp3]
 ```
 
 </details>
@@ -296,7 +306,10 @@ elevenlabs conversations show <conversation_id>
 ```bash
 elevenlabs phone list
 elevenlabs phone call <agent_id> --from-id <phone_number_id> --to +14155551234
-    [--dynamic-variables '{"name":"Alex"}']     # or @vars.json
+    [--dynamic-variables '{"name":"Alex"}']         # or @vars.json
+    [--client-data '{"conversation_config_override": {...}}']
+    [--record]                                       # Twilio only
+    [--ringing-timeout-secs 25]                      # 1-999
 ```
 
 </details>

README.md

@@ -26,9 +26,13 @@ upstream API change or before opening a coverage-audit PR.
 # Compare CLI coverage to spec:
 diff <(awk '{print $1, $2}' docs/reference/endpoints-inventory.txt | sort -u) \
      <(awk '{print $1, $2}' docs/reference/cli-endpoints.txt | sort -u)
-
-# Or let Codex do it (see docs/reference/audit-prompt.md for the brief
-# we used to seed an audit in 2026-04).
 ```
 
+## Historical audits
+
+- [`spec-audit-pre-v0.3.0.md`](spec-audit-pre-v0.3.0.md) — Codex audit of
+  v0.2.2 that drove the v0.3.0 release (2026-04-21).
+- [`post-ship-review-v0.3.0.md`](post-ship-review-v0.3.0.md) — follow-up
+  review of the v0.3.0 work that drove v0.3.1 (same day).
+
 Upstream-spec URL: https://api.elevenlabs.io/openapi.json