Command Reference

This page provides a comprehensive reference for all available CLI commands. Use telnyx <command> --help for detailed options.

This reference documents the current Go-based Telnyx CLI, which uses plural resource names such as telnyx messages. The deprecated Node.js @telnyx/api-cli uses singular resource names such as telnyx message and supports short flags such as -f and -t. See the legacy command reference for that syntax.

The CLI is auto-generated from the Telnyx REST API. For full request/response schemas, see the corresponding API reference for each resource.

Global Options

These flags work with all commands:

--debug                   # Enable debug logging (shows HTTP requests/responses)
--base-url <url>          # Override the API base URL
--format <format>         # Output format: auto, json, jsonl, pretty, yaml, raw
--format-error <format>   # Error output format
--transform <gjson>       # Transform output using GJSON syntax
--help, -h                # Show help
--version, -v             # Show version

Phone Numbers

See Phone Numbers API for full response schemas.

List & Manage Numbers

# List your phone numbers
telnyx phone-numbers list
telnyx phone-numbers list --filter.status active
telnyx phone-numbers list --page-size 50

# Get number details
telnyx phone-numbers retrieve --id <phone-number-id>

# Update number settings
telnyx phone-numbers update --phone-number-id <phone-number-id> --connection-id <id>

# Delete a number
telnyx phone-numbers delete --id <phone-number-id>

Search Available Numbers

# Search available numbers
telnyx available-phone-numbers list --filter.country-code US
telnyx available-phone-numbers list --filter.country-code US --filter.limit 10
telnyx available-phone-numbers list --filter.country-code US --filter.locality "San Francisco"

# Search number blocks
telnyx available-phone-number-blocks list --filter.country-code US

Purchase Numbers

# Create a number order
telnyx number-orders create --phone-number '{phone_number: +15551234567}'
telnyx number-orders create --phone-number '{phone_number: +15551234567}' --messaging-profile-id <id>

# List/retrieve orders
telnyx number-orders list
telnyx number-orders retrieve --number-order-id <order-id>

Number Reservations

telnyx number-reservations create --phone-number '{phone_number: +15551234567}'
telnyx number-reservations list
telnyx number-reservations retrieve --number-reservation-id <reservation-id>

Messaging

See Messaging API for full payload options.

Send Messages

# Send SMS
telnyx messages send --from +15551234567 --to +15559876543 --text "Hello!"

# Send MMS
telnyx messages send --from +15551234567 --to +15559876543 \
  --text "Check this out" \
  --media-url https://example.com/image.jpg

# Send WhatsApp message
telnyx messages whatsapp --from +15551234567 --to +15559876543 \
  --type WHATSAPP --whatsapp-message '{text: {body: "Hello!"}}'

# Schedule a message
# Set SEND_AT to an ISO 8601 timestamp at least one minute in the future
telnyx messages schedule --from +15551234567 --to +15559876543 \
  --text "Reminder!" --send-at "$SEND_AT"

# Cancel scheduled message
telnyx messages cancel-scheduled --id <message-id>

Retrieve Messages

telnyx messages retrieve --id <message-id>

Messaging Profiles

telnyx messaging-profiles list
telnyx messaging-profiles retrieve --messaging-profile-id <profile-id>
telnyx messaging-profiles create --name "Production" --whitelisted-destination '["*"]'
telnyx messaging-profiles update --messaging-profile-id <profile-id> --name "Updated Name"
telnyx messaging-profiles delete --messaging-profile-id <profile-id>

# List associated phone numbers
telnyx messaging-profiles list-phone-numbers --messaging-profile-id <id>

Optouts

telnyx messaging-optouts list

10DLC (US A2P Messaging)

See 10DLC documentation for registration requirements.

Brands

# List brands
telnyx messaging-10dlc:brand list

# Create brand
telnyx messaging-10dlc:brand create \
  --entity-type PRIVATE_PROFIT \
  --display-name "My Company" \
  --company-name "My Company Inc" \
  --email "support@example.com" \
  --ein 12-3456789 \
  --phone +15551234567 \
  --street "123 Main St" \
  --city "San Francisco" \
  --state CA \
  --postal-code 94102 \
  --country US \
  --vertical TECHNOLOGY \
  --website https://example.com

