tella-cli

SKILL.md

---
name: tella
description: "Manage Tella via CLI - videos, clips, playlists, webhooks. Use when user mentions 'tella', 'tella.tv', 'tella video', 'screen recording', 'video transcript', 'clip thumbnail', 'video export', 'remove filler words', 'add zoom to video', 'blur video', 'highlight video', 'playlist of videos', or wants to interact with the Tella video recording/editing API."
category: video
---

# tella-cli

## When To Use This Skill

Use the `tella-cli` skill when you need to:

- List, fetch, update, or delete videos in a Tella workspace
- Pull transcripts (cut or uncut) for a clip with word-level timestamps
- Generate video or clip thumbnails (jpg/png/webp/gif/mp4) at custom sizes/timestamps
- Trigger video exports at 1080p or 4k, 30/60fps, with optional burned-in subtitles
- Duplicate a video or clip, optionally trimmed
- Edit clips: cut time ranges, reorder, remove filler words, find silent ranges
- Add or update visual edits: blurs, highlights, layouts, zooms (manual or tracking)
- Manage playlists and add/remove videos from them
- Add workspace collaborators (editor or viewer) to a video
- Create webhook endpoints, fetch signing secrets, and inspect recent deliveries

## Capabilities

- Read every video and playlist in the workspace, including metadata, view counts, and share links
- Push fine-grained edits to clips (cuts, reorders, blurs, highlights, layouts, zooms) without opening the Tella editor
- Pull transcripts for downstream search, summarization, or accessibility workflows
- Start exports and poll/list webhook deliveries to know when files are ready
- Manage sharing: `linkScope`, password, allowed embed domains, search-engine indexing
- Subscribe to events (`video.created`, `export.ready`, `transcript.ready`, etc.) and recover delivery messages

## Common Use Cases

- "List my last 20 Tella videos and dump them as JSON for a content audit"
- "Get the uncut transcript for clip X so I can generate chapter timestamps"
- "Export video Y at 4k 60fps with subtitles burned in"
- "Add a blur over the credentials shown between 4.2s and 7.8s on this clip"
- "Create a playlist 'Tutorials' and add these 5 videos to it"
- "Wire up a webhook so I get notified when an export is ready"
- "Remove filler words from this clip and then fetch the cleaned transcript"

## Setup

If `tella-cli` is not found, install and build it:
```bash
bun --version || curl -fsSL https://bun.sh/install | bash
npx api2cli bundle tella
npx api2cli link tella
```

`api2cli link` adds `~/.local/bin` to PATH automatically. The CLI is available in the next command.

Always use `--json` when calling commands programmatically.

## Working Rules

- Always use `--json` for agent-driven calls so downstream steps can parse the result
- Run `<resource> --help` or `<resource> <action> --help` when unsure of flags rather than guessing
- For destructive actions (`delete`, `remove-*`), read first with `get`/`list` to confirm the target
- Most clip mutations require both `<videoId>` and `<clipId>` as positional args (in that order)
- Coordinates for masks (blurs, highlights) and zoom focus points are normalized to `0-1` of the canvas
- Times are in milliseconds (`*-ms` flags) unless the docs say otherwise

## Authentication

```bash
tella-cli auth set "tella_pk_xxx..."   # API key from https://www.tella.tv/settings/api-keys
tella-cli auth test                     # Verify the key works
tella-cli auth show                     # Show masked token
tella-cli auth remove                   # Delete stored token
```

Token is stored at `~/.config/tokens/tella-cli.txt` (chmod 600).

## Resources

### videos

| Action | Description | Key Flags |
|--------|-------------|-----------|
| `list` | List videos in the workspace | `--cursor`, `--limit`, `--playlist-id`, `--fields` |
| `get <id>` | Get a single video's metadata | - |
| `update <id>` | Update title, description, sharing, playback | `--name`, `--description`, `--link-scope`, `--password`, `--allowed-embed-domains`, `--custom-thumbnail-url`, `--default-playback-rate`, `--captions-default-enabled`, `--comments-enabled`, `--comment-emails-enabled`, `--downloads-enabled`, `--raw-downloads-enabled`, `--publish-date-enabled`, `--search-engine-indexing-enabled`, `--transcripts-enabled`, `--view-count-enabled` |
| `delete <id>` | Delete a video | - |
| `duplicate <id>` | Duplicate, optionally trimmed | `--name`, `--trim-start-ms`, `--trim-end-ms` |
| `export <id>` | Start an export job | `--resolution` (1080p/4k), `--fps` (30/60), `--speed`, `--granularity` (video/clips/raw), `--subtitles` |
| `thumbnail <id>` | Get thumbnail/animated preview | `--format` (jpg/png/webp/gif/mp4), `--inpoint-ms`, `--duration-ms`, `--width`, `--height`, `--download`, `--response json` |
| `add-collaborator <id>` | Add a workspace member | `--email` (required), `--role editor\|viewer` (required) |

### clips

Most clip commands take `<videoId> <clipId>` as positional args.

