tmdb-cli-enhanced 2.0.0

A beautiful command-line interface for The Movie Database (TMDB) API with interactive features

TMDB CLI Tool

A beautiful command-line interface for The Movie Database (TMDB) API that allows you to search for movies, browse trending content, check upcoming releases, and get detailed movie information.

🆕 What's New in v2.0

• 🎮 Interactive Movie Browser: Browse movies with a beautiful, interactive interface
• ⭐ Personal Watchlist: Save, manage, and export your favorite movies
• 🎯 Smart Recommendations: Get movie suggestions based on movies you like or by genre
• 💾 Data Persistence: Your watchlist is saved locally between sessions
• 📤 Export Functionality: Export your watchlist to shareable text files
• 🎨 Enhanced UI: Rich, colorful interface with intuitive navigation
• ⚡ Improved Performance: Faster API calls and better error handling

Features

• 🔍 Search Movies: Search for movies by title with pagination support
• 📈 Trending Movies: Browse trending movies for today or this week
• 🎬 Upcoming Releases: View upcoming movie releases
• 📋 Movie Details: Get comprehensive information about specific movies
• � Interactive Browser: Browse movies with an interactive interface
• ⭐ Personal Watchlist: Save and manage your favorite movies
• 🎯 Smart Recommendations: Get movie suggestions based on preferences
• 💾 Data Export: Export your watchlist to text files
• �🎨 Rich Terminal Output: Beautiful, colored tables and formatted text
• ⚡ Error Handling: Graceful handling of network issues, invalid input, and API errors
• 🔧 Environment Configuration: Secure API key management with .env files

Installation

Option 1: Install from PyPI (Recommended)

# Install globally
pip install tmdb-cli-enhanced

# Or install in a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install tmdb-cli-enhanced

Option 2: Install from Source

1. Clone this repository:

   git clone https://github.com/hanzadj/tmdb-cli.git
   cd tmdb-cli
   

2. Create a virtual environment and install dependencies:

   # Create virtual environment
   python3 -m venv venv
   
   # Activate virtual environment
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   
   # Install in development mode
   pip install -e .
   

Setup Your API Key

3. Set up your TMDB API key:
   • Get a free API key from The Movie Database
   • Copy the .env.example file to .env:

     cp .env.example .env
     

   • Edit the .env file and replace your_tmdb_api_key_here with your actual API key:

     API_KEY=your_actual_tmdb_api_key_here
     

Usage

After installation, you can use the CLI tool in several ways:

Method 1: Using the command (recommended for PyPI installs)

tmdb-cli search "inception"
tmdb-cli trending --type week
tmdb-cli upcoming
tmdb-cli details 550

# Or using the shorter alias
tmdb search "inception"
tmdb trending --type week
tmdb upcoming
tmdb details 550

Method 2: Using the wrapper script (for source installs)

./tmdb search "inception"
./tmdb trending --type week
./tmdb upcoming
./tmdb details 550

Method 3: Direct Python module execution

# If installed via pip
python -m tmdb_cli.main search "inception"

# Or if using source install with activated virtual environment
source venv/bin/activate
python -m tmdb_cli.main search "inception"

Basic Commands

Search for Movies

tmdb search "inception"
tmdb search "spider man" --page 2

Get Trending Movies

# Trending today (default)
tmdb trending

# Trending this week
tmdb trending --type week

View Upcoming Releases

tmdb upcoming

Get Movie Details

tmdb details 550  # Fight Club
tmdb details 27205  # Inception

Interactive Movie Browser

# Browse popular movies interactively
tmdb browse

# Browse top rated movies
tmdb browse --category top_rated

# Browse currently playing movies
tmdb browse --category now_playing

Manage Your Watchlist

# View your personal watchlist
tmdb watchlist

# Add movies to watchlist using the browse command
tmdb browse  # then use 'w' command to manage watchlist

Get Movie Recommendations

# Get recommendations based on a specific movie
tmdb recommend --movie-id 27205  # Based on Inception

# Get recommendations by genre
tmdb recommend --genre "science fiction"
tmdb recommend --genre "action"

# Get personalized recommendations (requires watchlist)
tmdb recommend

Command Reference

Command	Description	Options
search <query>	Search for movies by title	--page, -p: Page number (default: 1)
trending	Get trending movies	--type: day or week (default: day)
upcoming	Show upcoming movie releases	None
details <movie_id>	Get detailed movie information	Movie ID (required)
browse	Interactive movie browser	--category: popular, top_rated, now_playing
watchlist	Manage personal watchlist	Interactive management options
recommend	Get movie recommendations	--movie-id: Based on movie, --genre: By genre

Help and Version

# Show help
tmdb --help

# Show version
tmdb --version

# Help for specific commands
tmdb search --help

Interactive Features

Movie Browser

The interactive browser (./tmdb browse) provides an immersive way to discover movies:

• Navigation: Use n (next) and p (previous) to browse pages
• Movie Details: Use d <number> to view detailed information
• Watchlist Management: Use w to add/remove movies from your personal watchlist
• Visual Indicators: Movies in your watchlist are marked with ⭐
• Clean Exit: Use q to quit the browser

Watchlist Management

Your personal movie watchlist is stored locally and provides:

• Persistent Storage: Movies are saved between sessions
• Export Functionality: Export your list to text files
• Quick Actions: Add, remove, view details, and clear entire list
• Statistics: Track when movies were added to your list

Smart Recommendations

Get intelligent movie suggestions based on:

• Similar Movies: Find movies like ones you've enjoyed
• Genre Preferences: Discover popular movies in specific genres
• Personal Taste: Recommendations based on your watchlist history

Output Examples

Interactive Browser

🎬 Popular Movies (Page 1/4)

