tella

Tella 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).

Install

The recommended path installs both the tella-pp-cli binary and the pp-tella agent skill (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and other agents supported by the upstream skills CLI) in one shot:

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

For CLI only (no skill):

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

For skill only — installs the skill into the same agents as the default command above, but skips the CLI binary (use this to update or reinstall just the skill):

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

To constrain the skill install to one or more specific agents (repeatable — agent names match the skills CLI):

npx -y @mvanhorn/printing-press-library install tella --agent claude-code
npx -y @mvanhorn/printing-press-library install tella --agent claude-code --agent codex

Without Node (Go fallback)

If npx isn't available (no Node, offline), install the CLI directly via Go (requires Go 1.26.3 or newer):

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/tella/cmd/tella-pp-cli@latest

This installs the CLI only — no skill.

Pre-built binary

Download a pre-built binary for your platform from the latest release. On macOS, clear the Gatekeeper quarantine: xattr -d com.apple.quarantine <binary>. On Unix, mark it executable: chmod +x <binary>.

Install for Hermes

Install the CLI binary first. The installer writes binaries to a per-user managed bin directory by default: $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows.

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

Then install the focused Hermes skill.

From the Hermes CLI:

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

Inside a Hermes chat session:

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

Restart the Hermes session or gateway if the newly installed skill is not visible immediately.

Install for OpenClaw

Install both the CLI binary and the focused OpenClaw skill. The installer defaults binaries to a per-user bin directory ($HOME/.local/bin on macOS/Linux, %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows):

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

Restart the OpenClaw session or gateway if the newly installed skill is not visible immediately.

Use with Claude Desktop

This CLI ships an MCPB bundle — Claude Desktop's standard format for one-click MCP extension installs (no JSON config required).

To install:

1. Download the .mcpb for your platform from the latest release.
2. Double-click the .mcpb file. Claude Desktop opens and walks you through the install.
3. Fill in TELLA_API_KEY when Claude Desktop prompts you.

Requires Claude Desktop 1.0.0 or later. Pre-built bundles ship for macOS Apple Silicon (darwin-arm64) and Windows (amd64, arm64); for other platforms, use the manual config below.

Manual JSON config (advanced)

If you can't use the MCPB bundle (older Claude Desktop, unsupported platform), install the MCP binary and configure it manually.

Install the MCP binary from this CLI's published public-library entry or pre-built release.

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "tella": {
      "command": "tella-pp-mcp",
      "env": {
        "TELLA_API_KEY": "<your-key>"
      }
    }
  }
}

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 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

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 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