pp-tella

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/media-and-entertainment/tella/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Tella — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `tella-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install tella --cli-only
   ```
2. Verify: `tella-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

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

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Reach for tella-pp-cli when you need agent-shaped Tella operations: scripted batch edits across a playlist, cross-video transcript search for an agent, webhook handler development without a tunnel, or programmatic export pipelines. The local SQLite store makes it ideal when an agent will issue many small queries against the same workspace.

## Unique Capabilities

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

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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>` — UI-button equivalent: cuts every silence ≥ `--min-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-driven mistake detection. **Unofficial API** — see below.

### Unofficial API: Find Mistakes

Tella's web UI has a "Find mistakes" button on the Cut panel that calls an AI service. 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. This requires a session cookie copied from a logged-in browser.

```bash
# 1) In Chrome on tella.tv: DevTools → Application → Cookies → tella.tv
#    Right-click a row → Copy → Copy as cURL → grab the `Cookie: ...` line.
# 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
```

The detection step uses cookie auth against `prod-stream.tella.tv`; the apply step writes via the documented public `/cut` endpoint (Bearer auth, additive). Cookie expires periodically; refresh from DevTools when you see HTTP 401.

> **Warning:** the unofficial AI service can change or break without notice. Pin to a Tella web-app version if reliability matters.

- **`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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  tella-pp-cli clips captions clp_abc --format srt > captions.srt
  ```

## Command Reference

**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...
- `tella-pp-cli videos update` — Update a video's settings including viewer options, download permissions, access controls, and metadata. Some...

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

### Finding the right comm