Pokedex CLI

A command-line Pokédex built in Go that interacts with the PokéAPI. Explore locations, catch Pokémon, and build your personal Pokédex—all from your terminal!

Note: This is a guided boot.dev project.

---

✨ Features

• 🗺️ Explore locations — Browse paginated location areas and discover Pokémon
• 🔍 Inspect Pokémon — View detailed stats (HP, Attack, Defense, etc.), types, height, and weight
• 🎯 Catch Pokémon — Probabilistic catching system based on base experience (harder Pokémon are tougher to catch!)
• 📖 Personal Pokédex — Keep track of all Pokémon you've caught during your session
• ⚡ Smart caching — API responses are cached with configurable TTL to reduce network calls and improve performance
• 🔄 Interactive REPL — Clean command-line interface with autocomplete-friendly commands

---

🚀 Quick Start

Requirements

• Go 1.25.2+ (check with go version)
• Network access to pokeapi.co

Installation

# Clone the repository
git clone https://github.com/captainpiratez/pokedexcli.git
cd pokedexcli

# Build the binary
go build -o pokedexcli

# Run it
./pokedexcli

You'll see the prompt:

Pokedex > 

Type help to get started!

---

📖 Usage

Available Commands

Command	Description	Example
help	Display help message with all commands	help
map	Get the next page of location areas	map
mapb	Get the previous page of location areas	mapb
explore <location>	List Pokémon found in a specific location	explore canalave-city-area
catch <pokemon>	Attempt to catch a Pokémon	catch pikachu
inspect <pokemon>	View details of a caught Pokémon	inspect pikachu
pokedex	List all Pokémon you've caught	pokedex
exit	Exit the Pokedex CLI	exit

Example Session

Pokedex > map
canalave-city-area
eterna-city-area
pastoria-city-area
...

Pokedex > explore canalave-city-area
Found pokemon:
 - tentacool
 - tentacruel
 - staryu
 - magikarp
 - gyarados
 - wingull
 - pelipper
 - shellos
 - gastrodon
 - finneon
 - lumineon

Pokedex > catch tentacool
Throwing a Pokeball at tentacool...
tentacool was caught!
You may now inspect it with the inspect command.

Pokedex > inspect tentacool
Name: tentacool
Height: 9
Weight: 455
Stats:
  -hp: 40
  -attack: 40
  -defense: 35
  -special-attack: 50
  -special-defense: 100
  -speed: 70
Types:
  - water
  - poison

Pokedex > pokedex
Your Pokedex:
  - tentacool

Pokedex > exit

---

🏗️ Project Structure

.
├── main.go                  # Entry point, initializes client and config
├── repl.go                  # REPL loop and command routing
├── command_*.go             # Individual command implementations
├── internal/
│   ├── pokeapi/            # PokéAPI client with caching
│   │   ├── client.go       # HTTP client wrapper
│   │   ├── location_*.go   # Location-related API calls
│   │   ├── pokemon_get.go  # Pokemon fetching
│   │   └── types_*.go      # API response types
│   └── pokecache/          # In-memory cache with TTL
│       ├── pokecache.go    # Cache implementation
│       └── pokecache_test.go
└── README.md

---

⚙️ How It Works

Caching

The CLI uses an in-memory cache (internal/pokecache) with a 5-minute TTL by default. This dramatically reduces API calls when exploring the same locations or catching the same Pokémon multiple times.

• Cache entries expire after 5 minutes
• Background reaper goroutine cleans up stale entries
• Thread-safe with sync.Mutex

Catch Mechanics

When you attempt to catch a Pokémon:

1. A random number is generated based on the Pokémon's base_experience
2. Higher base experience = harder to catch
3. If the roll succeeds, the Pokémon is added to your in-memory Pokédex
4. Caught Pokémon persist only for the current session

Example probabilities (approximate):

• Low base exp (e.g., Caterpie): ~80-85% catch rate
• Medium base exp (e.g., Pikachu): ~40-60% catch rate
• High base exp (e.g., Dragonite): ~5-15% catch rate

---

🧪 Testing

Run all tests:

go test ./...

Run tests with coverage:

go test -cover ./...

Run tests for a specific package:

go test ./internal/pokecache -v

---

🛠️ Development

Adding a New Command

1. Create a new file command_yourcommand.go
2. Implement the function signature: func commandYourCommand(cfg *config, args ...string) error
3. Register it in getCommands() in repl.go
4. Add help text and validation

Modifying API Client

The PokéAPI client is in internal/pokeapi. To add a new endpoint:

1. Define response types in types_*.go
2. Add a method to client.go (or create a new file like pokemon_get.go)
3. Use the built-in cache via c.cache.Get() and c.cache.Add()

---

✅ TODOs

• Update the CLI to support the "up" arrow to cycle through previous commands
• Simulate battles between pokemon
• Add more unit tests
• Refactor your code to organize it better and make it more testable
• Keep pokemon in a "party" and allow them to level up
• Allow for pokemon that are caught to evolve after a set amount of time
• Persist a user's Pokedex to disk so they can save progress between sessions
• Use the PokeAPI to make exploration more interesting. For example, rather than typing the names of areas, maybe you are given choices of areas and just type "left" or "right"
• Random encounters with wild pokemon
• Adding support for different types of balls (Pokeballs, Great Balls, Ultra Balls, etc), which have different chances of catching pokemon

🐛 Known Issues

• Pokédex resets when you exit (no persistence to disk)
• No support for filtering or searching caught Pokémon
• Pagination for map/mapb doesn't wrap around

Contributions welcome! Feel free to open an issue or PR.

---

Acknowledgments

• PokéAPI for the awesome free API
• The Go community for excellent tooling and libraries

---

Happy catching! 🎣✨