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
• TUI (Textual-based Interface) - Modern terminal-based user interface with keyboard navigation

Requirements

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

Installation

From Source

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

Using pip

pip install youtube-cli

Usage

Basic Search

youtube-cli "python tutorial"

Download a Video

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

View Help

youtube-cli --help

Check for yt-dlp Updates

youtube-cli --check-update

Update yt-dlp

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:

{
  "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:

pip install yt-dlp

API Development

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

# 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:

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:

yt-dlp --remote-components ejs:github

Permission Issues

Ensure proper permissions for download directories:

mkdir -p ~/Downloads/youtube
chmod 755 ~/Downloads/youtube

API Issues

If the API server fails to start:

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

YouTube TUI

A modern, terminal-based user interface for browsing and downloading YouTube videos built with Textual.

Features

• Modern terminal interface with keyboard navigation
• Search and browse YouTube videos
• Download videos with progress indication
• Playlist support
• Pagination through results
• Category selection for downloads
• Network share integration
• Download archive tracking

Installation

pip install youtube-cli[tui]

Usage

youtube-tui

Keyboard Shortcuts

Key	Action
Enter	Search / Download
n	Next Page
p	Previous Page
q	Quit / Back
Escape	Cancel / Back
Ctrl+F	Search from anywhere
Ctrl+R	Refresh

Documentation

See TUI.md for complete TUI documentation.