Retell CLI: Ship Voice Agent Updates Without Breaking Prod

It's Retell's official command-line client, announced in their August 3, 2026 changelog. Install it with npm install --global @retell-ai/retell-cli (Node 22 or later), then run retell auth login. The official docs page is about 40 lines long and stops at retell list-agents, which is why I'm writing this.

The first thing worth knowing: it isn't hand-written.Every command is generated from Retell's OpenAPI catalog. Version 0.47.0 ships 110 commands, one per API operation, named after the endpoint: create-agent, update-phone-number, list-calls, create-batch-test and so on. The package has had 66 releases since July 22, and 0.47.0 landed on November 1. Pin the version in CI. It moves weekly.

The second thing: it's thin. There are no retries, no auto-pagination (you pass --pagination-key yourself), a 60-second request timeout, and every failure exits with code 1 and prints Retell API request failed (422): {...}to stderr. That's fine for scripts. It's just not a framework.

Set RETELL_API_KEYand you're done. I read the credential code to confirm the order: the environment variable wins, then the OS keychain (where auth login stores the key), then ~/.config/retell/credentials.json with 0600 permissions as a fallback. retell auth whoami tells you which one it picked (mine said Source: env).

On headless Linux runners with no keychain, the login falls back to the file on its own. If you want to skip the keychain entirely, RETELL_DISABLE_KEYRING=1 does that, and RETELL_CONFIG_DIR moves the file. In CI, use the env var and nothing else, so a stale login on a self-hosted runner can never shadow the key you meant.

This is the one everybody hits. Here's the exact sequence I ran on a throwaway agent, in order:

The help text says update-agentupdates "the latest draft version." Once you publish, there is no draft, so you get 422 Cannot update published agent other than version title. Passing --version 0 doesn't help either. That matches Retell's versioning docs: publishing makes a version read-only, and you keep working in a new draft created from it.

Three details from that run that the docs don't spell out:

• The LLM follows the agent. Creating the v1 draft also moved the attached Retell LLM from version 0 to version 1, and publishing the agent published that LLM version. One publish, not two.
• get-agent returns the draft. Without --version it gave me v1 while v1 was still unpublished. Any script that reads get-agentto report "what's live" is wrong the moment someone opens a draft.
• Publishing prints null.Exit code 0, empty body. Don't parse it with jq expecting an object; confirm with list-agent-versions.

Version 0 can't be deleted at all (Cannot delete agent version 0.). To clean up a test agent, delete-agent removes every version, then delete-retell-llmremoves the response engine, which isn't deleted with it.

Keep the agent config in git as JSON, and let a script turn it into a new published version. This is the script I ran twice against a test agent today. It went v0 to v1 to v2, and get-agent --version 1 and --version 2 came back with the voice speeds each config set:

#!/usr/bin/env bash
# deploy-agent.sh <agent_id> <config.json> "<version title>"
set -euo pipefail
AGENT="$1"; CONFIG="$2"; TITLE="$3"
exec </dev/null   # the CLI reads stdin as a request body when it isn't a TTY

BASE=$(retell list-agent-versions "$AGENT" --output jsonl \
  | jq -s '[.[] | select(.is_published)] | max_by(.version) | .version')
DRAFT=$(retell create-agent-version "$AGENT" --base-version "$BASE" | jq .version)
retell update-agent "$AGENT" --version "$DRAFT" --body "$CONFIG" > /dev/null
retell publish-agent-version "$AGENT" --version "$DRAFT" --version-title "$TITLE" > /dev/null
echo "published v$DRAFT (from v$BASE)"

Two things make it work. --body config.json sends the whole file, and any flag you add on the same command overrides that field (I checked with --dry-run: a file with voice_speed 1.0 plus --voice-speed 1.15 sent 1.15). And the exec </dev/null line, which gets its own section below.

Publishing doesn't move traffic by itself. Phone numbers point at agents through inbound_agents and outbound_agents, each entry with a weight and an optional agent_version. The schema accepts a number, latest, latest_published or a tag name. I validated this with --dry-run, not against a live number:

retell update-phone-number +15555550100 \
  --inbound-agents '[{"agent_id":"agent_abc","agent_version":3,"weight":1}]'