| Action | Description | Key Flags |
|--------|-------------|-----------|
| `list <videoId>` | List clips for a video | `--fields` |
| `get <videoId> <clipId>` | Get a single clip | - |
| `update <videoId> <clipId>` | Rename or reorder | `--name`, `--order` |
| `delete <videoId> <clipId>` | Delete a clip | - |
| `duplicate <videoId> <clipId>` | Duplicate the clip | `--name`, `--order` |
| `cut <videoId> <clipId>` | Cut a time range out | `--from-ms` (req), `--to-ms` (req) |
| `reorder <videoId> <clipId>` | Move to new position | `--order` (req) |
| `remove-fillers <videoId> <clipId>` | Auto-remove filler words | - |
| `silences <videoId> <clipId>` | List silent ranges | `--min-duration-ms` |
| `transcript-cut <videoId> <clipId>` | Edited transcript (post-cuts) | - |
| `transcript-uncut <videoId> <clipId>` | Original transcript | - |
| `thumbnail <videoId> <clipId>` | Clip thumbnail/preview | `--format`, `--inpoint-ms`, `--duration-ms`, `--width`, `--height`, `--download`, `--response` |
| `list-sources <videoId> <clipId>` | List recording sources | `--fields` |
| `source-thumbnail <videoId> <clipId> <sourceId>` | Source thumbnail | same as clip `thumbnail` |
| `source-waveform <videoId> <clipId> <sourceId>` | Audio waveform JSON | - |
| `list-blurs <videoId> <clipId>` | List blur masks | - |
| `add-blur <videoId> <clipId>` | Add a blur mask | `--start-time-ms`, `--duration-ms`, `--point-x`, `--point-y`, `--dim-width`, `--dim-height` (all required) |
| `update-blur <videoId> <clipId> <maskId>` | Update a blur | any of the mask flags above |
| `remove-blur <videoId> <clipId> <maskId>` | Remove a blur | - |
| `list-highlights <videoId> <clipId>` | List highlight masks | - |
| `add-highlight <videoId> <clipId>` | Add a highlight | same mask flags as `add-blur` |
| `update-highlight <videoId> <clipId> <maskId>` | Update a highlight | mask flags |
| `remove-highlight <videoId> <clipId> <maskId>` | Remove a highlight | - |
| `list-layouts <videoId> <clipId>` | List layouts | - |
| `add-layout <videoId> <clipId>` | Add a layout (JSON shape) | `--layout` (JSON, req), `--start-time-ms`, `--duration-ms`, `--transition-style` |
| `update-layout <videoId> <clipId> <layoutId>` | Update a layout | `--layout`, time flags, `--transition-style` |
| `remove-layout <videoId> <clipId> <layoutId>` | Remove a layout | - |
| `list-zooms <videoId> <clipId>` | List zooms | - |
| `add-zoom <videoId> <clipId>` | Add a zoom | `--type manualZoom\|trackingZoom` (req), `--start-time-ms` (req), `--duration-ms` (req), `--scale`, `--focus-x`, `--focus-y` |
| `update-zoom <videoId> <clipId> <zoomId>` | Update a zoom | same as `add-zoom` |
| `remove-zoom <videoId> <clipId> <zoomId>` | Remove a zoom | - |

Mask coordinates (`--point-*`, `--dim-*`, `--focus-*`) are normalized `0-1` of the canvas.

### playlists

| Action | Description | Key Flags |
|--------|-------------|-----------|
| `list` | List all playlists | `--visibility` (personal/org), `--cursor`, `--limit`, `--fields` |
| `get <id>` | Get playlist details | - |
| `create` | Create a new playlist | `--name` (req), `--description`, `--emoji`, `--link-scope`, `--password`, `--visibility`, `--search-engine-indexing-enabled` |
| `update <id>` | Update a playlist | `--name`, `--description`, `--link-scope`, `--password`, `--search-engine-indexing-enabled` |
| `delete <id>` | Delete a playlist | - |
| `add-video <id>` | Add a video to it | `--video-id` (req) |
| `remove-video <id> <videoId>` | Remove a video from it | - |

### webhooks

| Action | Description | Key Flags |
|--------|-------------|-----------|
| `create-endpoint` | Subscribe to events | `--url` (req), `--filter-types` (req, comma-separated, e.g. `video.created,export.ready`) |
| `delete-endpoint <id>` | Delete an endpoint | - |
| `get-secret <id>` | Get the signing secret | - |
| `list-messages` | Recent delivery messages | `--event-types`, `--limit`, `--fields` |
| `get-message <id>` | Get a specific message | - |

Available event types include: `video.created`, `video.viewed`, `view.milestone`, `transcript.ready`, `export.ready`, `playlist.created`, `playlist.video_added`.

## Output Format

`--json` returns a standardized envelope:
```json
{ "ok": true, "data": { ... }, "meta": { "total": 42 } }
```

On error: `{ "ok": false, "error": { "message": "...", "status": 401 } }`

## Quick Reference

```bash
tella-cli --help                       # List all resources and global flags
tella-cli videos --help                # List actions on videos
tella-cli videos list --help           # Show flags for videos list
tella-cli clips add-zoom --help        # Show flags for add-zoom
```

## Global Flags

All commands support: `--json`, `--format <text|json|csv|yaml>`, `--verbose`, `--no-color`, `--no-header`

Exit codes: 0 = success, 1 = API error, 2 = usage error