# Retrieve/update brand (update requires the full set of required brand fields)
telnyx messaging-10dlc:brand retrieve --brand-id <id>
telnyx messaging-10dlc:brand update --brand-id <id> \
  --display-name "New Name" \
  --email "support@example.com" \
  --entity-type PRIVATE_PROFIT \
  --country US \
  --vertical TECHNOLOGY

# Revet brand (resubmit for verification)
telnyx messaging-10dlc:brand revet --brand-id <id>

# SMS OTP verification for sole proprietor
telnyx messaging-10dlc:brand trigger-sms-otp --brand-id <id> \
  --pin-sms "Your verification PIN is @OTP_PIN@" \
  --success-sms "Your brand has been verified"
telnyx messaging-10dlc:brand verify-sms-otp --brand-id <id> --otp-pin 123456

# Get brand feedback
telnyx messaging-10dlc:brand get-feedback --brand-id <id>

# Delete brand
telnyx messaging-10dlc:brand delete --brand-id <id>

Campaigns

# List campaigns
telnyx messaging-10dlc:campaign list --brand-id <id>

# Retrieve campaign
telnyx messaging-10dlc:campaign retrieve --campaign-id <id>

# Update campaign (only sample messages editable)
telnyx messaging-10dlc:campaign update --campaign-id <id> --sample1 "New sample"

# Get campaign operation status
telnyx messaging-10dlc:campaign get-operation-status --campaign-id <id>

# Deactivate campaign
telnyx messaging-10dlc:campaign deactivate --campaign-id <id>

# Submit appeal for rejected campaign
telnyx messaging-10dlc:campaign submit-appeal --campaign-id <id> \
  --appeal-reason "Detailed explanation of the changes made to address the rejection"

Use Cases

# Get the upfront and monthly cost for a use case
telnyx messaging-10dlc:campaign:usecase get-cost --usecase MARKETING

Phone Number Campaigns

telnyx messaging-10dlc:phone-number-campaigns list
telnyx messaging-10dlc:phone-number-campaigns retrieve --phone-number +15551234567

Voice / Call Control

See Call Control API for advanced call flow options.

Make Calls

# Dial outbound call
telnyx calls dial \
  --connection-id <id> \
  --from +15551234567 \
  --to +15559876543

# With answering machine detection
telnyx calls dial \
  --connection-id <id> \
  --from +15551234567 \
  --to +15559876543 \
  --answering-machine-detection detect

Call Status

telnyx calls retrieve-status --call-control-id <id>

Call Actions

# Answer incoming call
telnyx calls:actions answer --call-control-id <id>

# Hang up
telnyx calls:actions hangup --call-control-id <id>

# Transfer call
telnyx calls:actions transfer --call-control-id <id> --to +15559876543

# Bridge two calls
telnyx calls:actions bridge --call-control-id-to-bridge <id> --call-control-id-to-bridge-with <id2>

# Play audio
telnyx calls:actions start-playback --call-control-id <id> --audio-url https://...

# Stop audio
telnyx calls:actions stop-playback --call-control-id <id>

# Text-to-speech
telnyx calls:actions speak --call-control-id <id> \
  --payload "Hello, how can I help?" --voice AWS.Polly.Joanna

# Gather DTMF input
telnyx calls:actions gather --call-control-id <id> --minimum-digits 1 --maximum-digits 4

# Send DTMF
telnyx calls:actions send-dtmf --call-control-id <id> --digits "1234"

# Start recording
telnyx calls:actions start-recording --call-control-id <id> --channels single --format mp3

# Stop recording
telnyx calls:actions stop-recording --call-control-id <id>

# Start transcription
telnyx calls:actions start-transcription --call-control-id <id>

# Stop transcription
telnyx calls:actions stop-transcription --call-control-id <id>

# Start AI assistant
telnyx calls:actions start-ai-assistant --call-control-id <id> --assistant '{id: <assistant-id>}'

# Stop AI assistant
telnyx calls:actions stop-ai-assistant --call-control-id <id>

Call Control Applications

