retell-cli 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,92 @@ All notable changes to the Retell AI CLI will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.0] - 2026-04-16
+
+Bulk addition of CLI surface for Retell SDK resources that were previously unwrapped or partially wrapped. Bumped `retell-sdk` dependency to `^5.12.0`.
+
+### Added
+
+#### Calls (`calls`)
+- `calls create-phone` — create an outbound phone call (supports `--agent-override`, `--metadata`, `--dynamic-variables`, `--custom-sip-headers`, `--override-agent-id`, `--override-agent-version`, `--ignore-e164-validation`).
+- `calls create-web` — create a web call for browser-based agents.
+- `calls register-phone` — register a call for custom telephony.
+- `calls update <call_id>` — update metadata, custom attributes, dynamic variables, and data-storage setting.
+- `calls delete <call_id>` — delete a call and its data.
+- Note: `calls list` / `calls get` are intentionally omitted; use `transcripts list` / `transcripts get` / `transcripts search`.
+
+#### Batch Calls (`batch-calls`)
+- `batch-calls create` — schedule a batch of outbound calls from a JSON tasks file with optional `--call-time-window`, `--reserved-concurrency`, `--trigger-timestamp`.
+
+#### LLMs (`llms`)
+- `llms list`, `llms get <llm_id>`, `llms delete <llm_id>`.
+- `llms create` — via simple flags (`--general-prompt`, `--model`, `--s2s-model`, `--start-speaker`, `--begin-message`) or full `--file` body.
+- `llms update <llm_id> --file <path>` — full body update.
+
+#### Voices (`voices`)
+- `voices list`, `voices get <voice_id>`, `voices search`.
+- `voices add-resource` — add a community voice to the account library.
+- `voices clone` — clone a voice from one or more audio files (repeatable `--file`).
+
+#### Chats (`chats`) and Chat Agents (`chat-agents`)
+- `chats create`, `chats get`, `chats list`, `chats update`, `chats end`.
+- `chats complete` — send a user message to an existing chat and receive the agent's completion.
+- `chats sms` — create an SMS-backed chat session.
+- `chat-agents list/get/create/update/delete/versions/publish` — full chat agent lifecycle.
+
+#### Phone Numbers (CRUD gap filled)
+- `phone-numbers create` — purchase a new number and bind agents (reuses weighted-agent flags from `import`).
+- `phone-numbers update <phone_number>` — update bound agents, nickname, SIP auth (note: SDK uses `auth_username`/`auth_password` on update vs `sip_trunk_auth_username`/`sip_trunk_auth_password` on import; CLI flag `--sip-username/--sip-password` translates correctly), country allow-lists, webhook URLs.
+- `phone-numbers delete <phone_number>` — release a phone number.
+
+#### Flow Components (`flow-components`)
+- `flow-components list/get/create/update/delete` — CRUD for reusable conversation-flow components (create/update bodies via `--file`).
+
+#### Concurrency and MCP Tools
+- `concurrency get` — view the org's current call concurrency and limits.
+- `agents mcp-tools <agent_id> --mcp-id <id>` — list MCP tools available to an agent from a specific MCP server.
+
+### Changed
+
+- Bumped `retell-sdk` from `^5.10.3` to `^5.12.0`.
+- Extracted weighted-agent parsing from `phone-numbers/import.ts` into a shared `src/services/weighted-agents.ts` so `import`, `create`, and `update` can share a single implementation. Behavior of `phone-numbers import` is unchanged; its mutual-exclusion errors now flow through `handleSdkError` as `ValidationError` rather than via an inline `process.exit(1)`, giving consistent error shape with other commands.
+- Added a small `src/services/json-arg.ts` helper for flags that accept inline JSON or `@path` file references (`--metadata`, `--dynamic-variables`, `--custom-sip-headers`, etc.).
+
+### Tests
+
+- Added ~80 new test cases covering happy paths, flag parsing, validation errors, and SDK error passthrough for every new command, plus a dedicated test file for the weighted-agents service and json-arg helper.
+
+### Fixed (post-review)
+
+- `llms update --version` now sets `query_version` on the request params instead of a nonexistent body `version` field — the flag previously had no effect.
+- Numeric flag parsing (`--version`, `--limit`, `--area-code`, `--trigger-timestamp`, etc.) now rejects empty and whitespace-only strings. Centralized via `src/services/numeric-flag.ts`.
+- `calls update`, `chats update`, and `phone-numbers update` now require at least one mutation flag instead of silently sending an empty body to the SDK.
+- Body-as-file flags (`llms create/update`, `chat-agents create/update`, `flow-components create/update`, `calls create-phone/create-web --agent-override`, `batch-calls create --call-time-window`) now reject non-object JSON (arrays, null, scalars) with a clear `ValidationError` via new `readJsonObjectFile` helper.
+- README: per-command flag lists for `calls create-phone / create-web / register-phone` now reflect the actual supported flags on each command.
+- `phone-numbers create` help no longer claims `--country-code` defaults to US or `--number-provider` defaults to twilio (the CLI does not set these defaults); the SDK still applies those server-side.
+- `loadJsonArg` now throws a descriptive error for a bare `@` with no path.
+
+### Fixed (second review pass)
+
+- `chat-agents create` / `llms create` now reject `--file` combined with simple flags (previously the simple flags were silently ignored).
+- `phone-numbers update` can now clear nullable fields with an explicit empty string (`--nickname ""`, `--fallback-number ""`, `--inbound-webhook-url ""`, `--inbound-sms-webhook-url ""`, `--transport ""` map to `null` in the SDK request). Previously these were silently dropped.
+- `phone-numbers create` / `update` now validate `--transport` against `TLS`/`TCP`/`UDP` before the SDK call (previously typos passed through and produced opaque 400s).
+- `llms update` / `chat-agents update` / `flow-components update` now reject an empty `--file` body object, matching the empty-body guard already in place on `calls update` / `chats update` / `phone-numbers update`.
+- `phone-numbers import` no longer advertises `--inbound-sms-agents` / `--outbound-sms-agents`; SMS agent bindings are not supported on import per the SDK. Use `phone-numbers update` after import to bind SMS agents.
+- Pre-existing numeric flag call sites in `src/index.ts` (`transcripts list/analyze/search`, `agents list/get/update`, `tests cases/batches create`, `flows list/get/update` — `--limit`, `--engine-version`, `--latency-threshold`, `--silence-threshold`) migrated to the centralized `parseNumericFlag`. Invalid or whitespace-only values now produce a clear error instead of silently becoming `NaN`.
+- Weighted-agents parser now rejects empty `agent_id` (e.g. `:0.5`, `agent_1:0.5,:0.5`) with a clear error instead of emitting `{agent_id: "", weight: 0.5}`.
+
+### Fixed (fourth review pass)
+
+- `chats complete` now rejects empty `--chat-id` / `--content` via `requireNonEmpty` (was missed in the third-pass rollout). Commander treats `--flag ""` as a defined string, so the empty values would otherwise reach the SDK and surface as an opaque 400.
+- `applyWeightedAgents` now rejects empty-string agent flags (`--inbound-agent ""`, `--outbound-agent ""`, `--inbound-agents ""`, `--outbound-agents ""`, `--inbound-sms-agents ""`, `--outbound-sms-agents ""`) with a clear `VALIDATION_ERROR` instead of silently dropping the binding. Closes a hole where `phone-numbers create/update/import --inbound-agent ""` would ship with no inbound binding the user thought they'd set.
+- `phone-numbers update --termination-uri ""` / `--sip-username ""` / `--sip-password ""` now reject (these SDK fields are not nullable). `--allowed-inbound-country-list ""` / `--allowed-outbound-country-list ""` now clear the list (map to `null`) — matching the nullable-clearing pattern applied to the other update fields in the second pass.
+- Removed dead `parseWeightedAgents` re-export from `phone-numbers/import.ts` and the single test that only exercised the re-export (not behavior).
+
+### Known gaps
+
+- Knowledge-base `update` is still not exposed by the SDK (only `create/retrieve/list/delete/addSources/deleteSource`), so no CLI command was added there.
+
 ## [1.4.0] - 2026-01-27
 
 ### Added

