STEP 1 — Transcribe a podcast video/audio file. This is typically the first tool you call.

What it does: Uses Whisper AI for word-level timestamps. Speaker detection (who said what) is off by default; pass enable_diarization=true to add speaker labels where torch/pyannote is available (whisper-py engine). Returns: Lightweight metadata only — duration, language, word/segment counts, speaker summary, and packed_ready flag. The actual transcript body is NOT returned here (it would be 500KB+ for a typical episode). Read the content via get_ui_state(include_transcript: true) which returns a compact phrase-grouped markdown view (~10x smaller than raw segments). Caching: Results are cached by file hash — same file won't be re-transcribed. Supported formats: MP4, MOV, WebM, MKV, MP3, WAV.

After transcription: call get_ui_state(include_transcript: true) to read the transcript, then analyze it for viral moments and call suggest_clips.

Start transcription as a background job and return a job_id immediately. Use this instead of transcribe_podcast for long files so you can narrate progress to the user while it runs (a 60-min episode takes 15–25 min).

Flow: call transcribe_start(file_path) → emit status text to user → call job_status(job_id, wait_seconds: 30) in a loop until done → then read the packed transcript via get_ui_state(include_transcript: true).

Requires the Web UI to be running (npm run ui). Returns { job_id, cached, status, estimate_minutes }.

Poll the status of any background job (transcription, clip render, batch export). Supports long-polling: pass wait_seconds (1–60) to block until the job changes state or the timeout elapses, whichever comes first. Paces Claude's polling naturally so the spinner doesn't spam and the user sees steady progress text.

Returns { status: 'running'|'done'|'error', progress, message, done, result? }. Use after transcribe_start or batch_create_clips(async_mode: true).

STEP 2 — Submit your clip suggestions after analyzing the transcript.

Before calling this: read the transcript via get_ui_state(include_transcript: true) and identify the best viral moments.

