pokecli: un CLI pequeño y tipado para PokeAPI

Descripción del proyecto

pokecli es una herramienta de línea de comandos de código abierto que construí para consultar datos de Pokémon, bayas, objetos, movimientos, habilidades, naturalezas, tipos, cadenas de evolución y especies desde PokeAPI. Es deliberadamente pequeña y es una de las implementaciones de referencia que suelo mostrar cuando hablo de cómo diseño una herramienta de línea de comandos. El proyecto también me sirve como ejemplo de implementación para herramientas nativas para IA: pokecli incluye un SKILL.md que un agente como Claude Code o Copilot puede cargar para aprender el conjunto de comandos sin tener que releer --help en cada tarea.

pokecli

Tecnologías utilizadas

Arquitectura

pokecli está organizado en cinco capas, cada una a cargo de exactamente una cosa. Los comandos conocen Typer. El cliente del API conoce httpx. El caché conoce TinyDB. Los modelos conocen Pydantic. La capa de presentación conoce Rich. Ninguna capa invade el carril de otra.

flowchart LR
  subgraph CLI["Composición con Typer"]
    MAIN["main.py\napp raíz"]
        DOMAIN_CMDS["commands/\npokemon.py\nberry.py\nimage.py\n..."]
        CACHE_CMD["commands/cache.py"]
    end
  subgraph CORE["Núcleo compartido"]
        UTILS["commands/_utils.py"]
        CLIENT["api/client.py"]
        STORE["cache/store.py"]
    end
  subgraph DATA["Dominio y presentación"]
        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

Cada comando get sigue el mismo flujo corto. Lo imponen los límites entre módulos, no una convención informal.

flowchart LR
  A([Solicitud]) --> B{¿Hit en caché?}
  B -- sí --> C[Datos en caché]
  B -- no --> D[Consulta al API]
  D --> E[Actualiza caché]
  C --> F[Transforma la respuesta]
    E --> F
  F --> G{Modo de salida}
  G -- tabla --> H[Vista de tabla]
  G -- json --> I[Vista JSON]

Estructura del paquete de un vistazo

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

Funcionalidades clave

Estas funcionalidades muestran el conjunto de capacidades de pokecli y el tipo de experiencia de línea de comandos que busco construir: pequeña, tipada, scriptable y clara de entender a primera vista.

Consultas de recursos con salida tipada

Cada recurso (pokemon, berry, item, move, ability, nature, type) tiene comandos get y list paralelos con flags compartidos (--no-cache, --format). Los comandos especializados de Pokémon agregan moves, species y evolution.

Comandos de pokecli

Descarga de sprites

pokecli image download pokemon <name_or_id> -o <path> guarda los sprites localmente. El flag --variant selecciona entre seis vistas conocidas.

Caché local con control por recurso

La primera llamada va a la red; a partir de ahí, cada consulta se sirve desde ~/.pokecli/cache.json. Puedes inspeccionar o limpiar la caché con granularidad por recurso.

Comandos de pokecli

Desafíos técnicos

Esta sección muestra las decisiones y compensaciones de ingeniería detrás de pokecli. Cada tarjeta destaca un problema que tuve que resolver, la decisión de diseño que tomé y lo que esa decisión dice sobre cómo construyo herramientas de línea de comandos.

1. Hacer que cada recurso sea una aplicación autocontenida de Typer

2. Usar el contexto de Typer como punto de apoyo para inyectar dependencias

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

3. Centralizar en una sola utilidad el flujo de caché primero y red después

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. Usar Pydantic como contrato frente a la API externa

Un script de shell que envuelva pokecli puede actuar sobre esto.

5. Elegir TinyDB en lugar de SQLite o Redis

6. Dejar Rich aislado en la capa de presentación

7. Incluir el SKILL.md dentro del paquete

Qué demuestra este proyecto

En conjunto, estas decisiones muestran por qué pokecli funciona bien como proyecto de referencia: el empaquetado es claro, los límites entre capas están bien definidos, los fallos están pensados y la herramienta sigue siendo lo bastante pequeña como para entenderse rápido sin perder rigor.

Resultados

pokecli es la pieza de código más pequeña que puedo mostrar y que aun así refleja todos los hábitos que aplico en un servicio de producción con interfaz de línea de comandos.

Tan importante como leer el código es entender la experiencia que produce. pokecli toma una API pública y la convierte en una herramienta serena y automatizable, y el SKILL.md que acompaña al proyecto hace que ese CLI sea nativo para IA al enseñarle a un agente cómo usarlo incluso si el modelo nunca fue entrenado específicamente con pokecli. Así, el proyecto mantiene una huella pequeña para quien llega por primera vez y, al mismo tiempo, sigue siendo legible para un agente desde la siguiente sesión.

{
  "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.

Foto de Jay ➡️ en Unsplash ➡️

Pokémon y los nombres de los personajes de Pokémon son marcas registradas de Nintendo.