> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
telnyx phone-numbers list
```

### JSON Format

Machine-readable output for scripting and automation:

```bash theme={null}
telnyx phone-numbers list --format json
```

### YAML Format

Human-readable structured output:

```bash theme={null}
telnyx phone-numbers list --format yaml
```

### Pretty Format

Indented, colorized JSON:

```bash theme={null}
telnyx phone-numbers list --format pretty
```

### Raw Format

Unformatted API response:

```bash theme={null}
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](https://github.com/tidwall/gjson/blob/master/SYNTAX.md):

```bash theme={null}
# 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](https://jqlang.github.io/jq/) for powerful filtering:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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
```

<Note>
  Filter flag names use **kebab-case** (e.g., `--filter.country-code`, not `--filter.country_code`).
</Note>

## 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

```bash theme={null}
#!/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

```bash theme={null}
#!/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

```bash theme={null}
#!/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

```yaml theme={null}
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:

```bash theme={null}
telnyx phone-numbers list --debug
```

This is useful for:

* Troubleshooting authentication issues
* Understanding the exact API calls being made
* Debugging unexpected responses

## Next Steps

<CardGroup cols={2}>
  <Card title="Command Reference" icon="terminal" href="/development/cli/reference">
    Full list of all commands
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/development/cli/troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>

***