Skip to main content

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.md
The 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 troubleshooting

Quick Example

Installation

Install via Go:
Requires Go 1.22+. After installation, ensure $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 commands

Resources

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.md
This 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 flag names use kebab-case (e.g., --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:
This is useful for:
  • Troubleshooting authentication issues
  • Understanding the exact API calls being made
  • Debugging unexpected responses

Next Steps

Full list of all commands Common issues and solutions

Command Reference

Source: https://developers.telnyx.com/development/cli/reference.md
This 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.md
This 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)

Causes:
  • Invalid or expired API key
  • API key not set
  • API key has extra whitespace or characters
Solutions:
  1. Verify your API key is set:
  2. Check the key format (should start with KEY_):
  3. Verify the key in the Telnyx Portal
  4. Test with a simple command:

“No API key” Error

Causes:
  • Environment variable not set
  • Environment variable not exported
Solutions:
  1. Set the environment variable:
  2. Verify it’s exported (not just set):
  3. Add to your shell profile for persistence:

Permission Errors

”Forbidden” (403)

Causes:
  • API key doesn’t have permission for this action
  • Resource belongs to a different account
  • Account verification required
Solutions:
  1. Check API key permissions in the Portal
  2. Verify you’re using the correct API key for the account
  3. Some features require account verification (verify here)

Resource Errors

”Not Found” (404)

Causes:
  • Resource ID is incorrect
  • Resource was deleted
  • Resource belongs to a different account
Solutions:
  1. Verify the resource exists:
  2. Check for typos in the resource ID
  3. 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)

Causes:
  • Exceeded API rate limits
  • Too many requests in short period
Solutions:
  1. Add delays between requests in scripts:
  2. Use bulk endpoints when available
  3. Check rate limits documentation

Messaging Errors

”Number not enabled for messaging”

Solutions:
  1. Enable messaging on the number via the Portal or API
  2. Or purchase a messaging-enabled number:

“10DLC campaign required”

Solution: Register for 10DLC via the Portal or API. See the 10DLC documentation.

”Invalid ‘to’ number”

Solutions:
  1. Use E.164 format (include country code):
  2. 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
Solutions:
  1. Verify Go’s bin directory contains telnyx:
  2. Add Go bin to PATH:
  3. Reinstall if needed:
  4. Reload your shell config:

“command not found: go”

Causes:
  • Go not installed
Solutions: Install Go:

Go version error

Solution: Upgrade Go:

Build/compile errors

Solutions:
  1. Ensure you have Go 1.22+:
  2. Clear module cache and retry:

Connection Issues

Network error / Connection refused

Causes:
  • No internet connection
  • Firewall blocking requests
  • Proxy misconfiguration
Solutions:
  1. Check internet connectivity
  2. Verify you can reach the API:
  3. Check proxy settings if applicable

Timeout errors

Solutions:
  1. Check your internet connection
  2. Try again (may be temporary)
  3. 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



Getting Started

Install

Source: https://developers.telnyx.com/development/cli/getting-started/install.md
The 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:
This downloads, compiles, and installs the telnyx binary to your Go bin directory.

Add to PATH

After installation, ensure the Go bin directory is in your PATH:
Reload your shell or restart your terminal for changes to take effect.

Verify Installation

You should see output similar to:

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:
  1. Verify Go’s bin directory:
  2. Add Go bin to your PATH:
  3. 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:
  1. Ensure you have Go 1.22+:
  2. Clear Go’s module cache and retry:

Next Steps

Configure authentication and run your first commands Full list of all CLI commands

Quickstart

Source: https://developers.telnyx.com/development/cli/getting-started/quickstart.md
This quickstart guide will help you install the Telnyx CLI, configure authentication, and run your first commands.

Prerequisites

Step 1: Install the CLI

Ensure Go’s bin directory is in your PATH:
Verify the installation:

Step 2: Configure Authentication

