Pokedex CLI

A command-line Pokédex application built in Go that lets you explore Pokémon locations, catch Pokémon, and build your own Pokédex using the PokéAPI.

Features

• Map Navigation: Browse through location areas in the Pokémon world

  • map - View the next 20 location areas
  • mapb - View the previous 20 location areas

• Explore Locations: Discover which Pokémon appear in each area

  • explore <location_area> - List all Pokémon in a specific location

• Catch Pokémon: Attempt to catch Pokémon and add them to your Pokédex

  • catch <pokemon_name> - Try to catch a Pokémon (50% success rate)

• Inspect Pokémon: View detailed stats and types of caught Pokémon

  • inspect <pokemon_name> - Display a Pokémon's height, weight, types, and stats

• View Your Collection: See all Pokémon you've caught

  • pokedex - List all caught Pokémon

• Smart Caching: Responses are cached for 5 minutes to reduce API calls

Installation

Requirements

• Go 1.25.4 or higher

Build

go build -o pokedex .

Run

./pokedex

Usage

Start the interactive REPL:

$ ./pokedex
Pokedex > 

Example Session

Pokedex > map
caspian-sea
cerulean-cave
...

Pokedex > explore cerulean-cave
Found Pokemon:
- articuno
- mew
- mewtwo

Pokedex > catch mewtwo
Throwing a Pokeball at mewtwo...
Caught mewtwo!

Pokedex > inspect mewtwo
Inspecting mewtwo...
Name: mewtwo
Height: 20
Weight: 1220
Types:
- psychic
Stats:
- hp: 106
- attack: 110
- defense: 90
...

Pokedex > pokedex
Caught Pokemon:
- mewtwo

Pokedex > help
Welcome to the Pokedex!
Usage:
exit: Exits the Pokedex application
help: Displays a help message
map: Displays the names of 20 location areas in the Pokemon world
mapb: Displays the names of previous 20 location areas in the Pokemon world
explore <location_area>: Lists the Pokemon in a location area
catch <pokemon_name>: Catches a Pokemon
inspect <pokemon_name>: Inspect a caught Pokemon's details
pokedex: View all caught Pokemon

Pokedex > exit
Closing the Pokedex... Goodbye!

Architecture

Main Components

• main.go - CLI REPL, command handlers, and JSON unmarshaling logic
• internal/pokecache/main.go - Thread-safe caching system with automatic expiration
  • Entries expire after 5 minutes
  • Prevents redundant API calls
  • Uses goroutines and mutexes for concurrent safety

Data Structures

• APIResponse: Parses paginated location data from PokéAPI
• Pokemon: Holds Pokémon details (name, height, weight, stats, types)
• LocationArea: Represents Pokémon encounters in a specific area
• Cache: Thread-safe in-memory cache with TTL-based cleanup

Technical Details

JSON Tag Mapping

The application uses struct tags to map JSON keys to Go fields:

type Pokemon struct {
    Name   string `json:"name"`      // Maps JSON "name" key
    Height int    `json:"height"`    // Maps JSON "height" key
    Weight int    `json:"weight"`    // Maps JSON "weight" key
}

Caching Strategy

• 5-minute TTL for all cached responses
• Background goroutine cleans expired entries
• Mutex-protected concurrent access

API Integration

• Uses PokéAPI v2 (free, no authentication required)
• Endpoints:
  • Location areas: https://pokeapi.co/api/v2/location-area/
  • Pokémon details: https://pokeapi.co/api/v2/pokemon/{name}

Project Structure

.
├── main.go                          # CLI entry point and commands
├── go.mod                           # Module definition
├── README.md                        # This file
└── internal/
    └── pokecache/
        ├── main.go                  # Cache implementation
        └── cache_test.go            # Cache tests

Future Enhancements

• Persist caught Pokémon to disk
• Display Pokémon images in the terminal
• Add battle mechanics between caught Pokémon
• Search Pokémon by type or stat range
• Add leaderboards for catching streaks

License

MIT

Contributing

Feel free to fork and submit pull requests!

Resources

• PokéAPI Documentation
• Go Documentation