--- name: pp-tella description: "Edit recorded lessons, review a live preview, and deliver video with captions. Trigger phrases: `edit my Tella lesson`, `preview a Tella video`, `export Tella captions`, `use tella`, `run tella`." author: "Greg Ceccarelli" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - tella-pp-cli install: - kind: go bins: [tella-pp-cli] module: github.com/mvanhorn/printing-press-library/library/media-and-entertainment/tella/cmd/tella-pp-cli --- # 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.10 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead: ```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. Prepare lesson recordings with repeatable recipes and reversible transcript cuts. Keep the review step separate from export and delivery. ## When to Use This CLI Use for editing recorded lessons, reviewing live previews, and delivering exports with captions. ## Anti-triggers Do not use this CLI for: - Recording a screen or camera directly - Publishing videos without explicit approval ## Unique Capabilities ### More - **`transcripts search`** — FTS5 search across cached clip transcripts; returns video and clip references with matching text snippets. - **`videos viewed`** — Roll up webhook view-count milestone events into a per-video summary over a window (e.g. which videos reached 25 views in the last 7 days). - **`webhooks tail`** — webhooks tail streams or snapshots inbox events; webhooks replay separately replays prior messages to a local URL with valid HMAC headers. - **`clips edit-pass`** — Plan or apply public filler, buffer, edge and silence edits across playlist clips; use find-retakes for transcript retakes and agent-chats for semantic edits. - **`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. ```bash tella-pp-cli clips transcript-diff cl_example --video=vid_example --json ``` - **`sources upload-file`** — Create a Tella source and upload local media bytes to its pre-signed URL then return the source ID; use videos clips insert-file to upload and attach media to a video. - **`exports wait`** — Kick off exports for one or more videos and poll GET /v1/videos/{id}/exports/{exportId}, reporting progress and the download URL. Exit non-zero if an export fails or times out. ```bash tella-pp-cli exports wait --video=vid_example_one --video=vid_example_two --timeout 10m --json ``` - **`clips captions`** — Format a clip's cut transcript as an SRT or VTT subtitle file ready to attach to an embed or upload. ```bash tella-pp-cli clips captions cl_example --video=vid_example --format srt > captions.srt ``` - **`workspace stats`** — Local aggregate of video count, clip count, total duration, transcript word count, and export count by month across the cached workspace. - **`videos storyboard`** — Export editable video timeline and state only; use videos apply-storyboard --file PLAN.json --apply to apply a reviewed JSON edit plan. - **`videos clips insert-file`** — Upload local media into a Tella source and attach it as a clip; use videos clips add-broll for B-roll layout media. - **`videos clips cut-words`** — Plan or apply term-matched transcript-index cuts; use videos clips replace-word-ranges for replacement media. - **`videos audit`** — Scan a video timeline for likely issues such as long silences before export or sharing. - **`playlists edit-pass`** — Plan a standard remove-fillers/remove-buffers/trim-edges/export recipe across every video in a playlist. - **`videos clips clean`** — Plan or apply official per-clip cleanup with automatic pre-apply cut snapshots and explicit recovery. - **`videos clips undo-last-cuts`** — Restore a saved cuts snapshot (latest by default or selected with --snapshot); use videos clips restore-cuts for inline cuts JSON and retain divergence checks and exclusive-editing confirmation. ### Browser-free lessons - **`videos auto`** — Apply selected automatic edits across clips with recovery snapshots and finish with a live preview. - **`lessons pass`** — Prepare a lesson from a validated recipe and finish with a preview for review. - **`lessons ship`** — Export, wait, and download a lesson MP4 and SRT or VTT captions. - **`clips find-retakes`** — Propose repeated sentence cuts with timestamps and apply reviewed cuts under snapshots. - **`videos storyboard-image`** — Save video, clip, or source storyboard images for visual inspection. ## Command Reference **account** — The signed-in user, their workspace, its plan and agent credits - `tella-pp-cli account` — The signed-in user, their workspace and role in it, the workspace's plan (and when a trial ends) and its agent credits **agent-chats** — Tella's editor agent, working in a video: start a chat and follow it - `tella-pp-cli agent-chats list` — The editor agent chats in a video, most recently active first, each with its `status` and `lastReply`. - `tella-pp-cli agent-chats start` — Start a chat with Tella's editor agent in a video you can edit, as if you had typed `prompt` in its agent chat **auto-captures** — Screen walkthroughs an agent films of a web page with no one recording. Takes are started and read over the MCP server **backgrounds** — Personal, workspace, and default video backgrounds - `tella-pp-cli backgrounds` — Returns personal uploads, workspace uploads, and Tella's default image and animated backgrounds in named categories. **library** — Reusable media saved to a workspace, plus Tella's curated sound effect and background music catalogs — the same items the editor's media panels show - `tella-pp-cli library capture-screenshot` — Deprecated: use `POST /v1/library/imports`, which takes the same `url` and `scroll` and also imports video links. - `tella-pp-cli library create-generation` — Starts generating an image - `tella-pp-cli library create-item` — Saves an uploaded source to the library so it can be listed and reused later - `tella-pp-cli library delete-item` — Removes an item from the library. - `tella-pp-cli library get-generation` — Returns the current status of a generation started with `POST /v1/library/generations`. - `tella-pp-cli library get-import` — Returns the status of an import started with `POST /v1/library/imports`. Pass the same `videoId` it was started with. - `tella-pp-cli library list-items` — Returns a page of reusable media saved to the library — images, videos, screenshots, sound effects - `tella-pp-cli library start-import` — Brings media into Tella from a link. **motion** — Manage motion - `tella-pp-cli motion apply-commands` — Applies a batch of ops and the editor's own commands as one transaction and one undo step - `tella-pp-cli motion create-clip` — Adds a clip at the end of a video that plays a blank Tella Motion document of its own - `tella-pp-cli motion create-document` — Creates a blank document, 10 s long (the `canvas.set` op changes that). - `tella-pp-cli motion download-document` — Returns the whole stored document and its `seq`. Large: pull out what you need rather than reading it in full. - `tella-pp-cli motion duplicate-document` — Copies a document under the same owner and optionally edits the copy in the same request with `commands`. - `tella-pp-cli motion get-composition` — Returns a composition asset's node outline and the instances that play it. Editing it changes all of them. - `tella-pp-cli motion get-document` — Returns the document's canvas, the outline of its nodes, its compositions and assets - `tella-pp-cli motion get-document-thumbnail` — Returns a signed CDN URL for a still image (jpg/png/webp) or animated preview (gif/mp4) of the document on its own - `tella-pp-cli motion get-node` — Returns one node with every stored field, its window, the composition it sits in and, for an instance - `tella-pp-cli motion get-schema` — Returns the JSON schema of a document (`schema=document`), of every edit a commands batch takes (`schema=edits`) - `tella-pp-cli motion inspect-node` — Returns a node as the editor's inspector shows it at a time: properties with units, values and keyframes - `tella-pp-cli motion list-documents` — Lists Tella Motion documents you can edit, newest first. - `tella-pp-cli motion list-effects` — Returns the effect kinds the `addEffect` command puts on a node's stack, each with its parameters' names, types, ranges - `tella-pp-cli motion list-fonts` — Returns the fonts a title can be set in: the catalog's by slug - `tella-pp-cli motion list-media` — Returns the videos, sounds and images already in the document, with the `mediaId` the `addMedia` command places. **playlist-groups** — Sidebar groups for organizing playlists - `tella-pp-cli playlist-groups create` — Create a sidebar group to organize playlists into. - `tella-pp-cli playlist-groups delete` — Delete a playlist group. Playlists in the group are not deleted, they just become ungrouped. - `tella-pp-cli playlist-groups list` — Returns the sidebar playlist groups for the authenticated user, in sidebar order. - `tella-pp-cli playlist-groups update` — Rename a playlist group and/or move it to a position in its sidebar section (0 = top) **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. **social-accounts** — Manage social accounts - `tella-pp-cli social-accounts` — Lists the social accounts you have connected in Tella that POST /v1/videos/{id}/publish can post with **sources** — Manage sources - `tella-pp-cli sources create` — Returns a `sourceId` and a pre-signed S3 URL. - `tella-pp-cli sources get` — Returns whether a source from `POST /v1/sources` is ready to use, however it was placed (clip, b-roll, overlay **subtitle-presets** — Manage subtitle presets - `tella-pp-cli subtitle-presets list` — Returns Tella's built-in subtitle presets and the authenticated user's saved presets. - `tella-pp-cli subtitle-presets save` — Saves a subtitle look as a personal preset, like the editor's 'Save as preset'. **tags** — Tags for categorizing and filtering videos - `tella-pp-cli tags create` — Create a workspace or private tag. When no color is given, one is derived deterministically from the name. - `tella-pp-cli tags delete` — Permanently delete a tag and remove it from all videos. Private tags can only be deleted by their creator. - `tella-pp-cli tags list` — Returns all tags visible to the authenticated user: the workspace's shared tags plus the user's private tags - `tella-pp-cli tags update` — Update a tag's name, color and/or description. Private tags can only be updated by their creator. **tella-public-analytics** — Manage tella public analytics - `tella-pp-cli tella-public-analytics` — Viewing analytics aggregated across videos: by default every video shared with the workspace **text-presets** — Manage text presets - `tella-pp-cli text-presets delete` — Deletes one of the authenticated user's saved text presets. Built-in `default:` presets can't be deleted. - `tella-pp-cli text-presets list` — Returns Tella's built-in text styles and the authenticated user's saved text presets — the tiles the editor's Text - `tella-pp-cli text-presets save` — Saves a personal text preset, like the editor's 'Save style' on a text overlay. **videos** — Video operations - `tella-pp-cli videos create` — Create a new video. - `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. - `tella-pp-cli videos search` — Search the authenticated user's direct video library by title or indexed transcript sentences. - `tella-pp-cli videos update` — Update a video's settings including viewer options, download permissions, access controls, and metadata. **webhooks** — Webhook endpoint management - `tella-pp-cli webhooks create-endpoint` — Creates a new webhook endpoint owned by the authenticated API key's user. - `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-endpoints` — Lists the webhook subscriptions owned by the authenticated API key's user. - `tella-pp-cli webhooks list-messages` — Returns a list of recently sent webhook messages for debugging purposes - `tella-pp-cli webhooks update-endpoint` — Updates the delivery URL, subscribed event types, or delivery status for a webhook endpoint. **clips** - `tella-pp-cli clips edit-pass` — Plan or apply public filler, buffer, edge and silence edits across playlist clips; use find-retakes for transcript retakes and agent-chats for semantic edits. - `tella-pp-cli 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. - `tella-pp-cli clips captions` — Format a clip's cut transcript as an SRT or VTT subtitle file ready to attach to an embed or upload. - `tella-pp-cli clips find-retakes` — Propose repeated sentence cuts with timestamps and apply reviewed cuts under snapshots. **exports** - `tella-pp-cli exports wait` — Kick off exports for one or more videos and poll GET /v1/videos/{id}/exports/{exportId}, reporting progress and the download URL. Exit non-zero if an export fails or times out. **lessons** - `tella-pp-cli lessons pass` — Prepare a lesson from a validated recipe and finish with a preview for review. - `tella-pp-cli lessons ship` — Export, wait, and download a lesson MP4 and SRT or VTT captions. **playlists** - `tella-pp-cli playlists edit-pass` — Plan a standard remove-fillers/remove-buffers/trim-edges/export recipe across every video in a playlist. **sources** - `tella-pp-cli sources upload-file` — Create a Tella source and upload local media bytes to its pre-signed URL then return the source ID; use videos clips insert-file to upload and attach media to a video. **transcripts** - `tella-pp-cli transcripts search` — FTS5 search across cached clip transcripts; returns video and clip references with matching text snippets. **videos** - `tella-pp-cli videos viewed` — Roll up webhook view-count milestone events into a per-video summary over a window (e.g. which videos reached 25 views in the last 7 days). - `tella-pp-cli videos clips insert-file` — Upload local media into a Tella source and attach it as a clip; use videos clips add-broll for B-roll layout media. - `tella-pp-cli videos clips cut-words` — Plan or apply term-matched transcript-index cuts; use videos clips replace-word-ranges for replacement media. - `tella-pp-cli videos audit` — Scan a video timeline for likely issues such as long silences before export or sharing. - `tella-pp-cli videos clips clean` — Plan or apply official per-clip cleanup with automatic pre-apply cut snapshots and explicit recovery. - `tella-pp-cli videos clips undo-last-cuts` — Restore a saved cuts snapshot (latest by default or selected with --snapshot); use videos clips restore-cuts for inline cuts JSON and retain divergence checks and exclusive-editing confirmation. - `tella-pp-cli videos auto` — Apply selected automatic edits across clips with recovery snapshots and finish with a live preview. - `tella-pp-cli videos storyboard-image` — Save video, clip, or source storyboard images for visual inspection. **webhooks** - `tella-pp-cli webhooks tail` — webhooks tail streams or snapshots inbox events; webhooks replay separately replays prior messages to a local URL with valid HMAC headers. **workspace** - `tella-pp-cli workspace stats` — Local aggregate of video count, clip count, total duration, transcript word count, and export count by month across the cached workspace. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash tella-pp-cli which "" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. `--json` (and other machine formats) keep that exit-2 contract and write `{"matches":[]}` on stdout so agents can inspect the envelope without treating a miss as success. ## Recipes ### Plan a lesson pass ```bash tella-pp-cli lessons pass vid_lesson --dry-run --json ``` Inspect the house-style edit plan before applying it. ## Auth Setup Run `tella-pp-cli auth setup` for the URL and steps to obtain a token (add `--launch` to open the URL). Then store it: ```bash echo "$TOKEN" | tella-pp-cli auth set-token ``` Or set `TELLA_API_KEY` as an environment variable. Run `tella-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color`. Global format flags share one contract on promoted, novel, sync, and `--deliver` paths: - `--json` — one JSON document on stdout (sync progress events go to stderr) - `--compact` — keep identity/status/timestamp fields; does not change the document vs stream shape - `--csv` / `--plain` — tabular rows (collection envelopes unwrap to the row array). `--csv` prefixes `'` on a cell or header key that starts with `=`, `+`, `-`, `@`, tab, CR, or LF (fullwidth `＝＋－＠` too) so a spreadsheet does not run it as a formula; a plain signed number such as `-5` or `+2.5e3` is unchanged. - `--quiet` — one identity value per row, no envelope - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash