Scripting & Automation

Automate workflows with the Telnyx CLI using output formats, filtering, and JSON parsing — patterns for shell scripts, cron jobs, and CI/CD pipelines.

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

Format	Description	Best For
auto	Interactive exploration (default)	Browsing data
json	Compact JSON	Scripting, piping to jq
jsonl	JSON Lines (one object per line)	Streaming, large datasets
pretty	Indented, colorized JSON	Debugging
yaml	YAML format	Human-readable configs
raw	Unformatted API response	Debugging

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:

Flag	Description
--format <format>	Output format (auto, json, jsonl, pretty, yaml, raw)
--format-error <format>	Error output format
--transform <gjson>	Transform output with GJSON
--debug	Show HTTP request/response details
--base-url <url>	Override API base URL
--help	Show help for the command
--version	Show CLI version

Environment Variables

Variable	Description
TELNYX_API_KEY	API key (required)

Scripting Examples

Bash: Bulk SMS Send

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

FROM="[phone]"
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

---