Media and Entertainment

Tella Public

tella-pp-cli

Every Tella API operation behind one CLI, with a local SQLite store, FTS5 transcript search, and webhook tooling...

Printed by @gregce (Greg Ceccarelli)

Install

npx — recommended

npx -y @mvanhorn/printing-press-library install tella

Installs the CLI binary and the agent skill (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and more). Add --cli-only or --skill-only for one half. Requires Node.

Hermes

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-tella --force

From the Hermes CLI. Inside a chat session use /skills install with the same path.

OpenClaw

Install the pp-tella skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-tella. The skill defines how its required CLI can be installed.

Paste this to your OpenClaw agent — the skill describes how to install its CLI.

Claude Desktop

This CLI ships an MCPB bundle. Download the latest release .mcpb and double-click it — Claude Desktop walks you through the install.

View source on GitHub →

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

videos clips clean / videos clean — Preview and apply recoverable cleanup passes without opening the browser editor. The clip command accepts manual playback-time and transcript-word ranges; the video command discovers every clip through Tella's official timeline endpoint.
```
# Preview, then apply the same clip cleanup.
tella-pp-cli videos clips clean vid_abc cl_xyz \
  --remove-fillers \
  --remove-silences natural \
  --find-mistakes --unofficial \
  --dry-run
tella-pp-cli videos clips clean vid_abc cl_xyz \
  --remove-fillers \
  --remove-silences natural \
  --find-mistakes --unofficial \
  --apply

# Cut hand-selected playback and transcript ranges in the same pass.
tella-pp-cli videos clips clean vid_abc cl_xyz \
  --range 1200:1800 --range 8400:9100 \
  --word-range 42:46 --dry-run

# Apply the official cleanup tools to every clip in a video.
tella-pp-cli videos clean vid_abc \
  --remove-fillers --remove-silences natural --dry-run
tella-pp-cli videos clean vid_abc \
  --remove-fillers --remove-silences natural --apply
```
Cleanup snapshots each clip's exact existing cuts before mutation and records the last known post-clean cuts returned by Tella. Manual time ranges are sent together in one cut_clip request so earlier cuts cannot shift later coordinates. Because Tella exposes no conditional cut update, a failed compound apply never restores automatically: it re-fetches touched clips, reports whether their state is unchanged, matches the last known cleanup result, is indeterminate, or conflicts. Explicit undo re-fetches the clip and refuses if its cuts diverged from that recorded post-clean state. This is an advisory read-time check, not an atomic server guarantee: snapshot restore apply requires --confirm-exclusive-editing, which you must pass only after ensuring nobody else can save that clip until the command finishes.

Tella's official silence modes are natural (pauses longer than 800ms), fast (>500ms), and faster (>300ms). --remove-buffers remains available for backward compatibility and preserves the older threshold-based composition (--buffer-min-ms, default 200ms), so it is more aggressive than official faster; choose one or the other.
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 stable transcript word indices; Tella resolves exact word timing.
- videos clips remove-silences <vid> <clipId> --mode natural --apply — official Tella silence-removal modes with preview-by-default safety.
- videos clips remove-buffers <vid> <clipId> [--min-ms N] — legacy threshold mode: 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. As of 2026-08-31 it is still absent from Tella's public OpenAPI schema and MCP tool reference, 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 uses cookie auth against prod-stream.tella.tv (Server-Sent Events). Applying detected ranges uses the documented public batched /v1/.../cut endpoint (Bearer auth, additive). Cookie expires periodically; refresh it from DevTools after 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

Current official transcript reads and corrections — get-transcript returns the cut-applied transcript with stable word indices. update-transcript-words changes transcript/caption text or visibility atomically; it never changes audio or timing.

tella-pp-cli videos clips get-transcript vid_abc cl_xyz --json
tella-pp-cli videos clips update-transcript-words vid_abc cl_xyz \
  --words '[{"index":12,"text":"Tella"},{"index":18,"hidden":true}]' \
  --dry-run
tella-pp-cli videos clips update-transcript-words vid_abc cl_xyz \
  --words '[{"index":12,"text":"Tella"},{"index":18,"hidden":true}]' \
  --apply

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

# Read the full outline, clean a clip, then inspect the recovery preview.
tella-pp-cli videos timeline vid_abc --include cuts,words --json
tella-pp-cli videos clips clean vid_abc cl_xyz --remove-fillers --remove-silences natural --dry-run
tella-pp-cli videos clips clean vid_abc cl_xyz --remove-fillers --remove-silences natural --apply
tella-pp-cli videos clips undo-last-cuts vid_abc cl_xyz --dry-run

# Apply undo only while you have exclusive editing access to this clip.
tella-pp-cli videos clips undo-last-cuts vid_abc cl_xyz --apply --confirm-exclusive-editing

# 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 inline cuts explicitly, or preview a snapshot's advisory divergence check.
tella-pp-cli videos clips restore-cuts vid_abc cl_xyz --cuts '[{"startTimeMs":100,"durationMs":150}]' --dry-run
tella-pp-cli videos clips restore-cuts vid_abc cl_xyz --snapshot cuts.json --dry-run
tella-pp-cli videos clips restore-cuts vid_abc cl_xyz --snapshot cuts.json --apply --confirm-exclusive-editing

# Adjust documented per-clip audio tracks. "inherit" clears an override.
tella-pp-cli videos clips update vid_abc cl_xyz --microphone-volume 0.8 --system-audio-volume 0 --dry-run
tella-pp-cli videos clips update vid_abc cl_xyz --microphone-volume 0.8 --system-audio-volume 0 --apply
tella-pp-cli videos clips update vid_abc cl_xyz --microphone-volume inherit --system-audio-volume inherit --apply

# Enable Studio Voice video-wide, then optionally opt a clip out.
tella-pp-cli videos update vid_abc --studio-voice true --dry-run
tella-pp-cli videos update vid_abc --studio-voice true --apply
tella-pp-cli videos clips update vid_abc cl_xyz --studio-voice false --dry-run
tella-pp-cli videos clips update vid_abc cl_xyz --studio-voice false --apply

# Atomically add timeline resources. apply-edits cannot add cuts.
tella-pp-cli videos apply-edits vid_abc --operations '[{"type":"add_zoom","operationId":"zoom-1","clipId":"cl_xyz","zoomType":"manualZoom","startTimeMs":1000,"durationMs":1500,"scale":2}]' --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.

The CLI uses Tella's user-facing Studio Voice name, while translating it to the public API's studioSound field. Enabling it on a video starts enhanced-audio generation asynchronously; playback and exports use the raw audio until that version is ready. The clip setting opts an individual clip out (false) or re-enables it (true) under the video's master switch. When --stdin is combined with typed audio or Studio Voice flags, the typed flags are validated and override the corresponding JSON fields.

Tella's editor added whole-clip mute in August 2026, but the current public update_clip schema and MCP reference do not expose that toggle. The CLI therefore does not guess a mute field. Use the documented microphone/system volume overrides above when those tracks exist; setting both to 0 is not presented as equivalent to Tella's undoable UI mute.

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).
Choosing a silence option — Prefer --remove-silences natural|fast|faster for Tella's official modes. Legacy --remove-buffers uses the exact --buffer-min-ms threshold (default 200ms) through get-silences + batched cut, so it intentionally differs from official faster (>300ms). The cleanup command rejects using both together.
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