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:

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

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

clips

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

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

playlists

webhooks

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:

{ "ok": true, "data": { ... }, "meta": { "total": 42 } }

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

Quick Reference

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