telactl

CLI for talking to Tela's internal services. Handles device-flow auth once, then exposes authenticated HTTP calls and OpenAPI introspection against any ingredient registered in Pantry.

Install

bun install
bun run build

The built binary lives at dist/index.mjs (declared as bin in package.json). Link it on your $PATH however you prefer.

For development, run the CLI directly:

bun run src/index.ts <command>

First run

1. Authenticate. The first command that needs auth triggers the device flow — it prints a verification URL and code, then waits on stdin. Press Enter to open your browser.

2. Populate the ingredient cache. telactl doesn't ship with a hardcoded list of services; it pulls them from Pantry:

   telactl update

   This writes ~/.telactl/ingredients.json. api ingredients expose the api, docs endpoints, docs reference, and docs guide subcommands; library ingredients expose docs reference and docs guide. Re-run telactl update whenever an ingredient is added, removed, or changes environments. update always authenticates against the production auth-api.

3. Set environment defaults for any ingredient with more than one environment:

   telactl env set <slug> <environment>

   Without a saved default, telactl falls back to tooling → production → staging → development. If none match, it refuses to pick one and asks for --env. Single-environment ingredients are auto-selected.

Credentials live in ~/.telactl/credentials.<slug>.json — the default (production) auth target uses credentials.production.json. When --auth-env / --auth-url selects a specific auth-api env, the slug is derived from that env. Force a re-login with telactl login --force.

Commands

Auth

telactl login  [--auth-env <slug>] [--auth-url <url>] [--force]
telactl whoami [--auth-env <slug>] [--auth-url <url>] [-p|--pretty]
telactl token  [--auth-env <slug>] [--auth-url <url>]
telactl token list [-p|--pretty]

--auth-env picks an auth-api environment by slug (matched against the auth-api ingredient in the cache; production is always available even without a cache). --auth-url overrides --auth-env with a raw URL.

token prints the stored access token for the resolved auth env. token list shows all stored credentials with validity checks.

Cache & environments

telactl update                        # refresh ingredient cache from Pantry (uses production auth)
telactl env list <slug> [-p|--pretty]
telactl env set  <slug> <environment> # save a default environment for an ingredient

Documentation

telactl docs endpoints <slug> [-p|--pretty]
telactl docs reference <slug> [-p|--pretty]
telactl docs reference <slug> <METHOD> <PATH> [-p|--pretty]
telactl docs reference <library-slug> [file-path] [-p|--pretty]
telactl docs guide     <slug> [path] [-p|--pretty]

reference is the API contract — OpenAPI spec for api ingredients (full or per-endpoint), TypeDoc reference for library ingredients. guide returns the ingredient's step-by-step usage docs (docs.guides) — typically README.md plus any nested files under the same directory. Especially useful for libraries.

Default output is raw/machine-friendly (minified JSON or verbatim text). -p / --pretty enables human-readable output: tables for endpoints, ANSI-colored markdown for reference and guide (TTY-aware).

All three commands always fetch from Pantry using a production auth token.

Requests

telactl api <slug> <METHOD> <PATH> [args...] [flags]

Args use HTTPie-style syntax:

| Syntax | Meaning | | --------------- | ---------------------------------------------------- | | name=value | JSON body field (string) | | name:=value | JSON body field (raw JSON — numbers, booleans, etc.) | | name==value | Query parameter | | Header:value | Request header |

Flags:

• --env <slug> — override the service environment for this call.
• --auth-url <url> — override auth-api URL resolution (useful when the service env has no same-named auth env).
• --body <string> — send a raw request body as-is (overrides field args). Sets Content-Type: application/json unless you pass a Content-Type: header arg.
• -p / --pretty — pretty-print response body as JSON (if parseable).

Default output is the response body verbatim (raw). Authorization: Bearer <token> and Accept: application/json are set automatically unless you override them with header args. When the service env has no matching auth-api env, telactl prompts interactively to pick one (unless --auth-url is passed).

Examples

# GET with a query param
telactl api pantry GET /ingredients limit==50 page==1

# POST with JSON fields (strings vs. raw JSON)
telactl api vault POST /files name=report.pdf size:=1024

# Raw body from a file
telactl api vault POST /files --body "$(cat body.json)"

# Custom header + non-default environment
telactl api pantry GET /ingredients X-Debug:1 --env staging

# Binary/non-JSON response (default output is raw/verbatim)
telactl api vault GET /files/abc123 > file.bin

Non-2xx responses print <status> <statusText> plus the body to stderr and exit 1.

Tech

• Built with Cliffy on Bun.
• Auth via @meistrari/auth-cli device flow.
• OpenAPI-to-markdown via openapi-to-md.