telnyx call-control-applications list
telnyx call-control-applications retrieve --id <id>
telnyx call-control-applications create --application-name "My App" --webhook-event-url https://...
telnyx call-control-applications update --id <id> --application-name "Updated" --webhook-event-url https://...
telnyx call-control-applications delete --id <id>

Conferences

telnyx conferences list
telnyx conferences retrieve --id <id>
telnyx conferences create --call-control-id <id> --name "Team Call"

# Conference actions
telnyx conferences:actions join --id <id> --call-control-id <id>
telnyx conferences:actions mute --id <id> --call-control-id <id1> --call-control-id <id2>
telnyx conferences:actions unmute --id <id> --call-control-id <id1> --call-control-id <id2>

Recordings

telnyx recordings list
telnyx recordings retrieve --recording-id <id>
telnyx recordings delete --recording-id <id>

# Transcriptions
telnyx recording-transcriptions list
telnyx recording-transcriptions retrieve --recording-transcription-id <id>

AI

Chat Completions

telnyx ai:openai:chat create-completion --model meta-llama/Meta-Llama-3.1-8B-Instruct \
  --message '{role: user, content: "Hello!"}'

AI Assistants

# List/create assistants
telnyx ai:assistants list
telnyx ai:assistants create --name "My Assistant" \
  --model meta-llama/Meta-Llama-3.1-8B-Instruct \
  --instructions "You are a helpful assistant"
telnyx ai:assistants retrieve --assistant-id <id>
telnyx ai:assistants update --assistant-id <id> --name "Updated"
telnyx ai:assistants delete --assistant-id <id>

# Chat with assistant
telnyx ai:assistants chat --assistant-id <id> --conversation-id <id> --content "Hello!"

# Clone assistant
telnyx ai:assistants clone --assistant-id <id>

Audio (Speech-to-Text / Text-to-Speech)

# Transcribe audio
telnyx ai:audio transcribe --file-url https://example.com/audio.mp3 \
  --model openai/whisper-large-v3-turbo

# Text-to-speech
telnyx text-to-speech generate-speech --text "Hello world" --voice Telnyx.Ultra.Clara

Embeddings

# Embed raw text (OpenAI-compatible endpoint)
telnyx ai:openai:embeddings create-embeddings --input "Your text here" --model <embedding-model>

# Embed the contents of a storage bucket
telnyx ai:embeddings create --bucket-name my-bucket

Conversations

telnyx ai:conversations list
telnyx ai:conversations create --name "Support chat"
telnyx ai:conversations retrieve --conversation-id <id>
telnyx ai:conversations:messages list --conversation-id <id>

Verify (2FA)

Profiles

telnyx verify-profiles list
telnyx verify-profiles retrieve --verify-profile-id <id>
telnyx verify-profiles create --name "my-app" --sms '{default_verification_timeout_secs: 300}'
telnyx verify-profiles update --verify-profile-id <id> --name "updated"
telnyx verify-profiles delete --verify-profile-id <id>

# Message templates (account-wide)
telnyx verify-profiles create-template --text "Your code is {{code}}"
telnyx verify-profiles retrieve-templates

Send Verification

# Trigger SMS verification
telnyx verifications trigger-sms --phone-number +15551234567 --verify-profile-id <id>

# Trigger voice call verification
telnyx verifications trigger-call --phone-number +15551234567 --verify-profile-id <id>

# Trigger flash call verification
telnyx verifications trigger-flashcall --phone-number +15551234567 --verify-profile-id <id>

# Retrieve verification status
telnyx verifications retrieve --verification-id <id>

Verify Code

telnyx verifications:actions verify --verification-id <id> --code 123456

Fax

# Send fax
telnyx faxes create \
  --connection-id <id> \
  --from +15551234567 \
  --to +15559876543 \
  --media-url https://example.com/document.pdf

# List/retrieve faxes
telnyx faxes list
telnyx faxes retrieve --id <id>
telnyx faxes delete --id <id>

Number Lookup

telnyx number-lookup retrieve --phone-number +15551234567

Billing

# Check balance
telnyx balance retrieve

# Billing groups
telnyx billing-groups list
telnyx billing-groups retrieve --id <id>
telnyx billing-groups create --name "Production"
telnyx billing-groups update --id <id> --name "Updated"
telnyx billing-groups delete --id <id>

