PokéCLI - Your Terminal Pokédex

A command-line Pokémon encyclopedia that brings pocket monsters to your terminal. Search, browse, and discover Pokémon with user friendly interfaces powered by PokéAPI.

Features

CLI Mode (Fast & Scriptable)

• Quick lookup: pokec get pikachu
• Detailed stats: pokec get charizard --detailed
• Simple output: pokec get bulbasaur --simple

TUI Mode (Pretty & Interactive)

• Interactive menus: Navigate with numbered options
• Rich visuals: Color-coded types, stat bars, and clean layouts
• Multiple search methods: By name, Pokédex number, or type
• Random Pokémon: Discover new Pokémon with the random feature
• Progress indicators: Visual feedback during API calls

Technical Features

• Robust error handling: Network issues, invalid names, API errors
• Intelligent name cleaning: Handles special characters and formatting
• Modular design: Clean separation of API, display, and interface logic
• Extensible architecture: Easy to add new features and commands

---

Quick Start

Installation

1. Clone the repository:

git clone https://github.com/amilliiee/pokemon_cli.git
cd pokemon_cli

2. Create virtual environment (recommended):

python3 -m venv venv
source venv/bin/activate # For windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Install in development mode:

pip install -e .

Basic Usage

CLI Mode:

# Get basic Pokémon info
pokec get pikachu

# Get detailed stats with bars
pokec get charizard --detailed

# Simple one-line output
pokec get bulbasaur --simple

# Show help
pokec --help
pokec get --help

TUI Mode:

pokec tui

Then navigate the menu with number keys.

---

Project Structure

pokemon_cli/
├── src/
│   ├── __init__.py          # Package exports
│   ├── cli.py               # Click CLI commands
│   ├── tui.py               # Rich TUI interface
│   ├── api.py               # PokeAPI interactions
│   └── display.py           # Output formatting
├── pokec                    # Main entry point (CLI)
├── requirements.txt         # Dependencies
├── setup.py                 # Package configuration
└── README.md                # This file

---

Development

Setting Up Development Environment:

1. Install development dependencies (if not already done):

pip install -r requirements.txt

2. Run tests:

# Run the CLI tests
python3 -m src.cli get pikachu
python3 -m src.cli get charizard --detailed

# Run the TUI
python3 -m src.tui

Adding New Features:

1. New CLI command:

• Add function in cli.py with @cli.command() decorator
• Import necessary modules from api.py

2. New TUI feature:

• Add method to PokeTUI class in tui.py
• Add menu option in main_menu()

3. API enhancements:

• Add functions to api.py
• Update __init__.py exports

---

TUI Interface Guide:

Main Menu Options:

1. Search by name - Enter any Pokémon name
2. Search by number - Enter Pokédex ID (1-1010)
3. Browse by type - Select from 18 Pokémon types
4. Random Pokémon - Discover a random Pokémon
5. Favorites - Save and view favorite Pokémon (coming soon)
6. Compare - Compare two pokemon side-by-side (coming soon)
7. Exit - Quit the application

Display Features:

• Color-coded types: Each type has its canonical Pokémon color
• Stat visualization: Bar graphs show relative stat values (may change this in the future for readability)
• Clean layout: Panels and tables for organization

API Integration

PokéCLI uses the official PokéAPI with:

• Rate limiting: Built-in timeout and error handling
• Data caching: Optional local caching
• Comprehensive data: Access to all attributes

---

TODO/Roadmap

Planned Features:

• Favorites system: Save and manage favorite Pokémon
• Comparison tool: Side-by-side stat comparison
• Type effectiveness calculator: Damage multiplier calculator
• Evolution chains: Display evolution families
• Generation filters: Filter Pokémon by generation
• Local cache: Reduce API calls with local caching

Potential Enhancements:

• ASCII art sprites
• Team builder functionality
• Move lists
• Ability information
• Shiny form display

---

License

This project is licensed under the MIT License - see LICENSE.md for details

Acknowledgements

• PokéAPI for the comprehensive Pokémon data
• Click for the CLI framework
• Rich for styled terminal output
• The Pokémon Company for creating IP that has been with me since childhood