What it does: Stores your suggestions, assigns clip numbers (#1, #2, etc.), and pushes them to the Web UI for the user to review.

After this: the user reviews in the UI. Then export with batch_create_clips(export_selected: true) or create_clip(clip_number: N).

STEP 3 — Export a single clip as a finished vertical short (1080x1920, 9:16).

EASIEST: just pass clip_number (e.g. 3) — everything else auto-loads from session state. Output: H.264 MP4 with burned-in captions, normalized audio (-14 LUFS).

For batch export, use batch_create_clips instead. Caption styles: branded (professional), hormozi (bold/yellow), karaoke (progressive highlight), subtle (minimal). Crop modes: speaker (speaker-aware), face (face tracking), center (fixed center crop). Set keep_caption_overlay=true to retain a ProRes alpha overlay for DaVinci Resolve (export_to_davinci_resolve).

STEP 3 — Export multiple clips at once as finished vertical shorts.

EASIEST: pass export_selected=true to export all selected clips in one go. Alternative: pass clip_numbers=[1, 3, 5] for specific ones. Everything (video, timestamps, settings) auto-loads from session state.

Pass exactly one of clips, clip_numbers, or export_selected. If several are given, an explicit clips array wins, then export_selected, then clip_numbers.

Each clip gets: 9:16 vertical crop, burned-in captions, normalized audio, H.264 MP4.

Read or manage the podcli knowledge base. These are .md files that provide context about the podcast (hosts, style, audience, etc). Always read the knowledge base before suggesting or creating clips.

Register and manage reusable assets (logos, outros, intros, music, images). Reference them by name in create_clip/manage_reel instead of full paths. One logo/outro/intro/music can be the default, applied automatically when none is passed.

View previously created clips to avoid duplicates. Check before creating new clips.

Read the current podcli session state and get guidance on what to do next. Returns: video path, transcript status, clip suggestions, settings, and workflow next steps.

IMPORTANT: Call this FIRST when starting a new conversation to understand the current state. Clips are numbered #1, #2, etc. Use these numbers with create_clip(clip_number), batch_create_clips(clip_numbers), modify_clip, and toggle_clip.

Set include_transcript=true to analyze transcript content. Returns a compact phrase-grouped markdown view (~10x smaller than raw segments) with speaker attribution, silence gaps, and optional energy peaks — the primary surface for reasoning about clip boundaries.

Adjust a suggested clip before exporting. Change timing, title, or caption style. Use action='delete' to remove a clip entirely. Reference clips by clip_number (from get_ui_state).

Select or deselect a suggested clip by clip_number. Selected clips are exported with export_selected.

Update rendering settings (caption style, crop strategy, logo, outro) in the Web UI.

List all rendered clip files in the output directory with file sizes and dates.

Save, load, list, or delete rendering presets. Presets store caption_style, crop_strategy, logo_path, and outro_path for quick reuse.

Show, export, import, or reset the thumbnail template (colors, fonts, frame, box, layout) podcli uses to generate thumbnails. 'show' returns the effective config; 'export' writes it to a file path; 'import' replaces it from a file path; 'reset' reverts to the generic default.

Analyze audio energy levels for a video or specific segments. Useful for finding high-energy moments. Defaults to the current UI video and suggestions if not specified.

Create and iterate on a highlights reel. Detection runs once with action 'new'; after that, edit individual moments fast (longer/shorter/earlier/later/shift/drop/toggle) and rebuild without re-detecting. Pass video_paths (a list) to pool many videos and rank the best moments across all of them. Actions: 'new' (video_path or video_paths, profile, format, top_n, min_dur, max_dur), 'list', 'show' (session_id), 'edit' (session_id, index, op, seconds), 'build' (session_id), 'delete' (session_id).

Set the working video file without transcribing. Use this when you'll import a transcript separately. After this, either transcribe_podcast or import a transcript via import_transcript / parse_transcript.

Import an external transcript (e.g. from a transcription service) into the UI. Skips Whisper entirely. The transcript must include word-level timestamps.

Parse a raw speaker-labeled plain text transcript into word-level timestamps. Input format: 'Speaker (MM:SS)\ntext...\n\nSpeaker2 (MM:SS)\ntext...'. Uses the Python backend to generate accurate word timings.

List, enable, or disable podcli integrations (editor exporters, platform uploads, productivity tools, AI helpers).

Actions: • list — return all installed integrations with their enabled state (default) • enable — turn an integration on (its tools become callable) • disable — turn an integration off (calls return a disabled error)

State persists at the active config home (integrations.json, gitignored).

Export podcli shorts as a DaVinci Resolve FCPXML project.

Each short becomes a compound clip with V1 source + V2 ProRes 4444 alpha caption overlay — fully editable in free or Studio Resolve 20.x.

Requires the davinci_resolve integration to be enabled (manage_integrations action=enable name=davinci_resolve).

Manage portable config profiles and legacy path migration.

Actions: • status — active config home, cache dir, migration state (default) • migrate — move legacy project/.podcli/cache into data/cache (idempotent) • export — zip the active config home (knowledge, presets, assets, settings) • import — restore a bundle; backs up existing config before overwrite • use — activate a config home path (writes .podcli-home marker)

List, set, or unset global podcli settings stored in .env.

Keys: • HF_TOKEN — HuggingFace token for speaker detection • PODCLI_CLAUDE_PATH — manual path to Claude Code CLI when auto-discovery fails • PODCLI_CODEX_PATH — manual path to Codex CLI when auto-discovery fails

Actions: • list — show all settings, configured values, and AI CLI detection (default) • set — set a key (path must exist for PODCLI_*_PATH keys) • unset — remove a key (falls back to auto-discovery)

Show whether Claude Code / Codex CLIs are available for AI-powered clip suggestion and content generation.

Returns configured manual paths (PODCLI_CLAUDE_PATH / PODCLI_CODEX_PATH) and auto-discovered binaries. Use manage_env(action=set, key=PODCLI_CLAUDE_PATH, value=...) to override when detection fails.