Pokedex CLI

A command-line Pokedex built with TypeScript and Node.js. It uses the PokeAPI to explore location areas, inspect Pokemon, and catch them from an interactive REPL.

Features

• Interactive REPL
• Paginated location browsing
• Location exploration
• Pokemon catching
• In-memory Pokedex for the current session
• Basic test coverage with Vitest

Tech Stack

• TypeScript
• Node.js 22
• Vitest
• PokeAPI

Requirements

• Node.js 22.15.0
• npm

If you use nvm:

nvm use

Install

npm install

Run

Build:

npm run build

Start:

npm start

Build and run in one step:

npm run dev

Test

npm test

Available Commands

• help - list commands
• map - show the next page of location areas
• mapb - show the previous page of location areas
• explore <location-area> - list Pokemon in a location area
• catch <pokemon> - attempt to catch a Pokemon
• inspect <pokemon> - inspect a caught Pokemon
• pokedex - list caught Pokemon
• exit - quit the REPL

Example

> help
> map
> explore canalave-city-area
> catch pikachu
> inspect pikachu
> pokedex

Project Structure

src/
  main.ts
  repl.ts
  state.ts
  command.ts
  command_*.ts
  pokeapi.ts
  pokecache.ts
  tests/

Current Scope

The current version is a single-session CLI. Caught Pokemon are kept in memory and are lost when the process exits.

Next Direction: Party Mode

The best way to extend this project is to turn it into a terminal-based party and battle game instead of just a catch-and-inspect demo.

That path should focus on two things:

• party management
• multiplayer-friendly terminal play

Why This Direction

It keeps the project true to the REPL format while adding real game systems:

• a team-building loop instead of a flat collection list
• meaningful command design
• battle state and turn resolution
• richer testing around game rules
• a better reason for people to actually use the CLI

Recommended Roadmap

1. Party Management

Add a real party system on top of the current Pokedex:

• party add <pokemon>
• party remove <pokemon>
• party list
• party lead <pokemon>

Rules:

• max 6 Pokemon in party
• only caught Pokemon can be added
• one active lead Pokemon at a time

2. Battle-Ready Pokemon Data

Expand caught Pokemon into trainer-owned Pokemon instances:

• nickname support
• level
• HP
• move set
• status effects

This is the point where Pokemon from the API should stop being the full runtime model. You will want a separate domain model for owned Pokemon.

3. Turn-Based Battle Commands

Add battle flows that work naturally in a terminal:

• battle wild
• battle attack <move>
• battle switch <pokemon>
• battle run

Keep the output text-first and easy to follow. The REPL format is an advantage here, not a limitation.

4. Friend Play In The Terminal

If you want this to feel more substantial, make battles playable with friends over a shared terminal session or a lightweight host/join model.

Good options:

• shared local session through one REPL
• host/join over TCP for two terminal clients
• spectator-friendly battle logs

The clean version of this is: one player hosts a battle session, another joins, both manage their own parties, and the game resolves turns server-side.

What To Build First

Build party management before multiplayer.

That gives you a clean sequence:

1. refactor the current Pokedex into trainer-owned Pokemon
2. add party commands and party validation
3. build single-player wild battles
4. add two-player terminal battles

If you skip straight to multiplayer, the data model will stay weak and the command layer will get messy fast.

Good Engineering Targets For This Path

• move game logic out of command handlers
• create a Trainer model and a party service
• separate API data from runtime battle data
• add tests for catch rules, party rules, and battle turns
• persist trainer and party state to disk once the model stabilizes

License

ISC