youtube-cli/README.md

# YouTube CLI

A command-line interface for browsing and downloading YouTube videos with advanced features including API support and network sharing capabilities.

## Features

- **Search YouTube videos** with keyword queries
- **Display up to 15 videos at a time** with title, author, duration, and type (short/video/playlist)
- **Download videos** using yt-dlp with progress indication
- **Configure download locations** with default locations and network share support
- **Handle short videos** (videos with /shorts/ in URL) with special "(short)" prefix
- **REST API support** with OpenAPI specification
- **MCP (Model Context Protocol) compliance** for enhanced integration
- **Playlist support** for downloading entire YouTube playlists
- **Network share copying** - automatically copy downloads to network shares
- **Download archive tracking** - track already downloaded videos
- **Update checking** - automatically check for yt-dlp updates

## Requirements

- Python 3.7+
- yt-dlp
- rich
- requests
- Flask (for API functionality)

## Installation

### From Source

```bash
git clone https://github.com/yourusername/youtube-cli.git
cd youtube-cli
pip install -e .
```

### Using pip

```bash
pip install youtube-cli
```

## Usage

### Basic Search

```bash
youtube-cli "python tutorial"
```

### Download a Video

```bash
youtube-cli --download "https://www.youtube.com/watch?v=xyz123"
```

### View Help

```bash
youtube-cli --help
```

### Check for yt-dlp Updates

```bash
youtube-cli --check-update
```

### Update yt-dlp

```bash
youtube-cli --update
```

## Configuration

The application will create a default configuration file at `~/.config/youtube_cli/config.json` if one doesn't exist. You can customize:

```json
{
  "download_dir": "~/Downloads/youtube",
  "default_locations": [
    "~/Downloads/youtube",
    "~/Movies/youtube",
    "/tmp/youtube"
  ],
  "max_videos_per_page": 15,
  "yt_dlp_args": {
    "format": "bestvideo[height=1080]+bestaudio/bestvideo[height<=1080]+bestaudio",
    "write_thumbnail": true,
    "extractor_args": "youtube:player-client=default,-tv_simply"
  },
  "network_share_path": "/Volumes/MediaServer/Youtube/",
  "default_network_subfolder": "General"
}
```

## How to Use

1. Run a search query to find videos
2. Videos will be displayed with:
   - Title (short videos marked with "(short)")
   - Author
   - Duration
   - Type indicator (Video, Short, Playlist)
3. Choose an option:
   - `n` for next page of results
   - `q` to quit
   - Enter a number to select and download a video
   - Enter multiple numbers or ranges (e.g., `1,2,3` or `1-3`) to download multiple videos
   - `s` to search for a new term

## API Endpoints

The YouTube CLI also provides a REST API with the following endpoints:

### Search Videos
```
GET /search?q=QUERY&page=PAGE
```

### Download Video
```
POST /download
Content-Type: application/json

{
  "url": "https://www.youtube.com/watch?v=xyz123"
}
```

### Health Check
```
GET /health
```

### Version Information
```
GET /version
```

### Capabilities
```
GET /capabilities
```

### OpenAPI Specification
```
GET /openapi.json
```

## Features

- **Search**: Search YouTube videos using keyword queries
- **Pagination**: View 15 videos at a time with option for more
- **Download**: Download videos directly with progress indication
- **Short Detection**: Automatically detects and marks short videos
- **Configuration**: Customizable download locations
- **Cross-platform**: Works on macOS and Linux
- **Playlist Support**: Download entire YouTube playlists
- **Network Share Integration**: Copy downloads to network shares automatically
- **Download Archive**: Track already downloaded videos
- **Update Checking**: Automatically check for yt-dlp updates
- **MCP Compliance**: Compatible with Model Context Protocol for enhanced integration

## Dependencies

This tool depends on `yt-dlp` which must be installed separately:

```bash
pip install yt-dlp
```

## API Development

The application includes a Flask-based REST API for programmatic access:

```bash
# Run the API server
python app.py
```

The API will be available at `http://localhost:4096`

## Docker Support

The application can be run in Docker:

```bash
docker-compose up
```

This will start the API server on port 4096.

## Contributing

1. Fork it
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Create a Pull Request

## License

MIT License

## MCP Integration

This project supports Model Context Protocol (MCP) integration, allowing it to work with AI agents and tools that require MCP-compliant interfaces. The API endpoints provide capabilities that can be used by MCP servers to interact with YouTube content.

## Network Share Support

The application supports copying downloaded videos to network shares. Configure the `network_share_path` in your configuration file to enable this feature.

## Download Archive

The application maintains an archive of downloaded videos to prevent duplicate downloads. This archive is stored in `~/.config/youtube_cli/downloaded_videos.json`.

## Advanced Usage

### Download Multiple Videos
```
youtube-cli "python tutorial"
# When prompted, enter: 1,2,3
```

### Download Video Range
```
youtube-cli "python tutorial"
# When prompted, enter: 1-5
```

### Custom Download Locations
```
youtube-cli --download "https://www.youtube.com/watch?v=xyz123"
# When prompted, enter a network folder name to copy to network share
```

### Update Management
```
youtube-cli --check-update
youtube-cli --update
```

## Troubleshooting

### JavaScript Challenges
If you encounter JavaScript challenge solving errors:
```bash
yt-dlp --remote-components ejs:github
```

### Permission Issues
Ensure proper permissions for download directories:
```bash
mkdir -p ~/Downloads/youtube
chmod 755 ~/Downloads/youtube
```

### API Issues
If the API server fails to start:
```bash
pip install -r requirements-api.txt
```

## Technical Details

### Core Components
- **youtube_cli/main.py**: Main application logic with search, download, and archive functionality
- **youtube_cli/__main__.py**: Entry point for command-line interface
- **app.py**: REST API implementation with Flask
- **Dockerfile**: Containerization support
- **docker-compose.yml**: Docker orchestration

### Architecture
The application follows a modular architecture with:
- Command-line interface for direct usage
- REST API for programmatic access
- Configuration management
- Download tracking and archive functionality
- Network share integration
- Update checking capabilities

### Data Flow
1. User input via CLI or API
2. Search or download request processing
3. yt-dlp integration for video operations
4. Configuration and archive management
5. Network share copying (if configured)
6. Result delivery to user

## Version History

### v0.1.0
- Initial release with core search and download functionality
- Basic configuration support
- API endpoint implementation
- Network share support
- Update checking capabilities

## Future Enhancements

- Enhanced playlist management
- Improved error handling and recovery
- More sophisticated download filtering
- Advanced configuration options
- Better integration with AI tools and agents
- Enhanced logging and monitoring

## Related Projects

The TUI and web interfaces were extracted into their own projects:

- **[youtube-tui](https://git.jarianc.com/jarianc/youtube-tui)** — modern terminal-based interface built with Textual
- **[youtube-web](https://git.jarianc.com/jarianc/youtube-web)** — React-based web interface with download queue management