The CLI can't move environment tags. Every agent gets prod and staging tags, and the dashboard lets you move prodto a new version so every number on that tag follows. There's no tag command in 0.47.0. So pick one: bind numbers to explicit versions and let CI update them, or keep numbers on prod and make the tag move a human click after the script publishes. I prefer the second for anything that takes real calls. The click doubles as a release approval, and rollback is moving the tag back.

Before that click, put a real test in between. The CLI exposes create-batch-test and the test-case commands, and a scripted test call beats finding out from a customer. I covered what to listen for in my post on agents that keep interrupting.

This is the trap I'd have shipped if I hadn't read the source. Any command that sends a JSON body reads stdin as that body whenever stdin isn't a terminal. In a normal while read loop, stdin is your input file. So the first update-agent swallows every remaining line:

# agents.txt has three agent IDs, one per line
while read id; do
  retell update-agent "$id" --voice-speed 1.05
done < agents.txt

# iteration 1: Error: Unexpected token 'a', "agent_two
#              "... is not valid JSON
# iterations 2 and 3 never run

That's the loud version. The quiet one is worse: if the leftover lines happen to be valid JSON, they get merged into the request. In a dry run, a loop whose input contained {"agent_name":"hijacked-by-stdin"} produced a body with that name next to the voice_speed I actually asked for. Imagine that on a loop over 40 client agents.

The fix is one redirect:

while read id; do
  retell update-agent "$id" --voice-speed 1.05 < /dev/null
done < agents.txt

With it, the same loop ran all three iterations. Read-only commands with no body, like get-agent, aren't affected; they ran 3 of 3 without the redirect. I still add it everywhere, because I won't remember which commands have bodies at 11 PM.

Yes, more than I expected. It prints the method, URL, headers (with the key shown as Bearer [REDACTED]) and body, and it validates the body against the OpenAPI schema locally before anything goes out. That caught my first mistake in about 100 ms:

$ retell create-retell-llm --dry-run --start-speaker agent \
    --general-prompt "You are..." --model gpt-5.6
Error: Enter a valid JSON value

$ retell create-retell-llm --dry-run --start-speaker agent \
    --general-prompt "You are..." --model-config '{"primary":"gpt-5.6"}'
Error: OpenAPI validation failed: requestBody.model_config does not match
any allowed schema; requestBody.model_config.primary must be object

# what it wants:
--model-config '{"type":"cascading","primary":{"model":"gpt-5.4-mini"}}'

The validator also lists every allowed model when you get the name wrong, which is faster than hunting through docs. Note that gpt-5.6 on its own isn't valid; the catalog has gpt-5.6-terra and gpt-5.6-luna.

What it can't catch is anything the server decides. An empty llm_id passed local validation and came back from the API as a 400. Dry runs check shape, not meaning.

Speed is a non-issue: a dry run took 0.10 s median over five runs on my Mac mini, and a real get-agentround trip 0.28 s. That's fast enough to call it in a loop over every agent in a workspace.

My split: the dashboard for building and listening to calls, the CLI for anything repeatable (deploys, bulk changes, pulling call lists into a terminal), and the SDKfor code that runs inside a product. Retell's docs draw the same line. If you're coming from the dashboard, my Retell AI setup guide covers the build side, and the Web SDK v3 migration notes cover the browser side.

The bigger point is that voice agents are config, and config belongs in git. I made the same argument for Claude agents in agents as code with ant apply. Retell's draft-and-publish model maps cleanly onto it. Each merge becomes a published version with a title you can trace back to a commit, and rollback means pointing at the previous number.

November 2, 2026, @retell-ai/retell-cli 0.47.0 (catalog v4) installed locally on a Mac mini in Allen, Texas, Node 26, authenticated with RETELL_API_KEY. Every write went to throwaway agents and Retell LLMs created for the test and deleted at the end (a final get-agent returned 404). No phone numbers or production agents were touched, and no calls were placed. The phone-number binding was checked with --dry-runonly. Auth order, timeouts and the stdin behavior come from reading the package's dist/src/runtime files and then reproducing each one.