CLI Reference

telnyx-edge is the command-line tool for Edge Compute: it scaffolds function projects, deploys them, and manages the resources they bind. This page covers every command in v0.2.5.

Command	What it does
auth	Log in via OAuth or API key; check or clear credentials
new-func	Scaffold a project and register the function server-side
ship	Upload, build, and deploy a function
list	List your functions with status and invoke URL
inspect	One function’s full details and actor bindings
status	CLI self-diagnostics: config, auth, connectivity
revisions	A function’s deploy history
rollback	Retarget traffic to a previous revision
secrets	Manage organization-scoped secrets
bindings	Manage the org-level Telnyx API credential
types	Generate `telnyx-env.d.ts` from the project manifest
storage	Manage KV namespaces and keys
actors	Manage account-scoped Stateful Actor types
reset-func	Return a failed function to the `created` state
delete-func	Delete a function permanently

Installation

The CLI ships as GitHub release binaries only — it is not on npm and there is no Homebrew formula. Assets are version-stamped; there is no un-versioned “latest” asset (releases/latest/download/... URLs return 404).

Platform	Asset
Linux amd64	`telnyx-edge-v0.2.5-linux-amd64.tar.gz`
Linux arm64	`telnyx-edge-v0.2.5-linux-arm64.tar.gz`
macOS arm64 (Apple silicon)	`telnyx-edge-v0.2.5-macos-arm64.tar.gz`
macOS amd64 (Intel)	`telnyx-edge-v0.2.5-macos-amd64.tar.gz`
Windows	`.zip` archives on the same release page

Each tarball extracts into a versioned directory containing the telnyx-edge binary:

VERSION=v0.2.5

curl -fsSL "https://github.com/team-telnyx/edge-compute/releases/download/${VERSION}/telnyx-edge-${VERSION}-linux-amd64.tar.gz" | tar xz
sudo mv "telnyx-edge-${VERSION}-linux-amd64/telnyx-edge" /usr/local/bin/

telnyx-edge --version   # prints the installed version

For macOS, substitute macos-arm64 (Apple silicon) or macos-amd64 (Intel) in both lines. To update, download the new version’s asset and replace the binary the same way.

Global flags and configuration

Flag	Effect
`-h`, `--help`	Help for any command: `telnyx-edge <command> --help`
`-v`, `--verbose`	Verbose logging — the first thing to try on an obscure failure
`--version`	Print the CLI version (root command only)

Credentials persist in ~/.telnyx-edge/config.toml. Two environment variables affect the binary itself: TELNYX_CONFIG_PATH relocates the config file, and TELNYX_NO_UPDATE_CHECK disables the release update check.

auth

telnyx-edge auth login                       # OAuth 2.0 in the browser
telnyx-edge auth api-key set "KEY..."        # persist a Telnyx API key instead
telnyx-edge auth status                      # who am I, and does the token work
telnyx-edge auth logout                      # clear stored tokens

login opens a browser for OAuth; api-key set writes the key to ~/.telnyx-edge/config.toml. Both end in the same place — subsequent commands read the stored credential.

The CLI does not read a TELNYX_API_KEY environment variable. In CI, run telnyx-edge auth api-key set "$TELNYX_API_KEY" as a pipeline step — see CI/CD.

new-func

telnyx-edge new-func -l ts -n my-func
cd my-func

Flag	Description
`-l`, `--language`	Runtime — exactly one of `go`, `js`, `ts`, `python`, `quarkus`. Required unless `--from-dir` is given; the value is exact (`javascript` is rejected).
`-n`, `--name`	Function name. Becomes the directory name and part of the URL.
`--actor`	Scaffold a Stateful Actor (`telnyx.toml`) project — TypeScript only. See the Stateful Actors quick start.
`--from-dir`	Copy files from an existing directory instead of a language scaffold.