package/README.md

@@ -8,10 +8,15 @@ Community-built command-line tool for Retell AI - designed to give AI assistants
 ## Features
 
 - **Transcript Management** - List, retrieve, and analyze call transcripts
-- **Agent Management** - Full CRUD for Retell AI agents (create, list, update, delete, versions)
-- **Phone Number Management** - List, retrieve, and import phone numbers
+- **Agent Management** - Full CRUD for Retell AI agents (create, list, update, delete, versions, MCP tools)
+- **Call Creation** - Launch phone, web, and SMS-chat calls; register custom-telephony calls; schedule batch calls
+- **Phone Number Management** - Purchase, import, list, update, and release phone numbers (with weighted agent routing)
+- **Chat Sessions** - Create and manage chat sessions, chat agents, SMS chats, and LLM completions
+- **LLM + Voice Resources** - CRUD Retell LLMs; browse, search, add, and clone voice resources
 - **Prompt Engineering** - Pull, edit, and update agent prompts
 - **Tool Management** - Full CRUD for agent tools (webhooks, custom functions, etc.)
+- **Flow Components** - Reusable conversation-flow components (CRUD)
+- **Concurrency Monitoring** - Check org-wide call concurrency and limits
 - **Multi-format Support** - Works with Retell LLM and Conversation Flows
 - **AI-Friendly** - JSON output by default for AI coding assistants
 - **Cross-Shell** - Works in bash, fish, zsh, and more
