# yt-cli

> Download and transcribe YouTube videos with speaker diarization and auto-chapters. Use when the user wants to transcribe a video URL, search YouTube for videos, list videos from a channel, search existing transcripts, list transcribed videos, read transcript content, or check if a video has already been transcribed.

- Author: digibugcat
- Repository: DigiBugCat/Cassandra-Plugins
- Version: 20260106163115
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/DigiBugCat/Cassandra-Plugins
- Web: https://mule.run/skillshub/@@DigiBugCat/Cassandra-Plugins~yt-cli:20260106163115

---

---
name: yt-cli
description: Download and transcribe YouTube videos with speaker diarization and auto-chapters. Use when the user wants to transcribe a video URL, search YouTube for videos, list videos from a channel, search existing transcripts, list transcribed videos, read transcript content, or check if a video has already been transcribed.
---

# yt-cli

CLI tool for downloading and transcribing videos using yt-dlp and AssemblyAI.

## Commands

### Search YouTube for videos
```bash
yt-cli yt-search '<query>' [-n limit]
```
Search YouTube for videos matching the query. Returns video titles, channels, durations, view counts, and URLs.

Options:
- `-n, --limit <LIMIT>` - Maximum results to return (default: 10)

Example output:
```
Found 10 result(s) for 'rust tutorial':

1. Rust Programming Tutorial - Fireship (12:34)
   1.2M views
   https://youtube.com/watch?v=...

2. Learn Rust in 10 Minutes - TechChannel (10:15)
   500K views
   https://youtube.com/watch?v=...
```

Use the returned URLs with `yt-cli transcribe <url>` to transcribe a video.

### Transcribe a video

**IMPORTANT**: Transcription can take several minutes depending on video length. Always run in the background:

```bash
# Start transcription in background
yt-cli transcribe '<video-url>'
```
Use Bash tool with `run_in_background: true` to start the transcription.

Then poll for completion using BashOutput every 15-30 seconds until complete. The command will output progress updates as it downloads and transcribes.

Downloads audio, transcribes with speaker labels and auto-chapters, saves to `~/.yt-transcribe/transcripts/{platform}/{channel}/{video_id}/`.

Output includes: `transcript.md`, `transcript.json`, `metadata.json`, and the audio file.

### Check if video is already transcribed
```bash
yt-cli get '<video-url>'
```
Returns the transcript path if it exists. Use this before transcribing to avoid duplicates.

### Search transcripts
```bash
yt-cli search 'query' [-n limit]
```
Full-text search across all transcripts, descriptions, and chapter summaries.

### List channel videos
```bash
yt-cli channel '<channel-url>' [-n limit]
```
List latest videos from a YouTube channel. Takes a channel URL (e.g., `https://youtube.com/@CHANNEL`) or channel ID.

Options:
- `-n, --limit <LIMIT>` - Maximum videos to show (default: 20)

### List transcripts
```bash
yt-cli list [-p platform] [-c channel] [-H handle]
```
List all transcribed videos with optional filtering by platform, channel display name (`-c`), or channel handle (`-H`, e.g., `@EconomicsUnmasked`).

### Read a transcript
```bash
yt-cli read <path> [--json]
```
Output transcript content. Use `--json` for structured data with timestamps.

### Show statistics
```bash
yt-cli stats
```
Display total transcripts, channels, duration, and word counts.

### Reindex database
```bash
yt-cli reindex
```
Rebuild the search index from existing transcript files.

### Initialize (first-time setup)
```bash
yt-cli init [-k api-key] [-f]
```
Set up yt-cli with your AssemblyAI API key. Required before first transcription.

Options:
- `-k, --api-key <KEY>` - AssemblyAI API key (prompts interactively if not provided)
- `-f, --force` - Overwrite existing configuration

## Transcript Format

The markdown transcript includes:
1. **Chapters section** - Auto-generated summaries with timestamps
2. **Transcript section** - Speaker-labeled paragraphs with timestamps

Example:
```markdown
## Chapters

### [00:00] Introduction to the topic
Summary of what's discussed in this section...

### [05:23] Main discussion points
Summary of the main content...

---

## Transcript

**Speaker A** [00:00]: Welcome to the show...

**Speaker B** [01:23]: Thanks for having me...
```

## Storage Structure

```
~/.yt-transcribe/
├── transcripts/
│   └── youtube/
│       └── channel-name/
│           └── video-id/
│               ├── transcript.md
│               ├── transcript.json
│               ├── metadata.json
│               └── audio.m4a
└── transcripts.db
```

## Troubleshooting

### API key not configured
```
Error: AssemblyAI API key not found
```
Run `yt-cli init -k <your-api-key>` to set up your API key.

### yt-dlp errors
```
Error: Unable to download video
```
- Update yt-dlp: `brew upgrade yt-dlp` or `pip install -U yt-dlp`
- Video may be unavailable, private, or region-locked
- Check if the URL is valid and accessible in a browser

### Transcription timeout
Long videos (2+ hours) may take significant time. Use background execution and poll for completion.

### Database out of sync
If transcripts exist on disk but don't appear in search/list results:
```bash
yt-cli reindex
```
This rebuilds the search index from existing transcript files.