new-func does two things: it creates a project directory (the command fails if one with that name already exists), and it registers the function server-side — so it requires authentication, and the generated func.toml already contains the function’s UUID func_id. Rapid successive calls can hit HTTP 429 rate limits. What each scaffold contains:

Language	Files
`ts`	`func.toml`, `index.ts`, `package.json`, `tsconfig.json`
`js`	`func.toml`, `index.js`, `package.json`
`go`	`func.toml`, `handler.go`, `go.mod`
`python`	`func.toml`, `function/func.py`, `pyproject.toml`
`quarkus`	`func.toml`, `pom.xml`, `mvnw`, `.mvn/`, `src/main/java/functions/`

The entrypoint contract differs per language — see HTTP handler.

ship

telnyx-edge ship                       # deploy the function in the current directory
telnyx-edge ship --from-dir ../other   # or any relative, absolute, or ~/ path

Flag	Description
`-f`, `--from-dir`	Path to the function directory (default: current directory)
`-t`, `--timeout`	Deployment monitoring timeout as a Go duration (`2m`, `300s`; default `5m0s`)

ship uploads, builds, pushes, and deploys the function named by the directory’s func.toml. There is no environment flag — staging and production are separate functions. Umbrella projects (telnyx.toml) are bundled client-side before upload: the module graph rooted at main is compiled into a single file with esbuild (TypeScript/JavaScript only), and the manifest is included so the platform can deploy any [[actors]] it declares. On success, ship prints the live URL — stable across deploys:

📡 Your function is live at:
   https://my-func-myorg.telnyxcompute.com

The scheme is {func-name}-{org-nickname}.telnyxcompute.com — see Routes & Domains. Each successful ship also produces an immutable revision (revisions, rollback).

list

telnyx-edge list
telnyx-edge list --page 2 --page-size 50

Lists your functions — id, name, status, creation time, and invoke URL. Paginated: --page (default 1) and --page-size (default 25).

inspect

telnyx-edge inspect my-func   # accepts a name or an id (first column of 'list')

Shows one function’s status, invoke URL, and timestamps, plus the actor types it binds — each binding’s type, status, and owner/reference role.

status

telnyx-edge status

Self-diagnostics: config file existence, authentication status, and connectivity to https://api.telnyx.com. Run it first when any other command misbehaves.

revisions

telnyx-edge revisions list my-func

Lists the most recent revisions for a function, newest first, with each revision’s id, ship time, author, and deploy status; the revision currently serving traffic is marked. Every successful ship produces an immutable revision — see Versions & Rollback.

rollback

telnyx-edge rollback my-func a1b2c3d
# → Rollback of 'my-func' to revision a1b2c3d accepted; traffic is switching across clusters.

Instantly retargets traffic to an existing, immutable revision across all clusters — no rebuild, no re-upload. Only revisions that reached deploy_ok can be rolled back to; get ids from revisions list. Your source tree is untouched — the next ship deploys whatever is on disk, as a new revision.

secrets

Secrets are organization-scoped key-value pairs for sensitive data. The arguments are positional — there are no --name/--value flags:

telnyx-edge secrets add STRIPE_API_KEY "sk_live_abc123"
# → Secret 'STRIPE_API_KEY' added successfully

telnyx-edge secrets list      # keys only — values are never shown
telnyx-edge secrets delete OLD_API_KEY

add on an existing key overwrites it. Values are injected at deploy time, so ship each function that uses a changed secret. Functions read secrets two ways, and both are always true: every secret is injected as a plain environment variable into all functions in your organization, and TypeScript functions can additionally declare a [[secrets]] binding and read through the typed env.SECRETS.get(). See Secrets for both surfaces.

bindings

Manages the org-level Telnyx credential (one per organization) behind the Telnyx API binding. The per-function flow needs none of these commands — declaring [telnyx] in func.toml wires the binding automatically on ship.

