Every Tella API operation behind one CLI, with a local SQLite store, FTS5 transcript search, and webhook tooling that replaces ngrok.
Tella ships an API and an official MCP server; this CLI gives you both surfaces in one binary, plus a local-first store that makes cross-video transcript search, view-milestone rollups, and webhook replay actually fast. Every endpoint is a Cobra command, every command emits structured JSON, and every mutation supports --dry-run.
Printed by @gregce (Greg Ceccarelli).
Authentication
Set TELLA_API_KEY to your Tella account API key (Account → Settings → API). Sent as Authorization: Bearer on every call. No OAuth, no refresh — it's a single static token.
Quick Start
# Save your Tella API key to local config; used by every command.
tella-pp-cli auth set-token
# Verify token + reachability before doing anything else.
tella-pp-cli doctor
# Sanity-check that you can see your workspace.
tella-pp-cli videos list --json --limit 5
# Populate the local SQLite store; required for transcript search and milestone digest.
tella-pp-cli sync
# Offline FTS5 search across every cached transcript.
tella-pp-cli transcripts search "pricing" --json
# Stream new webhook events to stdout; useful during integration development.
tella-pp-cli webhooks tail --follow
Unique Features
These capabilities aren't available in any other tool for this API.
Local-first transcendence
-
transcripts search — FTS5 search across every cached clip transcript in your workspace; returns video, clip, and timecode hits in milliseconds.
Use this when an agent or human needs to find every video that mentioned a topic without rehydrating the workspace from the API.
tella-pp-cli transcripts search "pricing change" --json --limit 10
-
videos viewed — Roll up webhook view-milestone events into a per-video summary over a window (e.g. who crossed 75% in the last 7 days).
Use this in a sales follow-up loop to triage prospects by engagement without scanning the dashboard.
tella-pp-cli videos viewed --since 7d --milestone 75 --json
-
workspace stats — Local aggregate of video count, clip count, total duration, transcript word count, and export count by month across the cached workspace.
Use this for monthly creator-economy reports without dashboard scraping.
tella-pp-cli workspace stats --json
Webhook tooling
-
webhooks tail — Stream new webhook events from the inbox to stdout, and replay any prior message to a local URL with valid HMAC headers — no public tunnel needed.
Use this when developing a webhook handler against Tella without exposing localhost via a tunnel.
tella-pp-cli webhooks tail --follow --json
Bulk operations
-
clips edit-pass — Apply a chained set of edits (remove-fillers, remove-buffers, trim-edges, trim-silences-gt N, find-mistakes [unofficial]) across every clip in a playlist in one command.
Use this to apply a creator's standard edit pass across an entire playlist without per-clip clicking.
tella-pp-cli clips edit-pass --playlist plst_42 --remove-fillers --remove-buffers --trim-edges --dry-run
Per-clip primitives also available individually:
videos clips remove-buffers <vid> <clipId> [--min-ms N] — UI-button equivalent: cuts every silence ≥ N ms (default 200). Public API only.videos clips trim-edges <vid> <clipId> — narrow primitive: cuts only the head and tail silences. Public API only.videos clips find-mistakes <vid> <clipId> --unofficial — AI mistake detection via Tella's web-app endpoint. Unofficial API; cookie-auth required. See the "Unofficial API: Find Mistakes" section below.
Unofficial API: Find Mistakes
Tella's web UI exposes an AI-driven "Find mistakes" button on the Cut panel. That endpoint is not part of the public API (verified 404 against api.tella.com on 2026-05-16), so find-mistakes opts into the same internal endpoint the web app uses. It requires a session cookie copied from a logged-in browser.
# 1) Open tella.tv in Chrome, DevTools → Application → Cookies → tella.tv.
# Right-click a row → Copy → Copy as cURL → take the value after "Cookie:".
# 2) Set the env var to the raw cookie header value (NOT prefixed with "Cookie:"):
export TELLA_SESSION_COOKIE='__Secure-Tella.session=...; XSRF-TOKEN=...'
# 3) Run with --unofficial:
tella-pp-cli videos clips find-mistakes vid_abc cl_xyz --unofficial --json
Detection step uses cookie auth against prod-stream.tella.tv (Server-Sent Events). Apply step uses the documented public /v1/.../cut endpoint (Bearer auth, additive — coexists with --remove-buffers and friends). Cookie expires periodically; refresh from DevTools when you see HTTP 401.
Warning: the unofficial AI service can change or break without notice. The CLI prints a fresh error message pointing you back to DevTools whenever the cookie returns 401. This auth surface is intentionally opt-in (--unofficial) so accidental shell usage doesn't hit a deprecated/unstable endpoint.
-
exports wait — Kick off exports for one or more videos and block until each is ready, short-circuiting on the Export ready webhook event.
Use this in batch publishing scripts that need export URLs for downstream uploads.
tella-pp-cli exports wait --video vid_1 --video vid_2 --timeout 10m --json
Transcript tooling
-
clips transcript-diff — Diff a clip's cut transcript against its uncut transcript to surface every word that editing removed (filler, silence, hand-edit) with timecodes.
Use this to audit what an automated edit pass actually changed before publishing.
tella-pp-cli clips transcript-diff clp_abc --json
-
clips captions — Format a clip's cut transcript as an SRT or VTT subtitle file ready to attach to an embed or upload.
Use this to ship caption files alongside video embeds without round-tripping through a separate caption tool.
tella-pp-cli clips captions clp_abc --format srt > captions.srt
Usage
Run tella-pp-cli --help for the full command reference and flag list.
Commands
playlists
Playlist operations
tella-pp-cli playlists create - Create a new playlist for the authenticated usertella-pp-cli playlists delete - Permanently delete a playlist. Videos in the playlist are not deleted.tella-pp-cli playlists get - Returns detailed information about a playlist including its videostella-pp-cli playlists list - Returns a list of all playlists for the authenticated usertella-pp-cli playlists update - Update a playlist's name and/or description
videos
Video operations
tella-pp-cli videos delete - Permanently delete a videotella-pp-cli videos get - Returns detailed information about a video including chapters, transcript, and thumbnailstella-pp-cli videos list - Returns a paginated list of all videos for the authenticated user. Use playlistId query parameter to filter videos by playlist.tella-pp-cli videos update - Update a video's settings including viewer options, download permissions, access controls, and metadata. Some features require Premium plan.
webhooks
Webhook endpoint management
tella-pp-cli webhooks create-endpoint - Creates a new webhook endpoint to receive events. Returns the endpoint ID and signing secret.tella-pp-cli webhooks delete-endpoint - Permanently deletes a webhook endpointtella-pp-cli webhooks get-endpoint-secret - Retrieves the signing secret for a webhook endpoint. Use this to verify incoming webhook payloads.tella-pp-cli webhooks get-message - Returns details of a specific webhook message by IDtella-pp-cli webhooks list-messages - Returns a list of recently sent webhook messages for debugging purposes
Output Formats
# Human-readable table (default in terminal, JSON when piped)
tella-pp-cli playlists list
# JSON for scripting and agents
tella-pp-cli playlists list --json
# Filter to specific fields
tella-pp-cli playlists list --json --select id,name,status
# Dry run — show the request without sending
tella-pp-cli playlists list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
tella-pp-cli playlists list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
tella-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/tella-public-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
TELLA_API_KEY | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
tella-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $TELLA_API_KEY
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 401 Unauthorized on every call — Re-fetch your API key at tella.tv → Account → Settings → API and run
tella-pp-cli auth set-token again.
- Empty results from
transcripts search --data-source local — Run tella-pp-cli sync first to populate the local transcripts table.
webhooks tail shows no events — Confirm a webhook endpoint is registered (tella-pp-cli webhooks endpoint create); the inbox only collects events for registered endpoints.clips edit-pass --dry-run shows zero planned mutations — Default short-circuits before fetching anything; the empty plan is by design. Drop --dry-run to see real planning (and use --apply to actually fire).--remove-buffers plans cuts but --trim-silences-gt 1s plans none — The --trim-silences-gt flag wants silences ≥ N; if every silence is shorter than your threshold the plan is empty. Use videos clips get-silences <id> <clipId> to inspect raw ranges, or rely on --remove-buffers (default 200 ms threshold).find-mistakes returns HTTP 401 — Your TELLA_SESSION_COOKIE expired. Refresh from Chrome DevTools → Application → Cookies → tella.tv → copy the cookie row back into the env var. The unofficial AI host (prod-stream.tella.tv) does NOT accept the public-API Bearer token.- Export wait times out — Default timeout is 10m. Long videos can exceed; pass
--timeout 30m and ensure the Export ready webhook endpoint is registered for early termination.
Generated by CLI Printing Press