@@ -602,7 +607,7 @@ List all phone numbers in your account.
 **Example:**
 ```bash
 retell phone-numbers list
-retell phone-numbers list --fields phone_number,nickname,inbound_agent_id
+retell phone-numbers list --fields phone_number,nickname,inbound_agents,outbound_agents
 ```
 
 #### `retell phone-numbers get <phone_number> [options]`
@@ -615,7 +620,7 @@ Get details of a specific phone number.
 **Example:**
 ```bash
 retell phone-numbers get +14157774444
-retell phone-numbers get +14157774444 --fields phone_number,inbound_agent_id
+retell phone-numbers get +14157774444 --fields phone_number,inbound_agents,outbound_agents
 ```
 
 #### `retell phone-numbers import [options]`
@@ -628,6 +633,8 @@ Import a phone number from custom telephony (e.g., Twilio, Vonage).
 - `--nickname <name>` - Friendly name for reference
 - `--inbound-agent <id>` - Agent ID for inbound calls
 - `--outbound-agent <id>` - Agent ID for outbound calls
+- `--inbound-agents <spec>` - Weighted inbound agents, e.g. `agent_1:0.6,agent_2:0.4` (mutually exclusive with `--inbound-agent`)
+- `--outbound-agents <spec>` - Weighted outbound agents (same spec format as `--inbound-agents`)
 - `--sip-username <user>` - SIP trunk auth username
 - `--sip-password <pass>` - SIP trunk auth password
 - `--fields <fields>` - Comma-separated list of fields to return
