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

# CLI Reference

> Every CLI command in v0.2.5 — install from GitHub release binaries, authenticate, scaffold, deploy, and manage revisions, secrets, bindings, storage, and actor types.

`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](#auth)               | Log in via OAuth or API key; check or clear credentials  |
| [new-func](#new-func)       | Scaffold a project and register the function server-side |
| [ship](#ship)               | Upload, build, and deploy a function                     |
| [list](#list)               | List your functions with status and invoke URL           |
| [inspect](#inspect)         | One function's full details and actor bindings           |
| [status](#status)           | CLI self-diagnostics: config, auth, connectivity         |
| [revisions](#revisions)     | A function's deploy history                              |
| [rollback](#rollback)       | Retarget traffic to a previous revision                  |
| [secrets](#secrets)         | Manage organization-scoped secrets                       |
| [bindings](#bindings)       | Manage the org-level Telnyx API credential               |
| [types](#types)             | Generate `telnyx-env.d.ts` from the project manifest     |
| [storage](#storage)         | Manage KV namespaces and keys, and SQL databases         |
| [actors](#actors)           | Manage account-scoped Stateful Actor types               |
| [reset-func](#reset-func)   | Return a failed function to the `created` state          |
| [delete-func](#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](https://github.com/team-telnyx/edge-compute/releases) |

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

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

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

<Note>
  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](/docs/edge-compute/deploy).
</Note>

## new-func

```bash theme={null}
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](/docs/edge-compute/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](/docs/edge-compute/runtime/http-handler).

## ship

```bash theme={null}
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](/docs/edge-compute/deploy#staging-and-production). 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-0198c2c5-8.telnyxcompute.com
```

The scheme is `{func-name}-{func-id-prefix}.telnyxcompute.com` — see [Routes & Domains](/docs/edge-compute/configuration/routing). Each successful ship also produces an immutable revision ([revisions](#revisions), [rollback](#rollback)).

## list

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

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

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

```bash theme={null}
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](/docs/edge-compute/configuration/versions).

## rollback

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

```bash theme={null}
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](/docs/edge-compute/configuration/secrets) for both surfaces.

## bindings

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

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

```bash theme={null}
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                                          |
| `[storage.sqldb.<NAME>]`        | `env.<NAME>` is `SqlDatabase` from `@telnyx/edge-runtime` — requires the SDK at 0.9.0 or newer                            |
| `[[actors]]`                    | `env.<BINDING>` exposes the bound actor class's public method signatures (umbrella `telnyx.toml` projects only)           |
| `[[ratelimits]]`                | `env.<NAME>` is `RateLimiter` from `@telnyx/edge-runtime` — new in v0.4.0, requires the SDK at 0.9.2 or newer             |

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

<Note>
  `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](/docs/edge-compute/runtime/bindings).
</Note>

## storage

```bash theme={null}
telnyx-edge storage kv create --name my-cache
telnyx-edge storage kv key put <namespace-id> user/123 "hello" --ttl 30s
telnyx-edge storage sqldb create --name links-db
telnyx-edge storage sqldb execute links-db --remote --command "SELECT 1"
```

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](/docs/edge-compute/kv/cli).

`storage sqldb` manages SQL databases: create/list/get/delete, plus `execute` for running SQL against a database out-of-band and `migrations` for versioned schema files. It arrives in a later release than the v0.2.5 covered above — see the [SQL Databases CLI reference](/docs/edge-compute/sqldb/cli) for the version floor, full flags, and examples.

## actors

```bash theme={null}
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](/docs/edge-compute/stateful-actors) 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

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

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

## Related

* [Configuration](/docs/edge-compute/configuration) — every `func.toml` / `telnyx.toml` key the CLI reads
* [CI/CD](/docs/edge-compute/deploy) — install, authenticate, and ship from a pipeline
* [Versions & Rollback](/docs/edge-compute/configuration/versions) — how revisions and rollback behave
* [KV CLI](/docs/edge-compute/kv/cli) — the full `storage kv` surface
* [SQL Databases CLI](/docs/edge-compute/sqldb/cli) — the full `storage sqldb` surface, including `execute` and `migrations`
* [Stateful Actors](/docs/edge-compute/stateful-actors) — the projects behind `--actor` and the `actors` command