telnyx-cli

Telnyx CLI

The official CLI for the Telnyx REST API.

It is generated with Stainless.

Installation

Installing with Go

To test or install the CLI locally, you need Go version 1.22 or later installed.

go install 'github.com/team-telnyx/telnyx-cli/cmd/telnyx@latest'

Once you have run go install, the binary is placed in your Go bin directory:

• Default location: $HOME/go/bin (or $GOPATH/bin if GOPATH is set)
• Check your path: Run go env GOPATH to see the base directory

If commands aren't found after installation, add the Go bin directory to your PATH:

# Add to your shell profile (.zshrc, .bashrc, etc.)
export PATH="$PATH:$(go env GOPATH)/bin"

Running Locally

After cloning the git repository for this project, you can use the scripts/run script to run the tool locally:

./scripts/run args...

Usage

The CLI follows a resource-based command structure:

telnyx [resource] <command> [flags...]

telnyx calls dial \
  --api-key 'My API Key' \
  --connection-id conn12345 \
  --from +15557654321 \
  --to "'+15551234567'" \
  --webhook-url https://your-webhook.url/events

For details about specific commands, use the --help flag.

Environment variables

Global flags

• --api-key (can also be set with TELNYX_API_KEY env var)
• --public-key (can also be set with TELNYX_PUBLIC_KEY env var)
• --client-id (can also be set with TELNYX_CLIENT_ID env var)
• --client-secret (can also be set with TELNYX_CLIENT_SECRET env var)
• --help - Show command line usage
• --debug - Enable debug logging (includes HTTP request/response details)
• --version, -v - Show the CLI version
• --base-url - Use a custom API backend URL
• --format - Change the output format (auto, explore, json, jsonl, pretty, raw, yaml)
• --format-error - Change the output format for errors (auto, explore, json, jsonl, pretty, raw, yaml)
• --transform - Transform the data output using GJSON syntax
• --transform-error - Transform the error output using GJSON syntax

Passing files as arguments

To pass files to your API, you can use the @myfile.ext syntax:

telnyx <command> --arg @abe.jpg

Files can also be passed inside JSON or YAML blobs:

telnyx <command> --arg '{image: "@abe.jpg"}'
# Equivalent:
telnyx <command> <<YAML
arg:
  image: "@abe.jpg"
YAML

If you need to pass a string literal that begins with an @ sign, you can escape the @ sign to avoid accidentally passing a file.

telnyx <command> --username '\@abe'

Explicit encoding

For JSON endpoints, the CLI tool does filetype sniffing to determine whether the file contents should be sent as a string literal (for plain text files) or as a base64-encoded string literal (for binary files). If you need to explicitly send the file as either plain text or base64-encoded data, you can use @file://myfile.txt (for string encoding) or @data://myfile.dat (for base64-encoding). Note that absolute paths will begin with @file:// or @data://, followed by a third / (for example, @file:///tmp/file.txt).

telnyx <command> --arg @data://file.txt

Verifying SMTP submission

telnyx email smtp verify sends one real message through Telnyx SMTP submission with your own API key and prints every server reply, stage by stage:

export TELNYX_API_KEY=...   # or pass --api-key
telnyx email smtp verify \
  --host <smtp submission host> \
  --from you@your-verified-domain.com \
  --to you@your-verified-domain.com

The command always issues STARTTLS before sending credentials, then authenticates with AUTH PLAIN using the literal username apikey. It stops at the first failing reply. The last line is always the verdict, VERIFIED: message UUID <uuid> (exit status 0) or FAILED at <stage>: <server reply> (exit status 1), with a portal note or a hint just before it. VERIFIED requires the exact acceptance reply 250 2.0.0 Ok: queued as <uuid>; a reply cut off before its line ending never counts. The API key never appears in the output, even if the server echoes it back. If the server sends more reply text than can be checked for the key in time (1 second per MB, at least 1 second), the transcript is withheld and the FAILED verdict says so in plain words instead of quoting it. Ctrl-C stops the session and still prints the transcript so far, redacted, before an interrupted verdict. Scripts should check the exit status rather than parse the output.

• --host (or TELNYX_SMTP_HOST) is required; there is no default host yet.
• --port defaults to 587.
• --to defaults to the --from address.
• --timeout (default 30s) bounds each reply; --data-timeout (default 5m) bounds message acceptance.

The test suite runs against an in-process SMTP server. A live run is opt-in: go test -tags smtp_live -run TestLive -v ./internal/smtpverify/ with TELNYX_API_KEY and TELNYX_SMTP_LIVE_FROM set (TELNYX_SMTP_LIVE_HOST defaults to the dev front door). When a prerequisite is missing (credentials unset, or the dev front door not resolving yet) the run is reported as GATED and skipped with exit status 0; any failure past that gate fails the test.

Linking different Go SDK versions

You can link the CLI against a different version of the Telnyx Go SDK for development purposes using the ./scripts/link script.

To link to a specific version from a repository (version can be a branch, git tag, or commit hash):

./scripts/link github.com/org/repo@version

To link to a local copy of the SDK:

./scripts/link ../path/to/telnyx-go

If you run the link script without any arguments, it will default to ../telnyx-go.