pokecli: A Small, Typed CLI for PokeAPI

Project Description

pokecli is an open source command-line tool I built to query Pokemon, Berries, Items, Moves, Abilities, Natures, Types, evolution chains, and species data from PokeAPI. It is deliberately small, and it is one of the reference implementations I point to when I talk about how I design a command line tool. The project also doubles as my implementation example for AI-native tooling: pokecli ships with a SKILL.md that an agent like Claude Code or Copilot can load to learn the command set without re-reading --help on every task.

pokecli

Technologies Used

Architecture

pokecli is organised as five layers that each know about exactly one thing. Commands know Typer. The API client knows httpx. The cache knows TinyDB. The models know Pydantic. The display layer knows Rich. Nothing crosses its lane.

flowchart LR
    subgraph CLI["Typer composition"]
        MAIN["main.py\nroot app"]
        DOMAIN_CMDS["commands/\npokemon.py\nberry.py\nimage.py\n..."]
        CACHE_CMD["commands/cache.py"]
    end

    subgraph CORE["Shared core"]
        UTILS["commands/_utils.py"]
        CLIENT["api/client.py"]
        STORE["cache/store.py"]
    end

    subgraph DATA["Domain and presentation"]
        MODELS["models/*.py"]
        RENDER["display/*.py"]
    end

    MAIN --> DOMAIN_CMDS
    MAIN --> CACHE_CMD

    DOMAIN_CMDS --> UTILS
    DOMAIN_CMDS --> MODELS
    DOMAIN_CMDS --> RENDER

    UTILS --> CLIENT
    UTILS --> STORE
    CACHE_CMD --> STORE

Every get command follows the same short pipeline. The module boundaries enforce it, not convention.

flowchart LR
    A([Request]) --> B{Cache hit?}
    B -- yes --> C[Cached data]
    B -- no --> D[API fetch]
    D --> E[Update cache]
    C --> F[Transform response]
    E --> F
    F --> G{Output mode}
    G -- table --> H[Table view]
    G -- json --> I[JSON view]

Package layout at a glance

src/pokecli/
├── main.py             # root Typer app, sub-apps registered here
├── config.py           # POKEAPI_BASE_URL, DEFAULT_LIMIT, CACHE_DB_PATH
├── api/client.py       # PokeAPIClient (httpx + context manager)
├── cache/store.py      # CacheStore (TinyDB, table per resource)
├── commands/
│   ├── _utils.py       # fetch_resource, fetch_list
│   ├── pokemon.py      # get / moves / species / evolution / list
│   ├── berry.py  item.py  move.py  ability.py  nature.py  type.py
│   ├── image.py        # download (sprite variants)
│   ├── cache.py        # stats / clear
│   └── install.py      # install --skills
├── display/            # Rich renderers, one file per resource
├── models/             # Pydantic v2 models, one file per resource
└── skills/pokecli/
    ├── SKILL.md
    └── references/api-fields.md

Key Features

These features show the feature set of pokecli and the kind of command-line experience I aim to build: small, typed, scriptable, and clear at a glance.

Resource queries with typed output

Every resource (pokemon, berry, item, move, ability, nature, type) has parallel get and list commands with shared flags (--no-cache, --format). Specialised Pokemon commands add moves, species, and evolution.

pokecli commands

Sprite downloads

pokecli image download pokemon <name_or_id> -o <path> saves sprites locally. The --variant flag selects between six well-known views.

Local cache with per-resource control

First call goes to the network, every call after that is served from ~/.pokecli/cache.json. Users can inspect or clear the cache at resource granularity.

pokecli commands

Technical challenges

This section shows the engineering tradeoffs behind pokecli. Each card highlights a problem I had to solve, the design choice I made, and what that choice says about how I build command-line tools.

1. Keeping each resource a self-contained Typer app

2. Using the Typer context as a dependency-injection seam

@app.callback()
def root(ctx: typer.Context) -> None:
    ctx.ensure_object(dict)
    ctx.obj["client"] = ctx.with_resource(PokeAPIClient())

3. Centralising the cache-then-HTTP flow in one utility

def fetch_resource(client, resource, name_or_id, no_cache, err_console):
    with CacheStore() as cache:
        key = name_or_id.lower()
        data = None if no_cache else cache.get(resource, key)
        if data is None:
            try:
                data = client.get_resource(resource, name_or_id)
            except httpx.HTTPStatusError as e:
                if e.response.status_code == 404:
                    err_console.print(f"[red]Not found: '{name_or_id}'[/red]")
                else:
                    err_console.print(f"[red]API error: {e.response.status_code}[/red]")
                raise typer.Exit(1)
            except (httpx.ConnectError, httpx.TimeoutException):
                err_console.print("[red]Network error: could not reach PokeAPI[/red]")
                raise typer.Exit(1)
            cache.set(resource, key, data)
    return data

4. Treating Pydantic as the contract with the upstream API

A shell script wrapping pokecli can act on this.

5. Choosing TinyDB over SQLite or Redis

6. Isolating Rich in the display layer

7. Shipping the SKILL.md inside the package

What this project demonstrates

Taken together, these choices show why pokecli works well as a reference project: the packaging is clean, the boundaries are explicit, the failure modes are intentional, and the tool remains small enough to understand without losing rigor.

Results

pokecli is the smallest piece of code I can point to that still shows every habit I apply to a production service with a command line interface.

The product read is just as important as the code read. pokecli turns a public API into a calm, scriptable tool, and the shipped SKILL.md makes that CLI AI-native by teaching an agent how to use it even when the model was never trained on pokecli itself. That keeps the footprint small for a human contributor and still legible to an agent in the next session.

{
  "skill": "pokecli",
  "args": "Pikachu stats"
}

Launching skill: pokecli

$pokecli pokemon get pikachu

╭────────────────────────────────────────────────────────────╮
│ #25  Pikachu   Height: 0.4m   Weight: 6.0kg   Base XP: 112 │
╰────────────────────────────────────────────────────────────╯
 ELECTRIC 

Abilities: static  ·  lightning-rod (hidden)

 Stat            Base  Bar
 hp                35  ███░░░░░░░░░░░░░░░░░
 attack            55  ████░░░░░░░░░░░░░░░░
 defense           40  ███░░░░░░░░░░░░░░░░░
 special-attack    50  ████░░░░░░░░░░░░░░░░
 special-defense   50  ████░░░░░░░░░░░░░░░░
 speed             90  ███████░░░░░░░░░░░░░

$pokecli move get thunderbolt

╭──────────────────╮
│ #85  Thunderbolt │
╰──────────────────╯
  Type             Electric
  Category         Special
  Power            90
  Accuracy         100%
  PP               15
  Effect Chance    10%

Effect: Has a 10% chance to paralyze the target.

$pokecli move get flamethrower

╭───────────────────╮
│ #53  Flamethrower │
╰───────────────────╯
  Type             Fire
  Category         Special
  Power            90
  Accuracy         100%
  PP               15
  Effect Chance    10%

Effect: Has a 10% chance to burn the target.

Photo by Jay ➡️ on Unsplash ➡️

Pokémon and Pokémon character names are trademarks of Nintendo.