╭─────────────────────────────────────────────────────────────────╮
│ 1. The Shawshank Redemption ⭐                                  │
│ 📅 1994-09-23 | ⭐ 8.7/10                                       │
│ Two imprisoned mates bond over a number of years, finding...    │
╰─────────────────────────────────────────────────────────────────╯

Commands: next | prev | watchlist | details <num> | quit

Watchlist Display

📋 Your Watchlist (3 movies)

┌───┬──────────────────────┬──────────────┬─────────┬─────────────┐
│ # │ Title                │ Release Date │ Rating  │ Added       │
├───┼──────────────────────┼──────────────┼─────────┼─────────────┤
│ 1 │ Inception            │ 2010-07-15   │ 8.4/10  │ 2025-08-07  │
│ 2 │ The Dark Knight      │ 2008-07-16   │ 8.5/10  │ 2025-08-07  │
│ 3 │ Interstellar         │ 2014-11-05   │ 8.5/10  │ 2025-08-07  │
└───┴──────────────────────┴──────────────┴─────────┴─────────────┘

Search Results

                              Search Results for 'inception'                               
┌──────────────────────────────┬──────────────┬────────┬──────────────────────────────────────────────────┐
│ Title                        │ Release Date │ Rating │ Overview                                         │
├──────────────────────────────┼──────────────┼────────┼──────────────────────────────────────────────────┤
│ Inception                    │ 2010-07-16   │ 8.4/10 │ Cobb, a skilled thief who commits corporate     │
│                              │              │        │ espionage by infiltrating the subconscious...   │
│ Inception: The Cobol Job     │ 2010-12-07   │ 7.9/10 │ This Inception prequel unfolds courtesy of a... │
└──────────────────────────────┴──────────────┴────────┴──────────────────────────────────────────────────┘

Movie Details

╔══════════════════════════════════════════════════════════════════════╗
║                               Inception                               ║
║                 Your mind is the scene of the crime                   ║
╚══════════════════════════════════════════════════════════════════════╝

Release Date      July 16, 2010
Rating           8.4/10 (35,275 votes)
Runtime          148 minutes
Budget           $160,000,000
Revenue          $825,532,764
Genres           Action, Science Fiction, Adventure
Production       Warner Bros. Pictures, Legendary Entertainment, Syncopy

╭─ Overview ──────────────────────────────────────────────────────────────╮
│ Cobb, a skilled thief who commits corporate espionage by infiltrating   │
│ the subconscious of his targets, is offered a chance to regain his old  │
│ life as payment for a task considered to be impossible: "inception",    │
│ the implantation of another person's idea into a target's subconscious. │
╰─────────────────────────────────────────────────────────────────────────╯

Project Structure

tmdb-cli/
├── tmdb_cli/            # Main Python package
│   ├── __init__.py      # Package initialization
│   └── main.py          # CLI application code
├── .env.example         # Environment variables template
├── .gitignore          # Git ignore patterns
├── LICENSE             # MIT License
├── MANIFEST.in         # Package manifest for distribution
├── pyproject.toml      # Modern Python packaging configuration
├── tmdb                # Wrapper script for development
├── demo.sh             # Demo script showcasing all features
├── publish.sh          # PyPI publishing helper script
├── requirements.txt    # Python dependencies (for development)
└── README.md          # This file

# User Data (created automatically)
.env                    # Your personal API key (not in repo)
venv/                   # Virtual environment (not in repo)
~/.tmdb_watchlist.json  # Personal watchlist storage
tmdb_watchlist_*.txt    # Exported watchlist files

Dependencies

• requests: HTTP library for API calls
• python-dotenv: Environment variable management
• rich: Beautiful terminal formatting
• click: Command-line interface framework

Error Handling

The tool gracefully handles various error scenarios:

• Invalid API Key: Clear error message for authentication issues
• Network Problems: Timeout and connection error handling
• Invalid Input: Validation for movie IDs and search queries
• No Results: Friendly messages when searches return empty results
• Rate Limiting: Proper HTTP status code handling

API Information

This tool uses The Movie Database (TMDB) API. You need a free API key to use this application.

Getting an API Key

1. Create an account at TMDB
2. Go to your API settings
3. Request an API key
4. Copy the API key to your .env file

💡 Tips & Tricks

Power User Tips

• Quick Movie Lookup: Use tmdb details <movie_id> for instant movie information
• Genre Discovery: Try tmdb recommend --genre "thriller" to discover new genres
• Watchlist Shortcuts: In the browser, use w to quickly manage your watchlist
• Export for Sharing: Use the watchlist export feature to share movie lists with friends

Workflow Suggestions

1. Discovery: Start with tmdb browse to discover popular movies
2. Curation: Add interesting movies to your watchlist using the browser
3. Exploration: Use tmdb recommend to find similar movies
4. Organization: Export your watchlist periodically for backup

Troubleshooting

• Virtual Environment: Make sure to activate your virtual environment with source venv/bin/activate
• Missing Dependencies: If commands fail, ensure you've installed requirements with pip install -r requirements.txt
• API Key Issues: Make sure you've copied .env.example to .env and added your actual API key
• Network Issues: The tool handles timeouts gracefully - just retry
• Invalid Movie IDs: Use search to find the correct movie ID first
• Empty Watchlist: Start browsing movies to build your personal collection
• API Limits: The free TMDB API has generous limits for personal use

Contributing

Feel free to submit issues, feature requests, or pull requests to improve this tool.

Acknowledgments

This project was inspired by the TMDB CLI project from roadmap.sh - a fantastic resource for learning and building practical development projects. The roadmap.sh community provides excellent project ideas and learning paths for developers of all levels.

License

This project is open source and available under the MIT License.