Tella Public CLI

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.

Created 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 <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 cut <vid> <clipId> --range 2000:3500 --range 8000:9200 — cut multiple time ranges in one request.
  • videos clips cut-by-transcript <vid> <clipId> --word-range 12:17 — cut by uncut-transcript word indices; Tella resolves exact word timing.
  • 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.

• sources upload-file + videos clips add — Create a Tella source, upload local video bytes to the pre-signed URL, then add that source as a new clip.

  tella-pp-cli sources upload-file intro.mp4 --width 1920 --height 1080 --duration 42.5 --json
  tella-pp-cli videos clips add vid_abc --source-id src_123 --name Intro --json
  

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.

Novel editing workflows

These commands compose Tella's public edit primitives into agent-safe workflows:

# Upload a local file and add it as a new clip.
tella-pp-cli videos clips insert-file vid_abc intro.mp4 --width 1920 --height 1080 --duration 42.5 --dry-run

# Upload B-roll and attach it as layout media over a time range.
tella-pp-cli videos clips add-broll vid_abc cl_xyz broll.mp4 --width 1920 --height 1080 --duration 8.2 --start-ms 4000 --duration-ms 6000 --dry-run

# Clean a clip, then roll back cuts if needed.
tella-pp-cli videos clips clean vid_abc cl_xyz --remove-fillers --remove-buffers --trim-edges --dry-run
tella-pp-cli videos clips clean vid_abc cl_xyz --remove-fillers --remove-buffers --trim-edges --apply
tella-pp-cli videos clips undo-last-cuts vid_abc cl_xyz --dry-run

# Inspect edit substrate, then cut transcript words or replace word ranges.
tella-pp-cli videos clips silence-map vid_abc cl_xyz --json
tella-pp-cli videos clips cut-words vid_abc cl_xyz --term "mistake" --dry-run
tella-pp-cli videos clips replace-word-ranges vid_abc cl_xyz --word-ranges '[{"fromWordIndex":12,"toWordIndex":17}]' --dry-run

# Restore exact cuts explicitly.
tella-pp-cli videos clips restore-cuts vid_abc cl_xyz --cuts '[{"fromMs":100,"toMs":250}]' --dry-run

# Export/apply a full video edit plan.
tella-pp-cli videos storyboard vid_abc --include-transcript --json > storyboard.json
tella-pp-cli videos apply-storyboard vid_abc --file storyboard.json --dry-run

# Presets, QA, and playlist-scale edit planning.
tella-pp-cli videos format vid_abc --preset shorts --dry-run
tella-pp-cli videos audit vid_abc --json
tella-pp-cli playlists edit-pass plst_42 --remove-fillers --remove-buffers --trim-edges --dry-run

Commands default to dry-run/plan mode when they perform compound edits; pass each command's --apply flag where available, or drop global --dry-run, only after reviewing the emitted plan.

Commands

playlists

Playlist operations

• tella-pp-cli playlists create - Create a new playlist for the authenticated user
• tella-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 videos
• tella-pp-cli playlists list - Returns a list of all playlists for the authenticated user
• tella-pp-cli playlists update - Update a playlist's name and/or description

sources

Uploaded video sources for clips and B-roll layouts

• tella-pp-cli sources create - Create a new video source upload and return a sourceId plus pre-signed uploadUrl
• tella-pp-cli sources upload-file - Create a source and upload a local video file to the pre-signed URL

videos

Video operations

• tella-pp-cli videos delete - Permanently delete a video
• tella-pp-cli videos get - Returns detailed information about a video including chapters, transcript, and thumbnails
• tella-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 endpoint
• tella-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 ID
• tella-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 <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