@@ -781,6 +788,134 @@ retell transcripts analyze <call_id> --hotspots-only
 # 3. No jq or grep needed - direct JSON parsing!
 ```
 
+### Calls (create / update / delete)
+
+Call listing and retrieval stay under `transcripts`. Use `calls` to create and mutate calls.
+
+```bash
+# Outbound phone call
+retell calls create-phone --from-number +14157774444 --to-number +12137774445
+
+# Web call (browser-based agent)
+retell calls create-web --agent-id agent_xxx --metadata '{"session_id":"s1"}'
+
+# Register a call for custom telephony
+retell calls register-phone --agent-id agent_xxx --direction outbound
+
+# Update metadata / data storage on an existing call
+retell calls update call_abc123 --metadata '{"customer_id":"c_1"}' \
+  --data-storage-setting everything_except_pii
+
+# Delete a call and its data
+retell calls delete call_abc123
+```
+
+Shared on all three: `--metadata`, `--dynamic-variables`, `--fields`.
+
+- `create-phone` also: `--override-agent-id`, `--override-agent-version`, `--custom-sip-headers`, `--agent-override <path>` (path to JSON), `--ignore-e164-validation`.
+- `create-web` also: `--agent-version`, `--agent-override <path>`, `--current-node-id`, `--current-state`.
+- `register-phone` also: `--agent-version`, `--direction`, `--from-number`, `--to-number`.
+
+### Batch Calls
+
+```bash
+# Schedule a batch of outbound calls from a JSON tasks file
+retell batch-calls create \
+  --from-number +14157774444 \
+  --tasks tasks.json \
+  --name "April outreach" \
+  --reserved-concurrency 10
+
+# Optional: restrict calling windows
+retell batch-calls create --from-number +1 --tasks tasks.json \
+  --call-time-window window.json
+```
+
+### LLMs
+
+```bash
+retell llms list --fields llm_id,is_published
+retell llms get llm_abc
+retell llms create --general-prompt "You are a helpful agent." --model gpt-4.1
+retell llms create --file my-llm.json
+retell llms update llm_abc --file updates.json
+retell llms delete llm_abc
+```
+
+### Voices
+
+```bash
+retell voices list --fields voice_id,voice_name,provider
+retell voices get voice_abc
+retell voices search --search-query "warm female" --voice-provider elevenlabs
+retell voices add-resource --provider-voice-id pv_1 --voice-name "Allie"
+retell voices clone --voice-name "Dev Clone" --voice-provider elevenlabs --file sample.wav
+```
+
+### Chats
+
+```bash
+retell chats create --agent-id agent_xxx
+retell chats list --limit 10 --sort-order descending
+retell chats get chat_abc
+retell chats complete --chat-id chat_abc --content "What's the status?"
+retell chats sms --from-number +14157774444 --to-number +12137774445
+retell chats update chat_abc --metadata '{"k":"v"}'
+retell chats end chat_abc
+```
+
+### Chat Agents
+
+```bash
+retell chat-agents list
+retell chat-agents create --llm-id llm_abc --name "Support Chat"
+retell chat-agents get ca_abc --version 2
+retell chat-agents update ca_abc --file updates.json
+retell chat-agents versions ca_abc
+retell chat-agents publish ca_abc
+retell chat-agents delete ca_abc
+```
+
+### Phone Numbers (Full CRUD)
+
+```bash
+# Purchase a new number
+retell phone-numbers create --area-code 415 --nickname "Frontdesk" \
+  --inbound-agent agent_xxx
+
+# Update a purchased number (weighted agents + SIP)
+retell phone-numbers update +14157774444 \
+  --inbound-agents "agent_1:0.6,agent_2:0.4" \
+  --nickname "Support"
+
+# Release a number
+retell phone-numbers delete +14157774444
+```
+
+### Flow Components
+
+```bash
+retell flow-components list
+retell flow-components get comp_abc
+retell flow-components create --file component.json
+retell flow-components update comp_abc --file updates.json
+retell flow-components delete comp_abc
+```
+
+### Concurrency
+
+```bash
+retell concurrency get
+retell concurrency get --fields concurrency_limit,current_concurrency
+```
+
+### Agent MCP Tools
+
+```bash
+retell agents mcp-tools agent_abc --mcp-id mcp_1
+retell agents mcp-tools agent_abc --mcp-id mcp_1 --component-id comp_1 --version 3
+```
+
 ## Common Workflows
 
 ### Analyzing Failed Calls