twilio-cli

command
v0.8.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 15, 2026 License: MIT Imports: 26 Imported by: 0

README

twilio-cli

Drives a locally-running agent server as if it were Twilio — a real voice call or a real inbound SMS, without a Twilio account, a phone, or a public tunnel. It performs the same signed-webhook ceremony Twilio does, so the server cannot tell the difference.

Prerequisites

  • TWILIO_AUTH_TOKEN exported, matching the server's. Every webhook is signed over the exact URL posted to. A mismatch is a 403 with no other explanation.
  • Launch the server with the ws stream scheme, not wss. Answering wss makes every signature fail with a silent 403.
  • <FROM> must be a number the server's roster knows, in E.164 (+15551234567). Whether an unknown caller is rejected before a turn starts is the server's policy, not twilio-cli's — a server that binds any caller accepts any well-formed E.164. twilio-cli only checks the shape. In voice mode <FROM> is optional and defaults with a warning; see Voice. The sms subcommand always requires it.

Voice

go run ./cmd/twilio-cli +15551234567

<FROM> is optional here. Omit it and the call dials from +15105557890, announcing the substitution on one line so a defaulted number is never mistaken for one you chose:

twilio-cli: WARNING: no FROM given, defaulting source number to +15105557890

An explicit <FROM> is used verbatim and warns about nothing. The sms subcommand does not default it: sms parses <FROM> <BODY> positionally, so defaulting the first would make twilio-cli sms "hello" ambiguous between the two.

Posts the voice webhook, then opens the media-stream WebSocket and plays microphone audio in, printing the server's marks and control frames as they arrive.

The earcon cue means capture is live — not that the server is listening. When capture emits the mic-warm signal, at the first frame, twilio-cli plays a 240 ms 400 Hz tone to the local speaker. It fires within a second or two of the call connecting, and it says one thing: your microphone is now being streamed.

Wait for it to finish before you speak. The tone is real audio out of the same speaker, so the mic gate holds the outbound frames silent for its length plus the hangover — about half a second — and a word spoken over the beep is replaced by silence rather than clipped. Under -full-duplex there is no gate and the beep is only a beep.

It does not say the server is ready for you. A server that takes several seconds to generate its first response is not listening when this tone sounds, so the cue can land well ahead of the caller's first real turn. (A server that has already begun speaking by then gets no tone at all — it is suppressed, see playEarconUnlessServerSpoke.) Whatever signals "now it is your turn" has to come from the server, over the call, because only the server knows. Treat this tone as a capture check and wait for the server's own greeting.

This tone used to be a single 20 ms frame, which nobody could hear; it is now 240 ms with a 20 ms fade at each end (earconDurationMS, earconRampMS in playback.go).

Flag Purpose
-webhook Full webhook URL. Skips config resolution entirely.
-config Path to the config to resolve the target from. Overrides $AATOOLKIT_TWILIO_CONFIG.
-server Name of the config server entry to resolve from. Overrides $AATOOLKIT_SERVER_NAME.
-to The dialed number, E.164.
-audio Stream a raw μ-law file instead of capturing the mic. Any platform.
-no-echo-marks Suppress mark-echo, to exercise the server's AwaitingMarkEcho timeout.
-record <file> Record inbound server audio to a raw μ-law file, with per-arrival timing in <file>.jsonl.
-record-sent <file> Record the outbound caller audio (mic or -audio) to a raw μ-law file, replayable with -audio.
-full-duplex Send captured audio — mic or -audio — even while the server is speaking. Off by default; see Acoustic bleed.
Pointing twilio-cli at a config

With no -webhook, the target is resolved from a config file you name — there is no built-in default path. Give it with -config <file>, or export it once:

export AATOOLKIT_TWILIO_CONFIG=/absolute/path/to/your-fleet-config.toml

-config overrides the environment; -webhook overrides both and skips config resolution entirely. Use an absolute path: twilio-cli is normally run from this checkout while the config lives in the consuming project's, and a relative path resolves against your current directory.

Naming the server entry

Which entry in that config to read is likewise yours to name — there is no built-in default name, for the same reason there is no default path. A fixed one would belong to whichever consuming project happened to write it, and would stop resolving the day that project renamed its entry, failing with an error naming a server you never configured.

export AATOOLKIT_SERVER_NAME=my-agent-server

-server <name> overrides the environment; -webhook overrides both and skips the lookup entirely. The target is that entry's host at its second declared listen port — the webhook port — so the entry needs two listens.

Both the path and the name apply to the sms subcommand too — same flags, same variables, same precedence. The only difference is the route: /webhook for voice, /sms/inbound for SMS.

Recording what the server sent

-record answers the question a speaker cannot: did the server's audio arrive?

go run ./cmd/twilio-cli -record /tmp/call.ulaw +15551234567

