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.

• 🎮 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

• 🔍 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

1. Clone this repository:

   git clone https://github.com/yourusername/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 dependencies
   pip install -r requirements.txt

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
     

You can run the CLI tool in two ways:

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

# Activate virtual environment first
source venv/bin/activate

# Then run commands
python tmdb_cli.py search "inception"
python tmdb_cli.py trending --type week
python tmdb_cli.py upcoming
python tmdb_cli.py details 550

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

# Trending today (default)
./tmdb trending

# Trending this week
./tmdb trending --type week

./tmdb upcoming

./tmdb details 550  # Fight Club
./tmdb details 27205  # Inception

# Browse popular movies interactively
./tmdb browse

# Browse top rated movies
./tmdb browse --category top_rated

# Browse currently playing movies
./tmdb browse --category now_playing

# View your personal watchlist
./tmdb watchlist

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

# 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

# Show help
./tmdb --help

# Show version
./tmdb --version

# Help for specific commands
./tmdb search --help

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

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

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

🎬 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

📋 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 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... │
└──────────────────────────────┴──────────────┴────────┴──────────────────────────────────────────────────┘

╔══════════════════════════════════════════════════════════════════════╗
║                               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. │
╰─────────────────────────────────────────────────────────────────────────╯

tmdb-cli/
├── .env.example         # Environment variables template
├── .gitignore          # Git ignore patterns
├── tmdb_cli.py         # Main CLI application (enhanced with new features)
├── tmdb                # Wrapper script for easy execution
├── setup.py            # Setup and installation helper
├── demo.sh             # Demo script showcasing all features
├── requirements.txt    # Python dependencies
└── 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

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

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

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

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

• 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

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

• 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

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

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.

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