SIM Cards (IoT)

# List SIM cards
telnyx sim-cards list
telnyx sim-cards retrieve --id <id>
telnyx sim-cards update --sim-card-id <id> --tag production
telnyx sim-cards delete --id <id>

# SIM card groups
telnyx sim-card-groups list
telnyx sim-card-groups create --name "Fleet 1"
telnyx sim-card-groups retrieve --id <id>
telnyx sim-card-groups delete --id <id>

# SIM card orders
telnyx sim-card-orders list
telnyx sim-card-orders create --quantity 10 --address-id <id>

Porting

# Porting orders
telnyx porting-orders list
telnyx porting-orders retrieve --id <id>
telnyx porting-orders create --phone-number +15551234567

# Portability check
telnyx portability-checks run --phone-number +15551234567

# Port-outs
telnyx portouts list
telnyx portouts retrieve --id <id>

Storage

# Presigned URLs for upload/download
telnyx storage:buckets create-presigned-url --bucket-name my-bucket --object-name my-file.txt

Video Rooms

# Rooms
telnyx rooms list
telnyx rooms create --unique-name "Team Meeting" --max-participants 10
telnyx rooms retrieve --room-id <id>
telnyx rooms update --room-id <id> --max-participants 20
telnyx rooms delete --room-id <id>

# Sessions for a specific room
telnyx rooms:sessions list-1 --room-id <id>

# Sessions across the whole account
telnyx rooms:sessions list-0

# Recordings
telnyx room-recordings list
telnyx room-recordings retrieve --room-recording-id <id>
telnyx room-recordings delete --room-recording-id <id>

# Compositions
telnyx room-compositions list
telnyx room-compositions create --session-id <id>

Networking

WireGuard

telnyx wireguard-interfaces list
telnyx wireguard-interfaces create --body '{network_id: <network-id>, region_code: ashburn-va}'
telnyx wireguard-interfaces retrieve --id <id>
telnyx wireguard-interfaces delete --id <id>

telnyx wireguard-peers list --filter.wireguard-interface-id <id>
telnyx wireguard-peers create --body '{wireguard_interface_id: <interface-id>}'

Global IPs

telnyx global-ips list
telnyx global-ips create
telnyx global-ips retrieve --id <id>
telnyx global-ips delete --id <id>

Getting Help

telnyx --help                              # General help
telnyx <resource> --help                   # Resource help
telnyx <resource> <command> --help         # Command help

# Examples
telnyx phone-numbers --help
telnyx messages send --help
telnyx calls:actions --help

​Global Options

​Phone Numbers

​List & Manage Numbers

​Search Available Numbers

​Purchase Numbers

​Number Reservations

​Messaging

​Send Messages

​Retrieve Messages

​Messaging Profiles

​Optouts

​10DLC (US A2P Messaging)

​Brands

​Campaigns

​Use Cases

​Phone Number Campaigns

​Voice / Call Control

​Make Calls

​Call Status

​Call Actions

​Call Control Applications

​Conferences

​Recordings

​AI

​Chat Completions

​AI Assistants

​Audio (Speech-to-Text / Text-to-Speech)

​Embeddings

​Conversations

​Verify (2FA)

​Profiles

​Send Verification

​Verify Code

​Fax

​Number Lookup

​Billing

​SIM Cards (IoT)

​Porting

​Storage

​Video Rooms

​Networking

​WireGuard

​Global IPs

​Getting Help

Global Options

Phone Numbers

List & Manage Numbers

Search Available Numbers

Purchase Numbers

Number Reservations

Messaging

Send Messages

Retrieve Messages

Messaging Profiles

Optouts

10DLC (US A2P Messaging)

Brands

Campaigns

Use Cases

Phone Number Campaigns

Voice / Call Control

Make Calls

Call Status

Call Actions

Call Control Applications

Conferences

Recordings

AI

Chat Completions

AI Assistants

Audio (Speech-to-Text / Text-to-Speech)

Embeddings

Conversations

Verify (2FA)

Profiles

Send Verification

Verify Code

Fax

Number Lookup

Billing

SIM Cards (IoT)

Porting

Storage

Video Rooms

Networking

WireGuard

Global IPs

Getting Help