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#

ActionDescriptionKey FlagslistList 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.

ActionDescriptionKey Flagslist <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 thumbnailsame 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 blurany of the mask flags aboveremove-blur <videoId> <clipId> <maskId>Remove a blur-list-highlights <videoId> <clipId>List highlight masks-add-highlight <videoId> <clipId>Add a highlightsame mask flags as add-blur``update-highlight <videoId> <clipId> <maskId>Update a highlightmask flagsremove-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 zoomsame as add-zoom``remove-zoom <videoId> <clipId> <zoomId>Remove a zoom-

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

playlists#

ActionDescriptionKey FlagslistList all playlists--visibility (personal/org), --cursor, --limit, --fields``get <id>Get playlist details-createCreate 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#

ActionDescriptionKey Flagscreate-endpointSubscribe 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-messagesRecent 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