It writes two files. /tmp/call.ulaw is the raw μ-law exactly as it came off the socket — play it with ffplay -f mulaw -ar 8000 /tmp/call.ulaw. /tmp/call.ulaw.jsonl carries one line per arrival with the offset into the call, the payload size, and the gap since the previous payload:

{"at_ms":100620,"bytes":160,"gap_ms":20,"total_bytes":804990}

The gaps are the useful part. A stream that stops for thirty seconds and resumes looks identical to a continuous one in the audio file alone, and those gaps are precisely where an operator reports hearing nothing. At the end of the call one summary line reports how much sound arrived against how long the call ran:

recorded 812150 bytes of inbound audio (1m41.5s of sound over a 3m51s call, 0.44×)

A ratio well below 1 means the server genuinely sent silence for the rest of the call. A ratio near 1 means the audio was there and anything unheard was lost after this process received it.

Recording what you sent

-record-sent is the other half: it saves the caller's own audio — the μ-law actually put on the socket, whether it came from the mic or from -audio.

go run ./cmd/twilio-cli -record-sent /tmp/me.ulaw +15551234567

It writes the same pair of files as -record, in the outbound direction: /tmp/me.ulaw holds the payloads in send order, and /tmp/me.ulaw.jsonl their timing. The two flags are independent and can be used together, giving one file per direction.

The point of it is replay. Without it the caller's audio only ever exists in flight, so a live conversation cannot be put to a second server — you can only say the words again, differently. With it, the recording is exactly the format -audio streams:

go run ./cmd/twilio-cli -record-sent /tmp/me.ulaw +15551234567    # talk to model A
go run ./cmd/twilio-cli -audio /tmp/me.ulaw -server other +15551234567   # same audio, model B

The bytes are teed after the frame goes out, so the file is what this process put on the socket, not what the microphone heard: a frame whose write failed is not in it. That is a claim about sending, not about delivery — a write can succeed and the frame still be lost if the connection drops straight after.

A frame the mic gate silenced is in it as silence, which is the same claim held to honestly: on a gated run the stretches where the server was speaking record as silence, because that is what went out. It is not a recording of the room, and it is not the file you streamed in. To capture what the microphone actually heard, run with headphones and -full-duplex.

That makes -full-duplex the flag chaining needs. Under it, recording a replay reproduces the file it replayed byte for byte, as long as the recording goes to a different file — a run that would record over the audio it is replaying is refused before anything is opened, since recording truncates. Without it a replay is gated like any other source, so the second-generation file is silent wherever the server was speaking — and, on a call that opens quietly, for the ~490 ms the capture-live earcon holds the gate shut a few frames in.

Streaming a file instead of the mic

Mic capture needs ffmpeg and is macOS-only (it uses avfoundation). -audio streams a raw 8 kHz μ-law file as the same 20 ms frames to the same endpoint, so it runs anywhere and needs no hardware — which makes it the way to drive the frame path from a script or a test:

go run ./cmd/twilio-cli -audio telephony/testdata/how_are_you.ulaw +15551234567

The repo's own fixtures work as input (telephony/testdata/*.ulaw, telephony/assets/*.ulaw). Frames are paced in real time, not burst, so the server's VAD sees the clip exactly as it would a live call. Reaching the end of the file ends the call the same way hanging up does.

Leading silence is not discarded — a fixture is read verbatim, frame one onward, exactly as the mic path now is.