Set your API key as an environment variable. You can get your API key from the Telnyx Portal.
Add this line to your shell profile (~/.bashrc, ~/.zshrc, etc.) to persist it across sessions.

Verify Authentication

Test that your credentials are working:
You should see your account balance information.

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 integration

Authentication

Source: https://developers.telnyx.com/development/cli/getting-started/authentication.md
The Telnyx CLI authenticates using an API key set via environment variable.

Setting Your API Key

Set the TELNYX_API_KEY environment variable:
Add this line to your shell profile (~/.bashrc, ~/.zshrc, etc.) to persist it across terminal sessions.

Verify Authentication

Test that your credentials are working by running any command:
If authenticated successfully, you’ll see your account balance. If not, you’ll receive an authentication error.

Getting Your API Key

  1. Log in to the Telnyx Portal
  2. Navigate to API Keys
  3. Click Create API Key
  4. Copy the key (it won’t be shown again)
API keys start with 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:
Usage:

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

Solutions:
  • 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/CD

Workflows

10DLC Registration

Source: https://developers.telnyx.com/development/cli/workflows/10dlc.md
This 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_KEY environment 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:
Entity Types:
  • PRIVATE_PROFIT - Private company
  • PUBLIC_PROFIT - Publicly traded company
  • NON_PROFIT - Non-profit organization
  • GOVERNMENT - Government entity
  • SOLE_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:
Campaign creation is done via the Telnyx Portal or the API. The CLI supports retrieving and managing existing campaigns.

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

Once deactivated, a campaign cannot be restored.

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
Check feedback:

“Campaign rejected”

Common reasons:
  • Sample messages don’t match use case
  • Missing opt-out language
  • Vague or generic description
Solution: Review feedback, update campaign via Portal, and resubmit.

Revet a Brand

If your brand information has changed or was rejected, you can revet (resubmit):
Revetting is allowed once after successful registration, then limited to once every 3 months.

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 solutions

Legacy CLI (Deprecated)

Overview

Source: https://developers.telnyx.com/development/cli/legacy.md
This 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 reference

Resources


Installation

Source: https://developers.telnyx.com/development/cli/legacy/install.md
This 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:
This makes the telnyx command available from any directory.

Verify Installation

Expected output:

Update

To update to the latest version:

Troubleshooting

”command not found: telnyx”

If the command isn’t found after installation:
  1. Verify it installed:
  2. Check npm’s global bin is in your PATH:
  3. Restart your terminal or reload your shell config:

Permission errors

If you get EACCES permission errors:
  1. Follow npm’s guide to fix permissions
  2. Or use a Node version manager (nvm, fnm) which doesn’t require sudo

Next Steps

Configure API keys and profiles

Authentication

Source: https://developers.telnyx.com/development/cli/legacy/authentication.md
This 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.
You’ll be prompted to enter your API key. Configuration is stored in ~/.config/telnyx/config.json.

2. Environment Variable

3. Command-Line Flag

Verify Authentication

Example output:

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:
Keep your config file secure. It contains sensitive API keys. The file is created with restricted permissions (600) by default.

Environment Variables

Getting Your API Key

  1. Log in to the Telnyx Portal
  2. Navigate to API Keys
  3. Click Create API Key
  4. Copy the key (it won’t be shown again)
API keys start with 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 CLI

Command Reference

Source: https://developers.telnyx.com/development/cli/legacy/reference.md
This CLI is deprecated. For the current CLI commands, see Command Reference.

Authentication & Profiles

Phone Numbers

Search & Purchase

Manage Numbers

Messaging

Send Messages

List & Retrieve

Messaging Profiles

Voice

Make Calls

Call Control

Voice Profiles & Connections

10DLC

Interactive Setup

Brand Management

Campaign Management

Billing

Verification

Shell Autocomplete

Global Options

Migration to New CLI

See the Legacy CLI Overview for a command mapping to the new Go-based CLI.