telactl

CLI for talking to Tela services. It handles device-flow auth once, then lets you call authenticated APIs and inspect OpenAPI, TypeDoc, and guide docs for any ingredient registered in Pantry.

Install

Install the telactl binary globally with your package manager:

bun add -g @meistrari/telactl

npm install -g @meistrari/telactl

pnpm add -g @meistrari/telactl

Then verify the CLI is available:

telactl --help

Agent skill

This repository includes a Vercel Skills-compatible agent skill in skills/telactl. It teaches coding agents when and how to use telactl to discover Tela ingredients, read endpoint schemas, inspect library docs, and avoid rebuilding capabilities that already exist in Tela.

Install it with Vercel Skills from this repository:

bunx skills add meistrari/telactl

pnpx skills add meistrari/telactl

npx skills add meistrari/telactl

The skill assumes the telactl CLI is installed and authenticated on the machine where the agent runs.

Agents should run telactl with TELACTL_AGENT=1. This enables agent-friendly behavior when relevant: avoiding interactive sessions, skipping direct browser launches, and printing clear instructions for what the agent should ask the user to do next.

First run

1. Authenticate. Run the login command to start the device flow:

   telactl login

   It prints a verification URL and code, then waits on stdin. Press Enter to open your browser.

2. Populate the ingredient cache. telactl loads Tela services from Pantry instead of shipping a hardcoded service list:

   telactl update

   This writes ~/.telactl/ingredients.json. Re-run telactl update whenever an ingredient is added, removed, or changes environments. As a rule of thumb, run it every few days, or even before each use, to make sure your local ingredient cache is current.

Credentials live in ~/.telactl/credentials.<slug>.json. The default production auth target uses credentials.production.json. Force a re-login with:

telactl login --force

Common flows

Discover services

telactl api pantry GET /ingredients
telactl api pantry GET /ingredients query==file
telactl api pantry GET /ingredients type==library

pantry is always available, so you can use it to discover API services, libraries, and skills before building something from scratch.

Read documentation

telactl docs endpoints <slug>
telactl docs reference <slug>
telactl docs reference <slug> <METHOD> <PATH>
telactl docs guide <slug>
telactl docs guide <slug> <path>

Use endpoints to list API routes, reference for exact API or library contracts, and guide for step-by-step usage docs.

Call an API

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

Args use HTTPie-style syntax:

| Syntax | Meaning | | ------ | ------- | | name=value | JSON body field as a string | | name:=value | JSON body field as raw JSON | | name==value | Query parameter | | Header:value | Request header |

Examples:

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

# POST with JSON fields
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 and environment override
telactl api pantry GET /ingredients X-Debug:1 --env staging

Default output is raw and script-friendly: minified JSON or verbatim response text. Add -p / --pretty for human-readable output.

Commands

Auth

telactl login  [--auth-env <slug>] [--auth-url <url>] [--force] [--verbose]
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. --auth-url overrides it with a raw URL. login --verbose prints the login flow as compact one-line login key=value events, including auth target resolution, credential handling, branch decisions with selected and reason, user authorization, browser opening, poll wait/start/results, and final outcome. token prints the stored access token for the resolved auth environment, and token list shows stored credentials with validity checks.

When TELACTL_AGENT=1 is set, telactl uses more agent-friendly behavior where relevant. Whenever any command triggers device-flow authentication, it prints instructions for the agent to keep the process running in the background, ask the user to open the verification URL and authorize access, then wait for the background process to finish.

Cache and environments

telactl update
telactl env list <slug> [-p|--pretty]
telactl env set  <slug> <environment>

update refreshes the ingredient cache from Pantry using production auth.

Docs

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]

api ingredients expose api, docs endpoints, docs reference, and docs guide. library ingredients expose docs reference and docs guide.

Requests

telactl api <slug> <METHOD> <PATH> [args...] [--env <slug>] [--auth-url <url>] [--body <json>] [-p|--pretty]

Flags:

• --env <slug>: override the service environment for this call.
• --auth-url <url>: override auth-api URL resolution.
• --body <string>: send a raw request body as-is, overriding field args.
• -p / --pretty: pretty-print response body as JSON when parseable.

Authorization: Bearer <token> and Accept: application/json are set automatically unless you override them with header args. Content-Type: application/json is set whenever a body is sent unless you pass a Content-Type: header arg.

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

Development

Use this section only if you are changing the CLI itself.

Install dependencies and build the binary:

bun install
bun run build

The built binary lives at dist/index.mjs and is declared as bin in package.json.

Run the CLI from source while developing:

bun cli <command>

This is equivalent to:

bun run src/index.ts <command>

Run tests:

bun test

Tech stack:

• Bun
• Cliffy
• @meistrari/auth-cli device flow
• openapi-to-md