Skip to main content
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: 
telnyx phone-numbers list

​
JSON Format

Machine-readable output for scripting and automation: 
telnyx phone-numbers list --format json

​
YAML Format

Human-readable structured output: 
telnyx phone-numbers list --format yaml

​
Pretty Format

Indented, colorized JSON: 
telnyx phone-numbers list --format pretty

​
Raw Format

Unformatted API response: 
telnyx phone-numbers list --format raw

​
All Format Options

FormatDescriptionBest For
autoInteractive exploration (default)Browsing data
jsonCompact JSONScripting, piping to jq
jsonlJSON Lines (one object per line)Streaming, large datasets
prettyIndented, colorized JSONDebugging
yamlYAML formatHuman-readable configs
rawUnformatted API responseDebugging

​
Transforming Output with GJSON

Use --transform to extract specific fields using GJSON syntax: 
# Get first phone number
telnyx phone-numbers list --format json --transform "data.0.phone_number"

# Get all phone numbers as array
telnyx phone-numbers list --format json --transform "data.#.phone_number"

# Filter by status
telnyx phone-numbers list --format json --transform 'data.#(status=="active")#'

​
Filtering JSON with jq

Combine with jq for powerful filtering: 
# Get just phone numbers
telnyx phone-numbers list --format json | jq -r '.data[].phone_number'

# Count active numbers
telnyx phone-numbers list --format json | jq '[.data[] | select(.status == "active")] | length'

​
Pagination

List commands support pagination via filter parameters: 
# Limit results
telnyx phone-numbers list --page-size 10

# Paginate through results
telnyx phone-numbers list --page-size 50 --page-number 2

​
Filtering

Most list commands support filtering via individual --filter.* flags: 
# Filter numbers by status
telnyx phone-numbers list --filter.status active

# Filter by country (note: kebab-case, not snake_case)
telnyx available-phone-numbers list --filter.country-code US

# Multiple filters
telnyx phone-numbers list --filter.status active --filter.country-iso-alpha2 US

# Filter with features
telnyx available-phone-numbers list --filter.country-code US --filter.features sms
Filter flag names use kebab-case (e.g., --filter.country-code, not --filter.country_code).

​
Global Flags

These flags work with all commands:
FlagDescription
--format <format>Output format (auto, json, jsonl, pretty, yaml, raw)
--format-error <format>Error output format
--transform <gjson>Transform output with GJSON
--debugShow HTTP request/response details
--base-url <url>Override API base URL
--helpShow help for the command
--versionShow CLI version

​
Environment Variables

VariableDescription
TELNYX_API_KEYAPI key (required)

​
Scripting Examples

​
Bash: Bulk SMS Send

#!/bin/bash
# send-bulk-sms.sh

FROM="+15551234567"
NUMBERS=("15559876543" "15551112222" "15553334444")
MESSAGE="Your appointment is confirmed for tomorrow."

for number in "${NUMBERS[@]}"; do
  telnyx messages send --from "$FROM" --to "+$number" --text "$MESSAGE"
  echo "Sent to +$number"
  sleep 0.5  # Rate limiting
done

​
Bash: Export Numbers to CSV

#!/bin/bash
# export-numbers.sh

echo "phone_number,status,connection_id" > numbers.csv

telnyx phone-numbers list --format json | \
  jq -r '.data[] | [.phone_number, .status, .connection_id] | @csv' >> numbers.csv

echo "Exported to numbers.csv"

​
Bash: Monitor Account Balance

#!/bin/bash
# check-balance.sh

THRESHOLD=100

balance=$(telnyx balance retrieve --format json | jq -r '.data.balance')
balance_int=${balance%.*}

if [ "$balance_int" -lt "$THRESHOLD" ]; then
  echo "⚠️  Low balance warning: \$$balance"
  # Send alert, etc.
else
  echo "✓ Balance OK: \$$balance"
fi

​
GitHub Actions: Deploy Notification

name: Deploy Notification

on:
  deployment:
    types: [completed]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Install Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'

      - name: Install Telnyx CLI
        run: |
          go install github.com/team-telnyx/telnyx-cli/cmd/telnyx@latest
          echo "$(go env GOPATH)/bin" >> $GITHUB_PATH

      - name: Send SMS notification
        env:
          TELNYX_API_KEY: ${{ secrets.TELNYX_API_KEY }}
        run: |
          telnyx messages send \
            --from "${{ vars.TELNYX_NUMBER }}" \
            --to "${{ vars.ONCALL_NUMBER }}" \
            --text "✅ Deployment complete: ${{ github.repository }}@${{ github.sha }}"

​
Debug Mode

To inspect the full HTTP request and response: 
telnyx phone-numbers list --debug
This is useful for:
  • Troubleshooting authentication issues
  • Understanding the exact API calls being made
  • Debugging unexpected responses

​
Next Steps

Command Reference

Full list of all commands

Troubleshooting

Common issues and solutions