telnyx-edge bindings create     # provision the org credential (one per organization)
telnyx-edge bindings get        # binding metadata
telnyx-edge bindings validate   # check the credential works
telnyx-edge bindings update     # regenerate — use if you suspect compromise
telnyx-edge bindings delete     # remove; functions lose automatic Telnyx API access

types

telnyx-edge types                  # writes telnyx-env.d.ts at the project root
telnyx-edge types -f ./my-func     # or point at another project directory

Generates TypeScript types for the env surface from your manifest (func.toml or telnyx.toml), folding every declared binding into one global Env interface:

Declaration	Generated type
`[telnyx]`	`env.<BINDING>` is the Telnyx client class from the `telnyx` npm package — `env.<BINDING>.balance.retrieve()` type-checks
`[[secrets]]`	`env.SECRETS.get()` accepts the literal union of declared handles → `Promise<string>`; a typo’d handle fails to compile
`[storage.kv.<NAME>]`	`env.<NAME>` is `KvNamespace` from `@telnyx/edge-runtime` — new in v0.2.3
`[storage.cloudstorage.<NAME>]`	`env.<NAME>` is `CloudStorageBucket` from `@telnyx/edge-runtime` — new in v0.2.4
`[[actors]]`	`env.<BINDING>` exposes the bound actor class’s public method signatures (umbrella `telnyx.toml` projects only)

Declarations only — no JavaScript, no runtime glue, no source edits. Re-run after changing any binding declaration.

types generates a .d.ts consumed by tsc — it has no effect on js, go, python, or quarkus runtimes. Bindings on those runtimes are reached over REST instead; see Bindings.

storage

telnyx-edge storage kv create --name my-cache
telnyx-edge storage kv key put <namespace-id> user/123 "hello" --ttl 30s

Manages KV storage namespaces and keys: storage kv covers namespace create/list/get/delete, and storage kv key covers put/get/list/delete including server-side TTL and prefix listing. Full flags and examples live in the KV CLI reference.

actors

telnyx-edge actors list               # the account's registered actor types
telnyx-edge actors inspect Account    # one type, its attached functions, + live instance count
telnyx-edge actors instances Account  # list persisted instances (type/id pairs)
telnyx-edge actors delete Account     # delete an account-scoped type

Inspects and manages the Stateful Actor types registered to your account (account-scoped, keyed by type). inspect reports the actor type’s live instance count; instances lists the persisted instances (type/id pairs, e.g. Counter/alice). Output renders backend state — never inferred from local files.

reset-func

telnyx-edge reset-func broken-func

Tears down a failed function’s deployed resources and returns it to the created state — preserving its id, name, and config — so you can fix the code and ship again. Allowed only from a terminal failure state (build_failed, deploy_failed, delete_failed); a healthy function can’t be reset (use delete-func), and an in-progress operation must finish first.

delete-func

telnyx-edge delete-func my-old-func

Deletes a function by name. This cannot be undone — the function, its revisions, and its URL are gone.

Configuration — every func.toml / telnyx.toml key the CLI reads
CI/CD — install, authenticate, and ship from a pipeline
Versions & Rollback — how revisions and rollback behave
KV CLI — the full storage kv surface
Stateful Actors — the projects behind --actor and the actors command

Overview

Get Started

Best Practices

Guides

Local Development

Configuration

CI/CD

Runtime APIs

Observability

CLI

Platform

For AI Agents

Installation

Global flags and configuration

auth

new-func

ship

list

inspect

status

revisions

rollback

secrets

bindings

types

storage

actors

reset-func

delete-func

​Installation

​Global flags and configuration

​auth

​new-func

​ship

​list

​inspect

​status

​revisions

​rollback

​secrets

​bindings

​types

​storage

​actors

​reset-func

​delete-func

​Related

Installation

Global flags and configuration

auth

new-func

ship

list

inspect

status

revisions

rollback

secrets

bindings

types

storage

actors

reset-func

delete-func

Related