Telnyx Development: Telnyx CLI — Full Documentation
Complete page content for Telnyx CLI (Development section) of the Telnyx developer docs (https://developers.telnyx.com). Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this subsection: https://developers.telnyx.com/development/llms/development-telnyx-cli-llms-txt.md
Overview
Source: https://developers.telnyx.com/development/cli.mdThe Telnyx CLI is the official command-line interface for managing Telnyx resources directly from your terminal. Send messages, manage phone numbers, control calls, and more — all without leaving the command line.
When to Use the CLI vs the API
The CLI is ideal for operators, developers exploring the API, and simple automation. For production applications, use the Telnyx SDKs or call the REST API directly.
Features
Access all Telnyx APIs — messaging, voice, numbers, 10DLC, AI, verification, storage, and more JSON, YAML, pretty-print, and raw output for scripting and human readability Always in sync with the latest Telnyx API endpoints Inspect HTTP requests and responses for troubleshootingQuick Example
Installation
Install via Go:$GOPATH/bin is in your PATH.
Detailed installation instructions and troubleshooting
Documentation
Get up and running in 5 minutes Configure your API key Output formats, filtering, and scripting Full list of all CLI commandsResources
View source, report issues, and contribute Release notes and version history Full API documentation (CLI wraps these endpoints)Scripting & Automation
Source: https://developers.telnyx.com/development/cli/general-usage.mdThis guide covers common patterns for automating workflows with the Telnyx CLI — output formats, filtering, and integration with scripts and CI/CD pipelines.
Output Formats
The CLI supports multiple output formats via the--format flag.
Auto Format (Default)
Interactive exploration mode, best for browsing data:JSON Format
Machine-readable output for scripting and automation:YAML Format
Human-readable structured output:Pretty Format
Indented, colorized JSON:Raw Format
Unformatted API response:All Format Options
Transforming Output with GJSON
Use--transform to extract specific fields using GJSON syntax:
Filtering JSON with jq
Combine with jq for powerful filtering:Pagination
List commands support pagination via filter parameters:Filtering
Most list commands support filtering via individual--filter.* flags:
--filter.country-code, not --filter.country_code).
Global Flags
These flags work with all commands:Environment Variables
Scripting Examples
Bash: Bulk SMS Send
Bash: Export Numbers to CSV
Bash: Monitor Account Balance
GitHub Actions: Deploy Notification
Debug Mode
To inspect the full HTTP request and response:- Troubleshooting authentication issues
- Understanding the exact API calls being made
- Debugging unexpected responses
Next Steps
Full list of all commands Common issues and solutionsCommand Reference
Source: https://developers.telnyx.com/development/cli/reference.mdThis page provides a comprehensive reference for all available CLI commands. Use
telnyx --help for detailed options.
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:Phone Numbers
See Phone Numbers API for full response schemas.List & Manage Numbers
Search Available Numbers
Purchase Numbers
Number Reservations
Messaging
See Messaging API for full payload options.Send Messages
Retrieve Messages
Messaging Profiles
Optouts
10DLC (US A2P Messaging)
See 10DLC documentation for registration requirements.Brands
Campaigns
Use Cases
Phone Number Campaigns
Voice / Call Control
See Call Control API for advanced call flow options.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
Troubleshooting
Source: https://developers.telnyx.com/development/cli/troubleshooting.mdThis reference covers common issues you may encounter when using the Telnyx CLI and how to resolve them. Most CLI errors map directly to API error codes. For a complete list, see API Error Codes.
Authentication Errors
”Unauthorized” (401)
- Invalid or expired API key
- API key not set
- API key has extra whitespace or characters
-
Verify your API key is set:
-
Check the key format (should start with
KEY_): - Verify the key in the Telnyx Portal
-
Test with a simple command:
“No API key” Error
Causes:- Environment variable not set
- Environment variable not exported
-
Set the environment variable:
-
Verify it’s exported (not just set):
-
Add to your shell profile for persistence:
Permission Errors
”Forbidden” (403)
- API key doesn’t have permission for this action
- Resource belongs to a different account
- Account verification required
- Check API key permissions in the Portal
- Verify you’re using the correct API key for the account
- Some features require account verification (verify here)
Resource Errors
”Not Found” (404)
- Resource ID is incorrect
- Resource was deleted
- Resource belongs to a different account
-
Verify the resource exists:
- Check for typos in the resource ID
- Ensure you’re using the correct API key if you have multiple accounts
”Phone number not found”
Solution: List your numbers to see what’s available:Rate Limiting
”Too Many Requests” (429)
- Exceeded API rate limits
- Too many requests in short period
-
Add delays between requests in scripts:
- Use bulk endpoints when available
- Check rate limits documentation
Messaging Errors
”Number not enabled for messaging”
- Enable messaging on the number via the Portal or API
-
Or purchase a messaging-enabled number:
“10DLC campaign required”
”Invalid ‘to’ number”
-
Use E.164 format (include country code):
-
Verify the number is valid:
Installation Issues
”command not found: telnyx”
Causes:- CLI not installed
- Go bin directory not in PATH
- Shell not reloaded after install
-
Verify Go’s bin directory contains telnyx:
-
Add Go bin to PATH:
-
Reinstall if needed:
-
Reload your shell config:
“command not found: go”
Causes:- Go not installed
Go version error
Build/compile errors
Solutions:-
Ensure you have Go 1.22+:
-
Clear module cache and retry:
Connection Issues
Network error / Connection refused
Causes:- No internet connection
- Firewall blocking requests
- Proxy misconfiguration
- Check internet connectivity
- Verify you can reach the API:
- Check proxy settings if applicable
Timeout errors
Solutions:- Check your internet connection
- Try again (may be temporary)
- For large operations, the API may need more time
Getting More Help
Enable Debug Mode
For detailed HTTP request/response logging:Check CLI Version
Ensure you’re on the latest version:Get Support
- GitHub Issues: Report bugs
- Telnyx Support: Contact support
- Community: Slack
- API Status: status.telnyx.com
Getting Started
Install
Source: https://developers.telnyx.com/development/cli/getting-started/install.mdThe Telnyx CLI is supported on macOS, Windows, and Linux. The Telnyx CLI requires Go 1.22 or later. If you don’t have Go installed, follow the official installation guide.
Installation
Install the CLI using Go:telnyx binary to your Go bin directory.
Add to PATH
After installation, ensure the Go bin directory is in your PATH:Verify Installation
Update
To update to the latest version, run the install command again:Alternative: Run Without Installing
You can run the CLI directly without installing:Troubleshooting
”command not found: telnyx”
If the command isn’t found after installation:-
Verify Go’s bin directory:
-
Add Go bin to your PATH:
-
Reload your shell config:
“command not found: go”
Install Go first:- macOS:
brew install go - Linux: Use your package manager or download from go.dev
- Windows: Download the installer from go.dev
Build errors
If you encounter build errors:-
Ensure you have Go 1.22+:
-
Clear Go’s module cache and retry:
Next Steps
Configure authentication and run your first commands Full list of all CLI commandsQuickstart
Source: https://developers.telnyx.com/development/cli/getting-started/quickstart.mdThis quickstart guide will help you install the Telnyx CLI, configure authentication, and run your first commands.
Prerequisites
- Go 1.22+ installed
- A Telnyx account
- A Telnyx API key
Step 1: Install the CLI
Step 2: Configure Authentication
Set your API key as an environment variable. You can get your API key from the Telnyx Portal.~/.bashrc, ~/.zshrc, etc.) to persist it across sessions.
Verify Authentication
Test that your credentials are working:Step 3: Run Your First Commands
Check Your Balance
List Your Phone Numbers
Search for Available Numbers
Send a Test Message
You’ll need a messaging-enabled phone number and a configured messaging profile.Step 4: Explore Commands
Get Help
Common Commands
Output Formats
The CLI supports multiple output formats:Debug Mode
To see full HTTP request/response details:Next Steps
Learn about authentication options Output formats, scripting, and CI/CD integrationAuthentication
Source: https://developers.telnyx.com/development/cli/getting-started/authentication.mdThe Telnyx CLI authenticates using an API key set via environment variable.
Setting Your API Key
Set theTELNYX_API_KEY environment variable:
~/.bashrc, ~/.zshrc, etc.) to persist it across terminal sessions.
Verify Authentication
Test that your credentials are working by running any command:Getting Your API Key
- Log in to the Telnyx Portal
- Navigate to API Keys
- Click Create API Key
- Copy the key (it won’t be shown again)
KEY_. If you’re using a v1 API key (starting with a different prefix), you’ll need to create a new v2 key.
Multiple Accounts
If you work with multiple Telnyx accounts (e.g., production and staging), you have several options:Option 1: Shell Aliases
Create aliases for different accounts:Option 2: Separate Terminal Sessions
Set different API keys in different terminal windows:Option 3: Inline Override
Override the API key for a single command:CI/CD Integration
GitHub Actions
GitLab CI
Shell Scripts
Security Best Practices
Use environment variables or secrets management. Add.env files to .gitignore.
Create different API keys for production, staging, and development. This limits blast radius if a key is compromised.
Regenerate API keys periodically and update your configurations.
Store API keys in GitHub Secrets, GitLab CI Variables, AWS Secrets Manager, HashiCorp Vault, etc.
Troubleshooting
”Unauthorized” Error
- Verify your API key is set:
echo $TELNYX_API_KEY - Check if the key starts with
KEY_ - Verify the key hasn’t been revoked in the Portal
- Ensure there are no extra spaces or characters in the key
”No API key” Error
Solutions:- Set the environment variable:
export TELNYX_API_KEY=KEY_xxx - Check for typos in the variable name
- Ensure the variable is exported (not just set)
Next Steps
Run your first CLI commands Output formats, scripting, and CI/CDWorkflows
10DLC Registration
Source: https://developers.telnyx.com/development/cli/workflows/10dlc.mdThis guide shows you how to complete 10DLC (10-Digit Long Code) registration using the Telnyx CLI, from brand creation through campaign approval.
Why 10DLC?
US carriers require 10DLC registration for Application-to-Person (A2P) messaging from local phone numbers. Without it, your messages may be blocked or throttled. Registration establishes your business identity with carriers and unlocks higher throughput based on your trust score. For a deeper explanation of 10DLC, trust scores, and carrier requirements, see Understanding 10DLC.Prerequisites
- Telnyx account with verified status
- Telnyx CLI installed
TELNYX_API_KEYenvironment variable set- Business information ready (EIN, address, website)
- At least one US phone number
Registration Steps
Step 1: Create a Brand
A brand represents your business identity for 10DLC registration.Standard Business
Sole Proprietor
For sole proprietors, additional SMS OTP verification is required:PRIVATE_PROFIT- Private companyPUBLIC_PROFIT- Publicly traded companyNON_PROFIT- Non-profit organizationGOVERNMENT- Government entitySOLE_PROPRIETOR- Individual / sole proprietor
Step 2: Check Brand Status
Step 3: Create a Campaign
Once your brand is approved, create a campaign to define your messaging use case:Step 4: Manage Campaigns
Step 5: Phone Number Assignment
Check phone number campaign assignments:Step 6: Verify Setup
Campaign Approval
After submission, campaigns go through carrier approval:
Campaign approval can take 1-7 business days. Do not send A2P messages until approved.
Appeal Rejected Campaigns
If your campaign was rejected, you can submit an appeal:Deactivate a Campaign
Best Practices
Sample Messages
Your sample messages should:- Represent actual messages you’ll send
- Include opt-out language (“Reply STOP to unsubscribe”)
- Match your stated use case
- Not contain placeholder text
Throughput
10DLC throughput depends on your trust score:
Higher trust scores come from:
- Verified business information
- Good messaging practices
- Low spam/complaint rates
Troubleshooting
”Brand verification failed”
- Double-check EIN matches IRS records exactly
- Verify business address is current
- Ensure phone number is associated with business
“Campaign rejected”
Common reasons:- Sample messages don’t match use case
- Missing opt-out language
- Vague or generic description
Revet a Brand
If your brand information has changed or was rejected, you can revet (resubmit):Complete Script Example
Next Steps
Start sending SMS after approval Deep dive on trust scores and carrier requirements Throughput tiers and trust scores Common errors and solutionsLegacy CLI (Deprecated)
Overview
Source: https://developers.telnyx.com/development/cli/legacy.mdThis CLI is deprecated. The
@telnyx/api-cli package is no longer actively maintained.
For new projects, use the Telnyx CLI (Go) which offers better performance, simpler authentication, and full API coverage.
About the Legacy CLI
The@telnyx/api-cli is a Node.js-based command-line interface for interacting with the Telnyx API. It provides commands for managing phone numbers, sending messages, making calls, and more.
Features
- Interactive Setup — Guided authentication with
telnyx auth setup - Profile Management — Multiple API key profiles for different environments
- 10DLC Wizard — Step-by-step 10DLC brand and campaign registration
- Shell Autocomplete — Tab completion for commands and options
- Dry Run Mode — Preview destructive operations before executing
Legacy Documentation
npm installation instructions API keys, profiles, and config files Full command referenceResources
- npm Package — Version history
- GitHub Repository — Source code
Installation
Source: https://developers.telnyx.com/development/cli/legacy/install.mdThis CLI is deprecated. For new projects, use the current Telnyx CLI instead.
Requirements
The legacy CLI requires Node.js 20 or later.Installation
Install globally via npm:telnyx command available from any directory.
Verify Installation
Update
To update to the latest version:Troubleshooting
”command not found: telnyx”
If the command isn’t found after installation:-
Verify it installed:
-
Check npm’s global bin is in your PATH:
-
Restart your terminal or reload your shell config:
Permission errors
If you getEACCES permission errors:
- Follow npm’s guide to fix permissions
- Or use a Node version manager (nvm, fnm) which doesn’t require sudo
Next Steps
Configure API keys and profilesAuthentication
Source: https://developers.telnyx.com/development/cli/legacy/authentication.mdThis CLI is deprecated. The new Telnyx CLI uses environment variables only (
TELNYX_API_KEY). Profile management is not available in the new CLI.
Authentication Methods
The legacy CLI supports three authentication methods, checked in order: flag → environment variable → config file.1. Interactive Setup (Recommended)
~/.config/telnyx/config.json.
2. Environment Variable
3. Command-Line Flag
Verify Authentication
Multiple Profiles
Use named profiles to manage multiple Telnyx accounts or environments.Create a Profile
List Profiles
Use a Profile
Set Default Profile
Delete a Profile
Configuration File
The CLI stores configuration in~/.config/telnyx/config.json:
Environment Variables
Getting Your API Key
- Log in to the Telnyx Portal
- Navigate to API Keys
- Click Create API Key
- Copy the key (it won’t be shown again)
KEY_. If you’re using a v1 API key, you’ll need to create a new v2 key.
Next Steps
Full command reference for the legacy CLICommand Reference
Source: https://developers.telnyx.com/development/cli/legacy/reference.mdThis CLI is deprecated. For the current CLI commands, see Command Reference.