A replay is gated like any other source. What the file holds and what goes on the wire are different things: the mic gate silences outbound frames while the player has audio queued, and that includes the capture-live earcon, which plays on any call the server does not open by speaking. So an -audio run loses roughly 490 ms near the start and any stretch the server talks over. (The earcon is played by the read loop a beat after the first frame goes out, so the very first frames are ungated; and on a call the server opens by speaking, the tone is suppressed and the server's own audio gates the mic instead.) Pass -full-duplex when the point is to put a fixed byte stream in front of the server — a scripted run, a regression fixture, or the record-then-replay chain above.

The earcon still sounds on a file replay — once, a beat after the first frame goes out, unless the server has already started speaking, in which case it is suppressed. It is the same mic-warm signal, and there is nobody to cue on a file replay, so mute your output if you are running unattended.

A relative -audio path resolves against your current directory, not the repository root.

The file must be raw μ-law with no container — a WAV will stream its 44-byte header as audio. Convert with:

ffmpeg -i input.wav -ar 8000 -ac 1 -acodec pcm_mulaw -f mulaw out.ulaw

SMS — two steps, in this order

The reply to an inbound SMS is not in the webhook response. The server answers the webhook in milliseconds with empty TwiML, queues the turn, and delivers the reply out-of-band over the Twilio REST API. So the CLI runs a local capture server that stands in for api.twilio.com, and waits for the reply to land on it (up to 35s).

The server reads TWILIO_API_BASE_URL once at startup, so it has to be launched already pointed at the capture port. That is why the order matters and cannot be reversed:

export TWILIO_API_BASE_URL=http://127.0.0.1:9750

Launch the server from that shell, then:

go run ./cmd/twilio-cli sms -capture-port 9750 +15551234567 "what's on today?"

On success it prints the reply it intercepted:

capture server listening on port 9750 — launch the server with TWILIO_API_BASE_URL=http://127.0.0.1:9750
captured reply — From=+15105559999 To=+15551234567

...the reply text, with real line breaks...
Flag Purpose
-capture-port Port the capture server binds. Default 9750. Must match the TWILIO_API_BASE_URL the server was launched with.
-webhook Full /sms/inbound URL. Skips config resolution.
-config Path to the config to resolve the target from. Overrides $AATOOLKIT_TWILIO_CONFIG.
-server Name of the config server entry to resolve from. Overrides $AATOOLKIT_SERVER_NAME.
-to The Twilio number the SMS was addressed to, E.164.

Do not set TWILIO_API_BASE_URL in your fleet config. Pointing the fleet at a local capture server by default would silently stop real SMS replies from being sent.

Acoustic bleed

twilio-cli plays inbound audio through the default output device and captures the default input device at the same time. On a laptop with no headphones the microphone hears the speaker, so everything the server says goes back up the stream as caller speech: the server transcribes its own voice, barges in on itself, and answers what it just said. Measured on one demo call, every inbound turn was the server's own preceding sentence, with the operator's real words appended to the tail of the echo.

This is physical acoustics, not a software isolation problem — capture and playback are separate OS processes. A real call does not have it because the carrier cancels the echo, so it is specific to the fake-call harness, which is exactly where turn-taking regressions are supposed to be visible.

The mic is gated by default. While the player still has audio to render — the server's speech, and the earcon tone, which goes into the same sink — the frames twilio-cli sends upstream carry μ-law silence instead of what the microphone heard, with a 250 ms hangover past the end of the audio handed to the player. Frames keep going out at the same rate: only their content changes, never the cadence, because a server that paces its writes against inbound frames stalls if the client goes quiet. A Twilio clear — barge-in, where the server abandons the rest of a reply — reopens the mic at once rather than waiting out audio nobody will hear.

"Handed to the player", not "played": twilio-cli writes into ffplay's stdin and cannot observe what has come out of the speaker, so the hangover covers the player's own buffering as well as the room's decay. That is why it is larger than a room-decay figure alone, and what to bear in mind before retuning it.

The connected log line says which mode produced a call, so a recording or transcript can be read afterwards for what it is.

This is half-duplex gating, not echo cancellation; cmd/twilio-cli/gate.go carries the argument for why, and is the place to read before changing any of it.

Turning the gate off

-full-duplex sends the captured frames throughout. Two reasons to want it:

  • Headphones. The microphone cannot hear them, so there is nothing to gate.
  • Testing barge-in. With the gate shut, talking over the server is the one behaviour the harness cannot exercise. Use headphones and -full-duplex together.

A third option isolates the two devices instead: set AATOOLKIT_STT_MIC to an alternate audio input (a USB headset microphone, say) while playback stays on the built-in speakers.

The value is an ffmpeg avfoundation device spec, [video]:[audio] — so the leading colon matters: AATOOLKIT_STT_MIC=":1" or AATOOLKIT_STT_MIC=":USB Audio Device". A value with no colon is treated as the audio half and gets one prepended, so a bare 1 still works; passing a full spec such as 0:1 is left alone. List the devices ffmpeg can see with:

ffmpeg -f avfoundation -list_devices true -i ""

Troubleshooting

Symptom Cause
returned status 403 TWILIO_AUTH_TOKEN doesn't match the server's, or the server was launched with wss.
no "<name>" server declared in <your config> -server/$AATOOLKIT_SERVER_NAME names an entry your config does not declare. Fix the name, or pass -webhook explicitly.
no server name: pass -server <name>, set AATOOLKIT_SERVER_NAME... No -webhook and no server name. Supply one of the three the message names.
no config path: pass -config <file>, set AATOOLKIT_TWILIO_CONFIG... No -webhook and no config source. Supply one of the three the message names.
ffmpeg Selected framerate ... is not supported on mic capture AATOOLKIT_STT_MIC named a camera: a bare value used to be read as the video device. Use the :N form.
no reply reached the capture server within 35s The server was not launched with TWILIO_API_BASE_URL pointed at the capture port — it sent the reply to the real Twilio API instead.
bind SMS capture server on port N Something else holds that port. Pick another with -capture-port, and launch the server with the matching TWILIO_API_BASE_URL.

Documentation

The Go Gopher

There is no documentation for this package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL