pokemon-wikis-cli

A CLI-first, fully async Python SDK for compliant, server-friendly access to the Pokémon wikis — through one English interface.

It does not maintain a database and does not parse Pokémon-specific data. It is a thin, polite wrapper over MediaWiki with three primitives: search, filter, and get wikitext, plus a keywords reference.

Wikis

Select one per call with -w / --wiki (required):

-w	wiki	notes
zh-hans	神奇宝贝百科 (52poke)	simplified output
zh-hant	神奇寶貝百科 (52poke)	traditional output
en	Bulbapedia
de	PokéWiki	no CirrusSearch — filter intersects categories client-side
es	WikiDex

The Japanese, French, and Italian sister wikis are deliberately excluded: they gate automated requests behind bot challenges (403 / Cloudflare), and this tool does not evade them.

Install / run

Run it without installing, straight from GitHub, with uvx:

uvx --from git+https://github.com/AirswitchAsa/pokemon-wikis-cli pokewiki \
  filter type:electric gen:1 -w en

From a local checkout instead:

uvx --from . pokewiki filter type:electric gen:1 -w en   # one-off
uv sync && uv run pokewiki ...                            # development

CLI

# fuzzy text search
pokewiki search "Pikachu" -w en
pokewiki search "皮卡丘" -w zh-hans

# structured filter — English keys, AND-intersected, work on every wiki
pokewiki filter type:electric gen:1 -w en
pokewiki filter type:electric gen:1 -w zh-hant
pokewiki filter type:electric gen:1 -w de        # client-side intersection

# per-wiki axes
pokewiki filter region:hisui type:dragon -w en   # region: en + zh
pokewiki filter ability:static gen:1 -w zh-hant  # ability: 52poke only

# text within a constraint (CirrusSearch wikis only)
pokewiki search "fast" -c type:electric -w en

# look up a page by title and print its raw wikitext (follows redirects, so a
# bare name works; title is per-wiki, not translated)
pokewiki page "Pikachu" -w en
pokewiki page "Thunderbolt" -w en
pokewiki page "皮卡丘" -w zh-hans

# the constraint vocabulary (wiki-independent; -w shows native names)
pokewiki keywords
pokewiki keywords type
pokewiki keywords type -w de

Constraint keys are repeatable and comma-joinable; on filter they may also be space-separated. All keys AND-intersect:

pokewiki filter type:electric gen:1 -w en
pokewiki search "" -c type:electric,gen:1 -w en   # equivalent (but just use filter)

SDK

from pokewiki import PokeWikiClient

async with PokeWikiClient(
    wiki="en",
    user_agent="pokewiki/0.1 (contact: you@example.com)",
) as client:
    results = await client.filter(["type:electric", "gen:1"])
    hits = await client.search("Pikachu")
    page = await client.get_wikitext("Pikachu (Pokémon)")
    print(page.wikitext)

The SDK constructor requires a user_agent — only the CLI carries a default — so embedders always identify themselves.

The unified vocabulary

filter/-c keys are English; each resolves to the wiki's native category name (type:electric → Electric-type Pokémon / 电属性宝可梦 / Elektro-Pokémon / Pokémon de tipo eléctrico). There are two kinds of axis:

• Universal — identical keys on every wiki: type (18), generation (9), egg group (14). These 41 keys resolve consistently whichever -w you pick.
• Per-wiki — present only where the wiki categorises that way:
  • region (region:kanto → Pokémon in the Kanto Pokédex / 关都地区宝可梦) on Bulbapedia (9) and 52poke (10). PokéWiki and WikiDex have no regional-Pokédex categories — only debut generation, which gen: already covers — so region is absent there. (en has no region:kalos: Bulbapedia splits Kalos into three sub-dexes.)
  • ability (ability:static → 拥有静电特性的宝可梦) on 52poke only (312 abilities). The other three wikis don't categorise Pokémon by ability.

A per-wiki key is simply absent on the wikis that lack it (resolving it there is a clean error). Run pokewiki keywords for the union of all keys, or pokewiki keywords -w <wiki> for one wiki's keys with native names; use plain search for anything outside the vocabulary.

Compliance

• requires a clear, custom User-Agent and refuses generic ones;
• uses only the MediaWiki API — never action=parse;
• serializes requests (no concurrency), spaced ≥ min_interval (default 0.6s);
• caches successful responses on disk for 24h;
• one polite Retry-After-honoring retry on 429, then a clear error;
• no batch-crawling features; excludes wikis that block automated access.

Development

uv sync
uv run pytest             # unit tests (network mocked)
uv run pytest -m live     # smoke tests against the real wikis
uv run ruff check .
uv run ty check
dog lint docs             # documentation (DOG) is the spec — see docs/

Non-goals

No structured Pokémon parser, no local database, no bulk sync, no image downloading, no MCP server, no JSON schema commitment yet.

Agent skill

skills/pokewiki/SKILL.md wraps the CLI for coding agents. It teaches when to reach for the wikis — treat them as ground truth, not training-data memory — and how to chain search → page → filter to answer a question from live data. Install it with npx skills:

npx skills add https://github.com/AirswitchAsa/pokemon-wikis-cli/tree/main/skills/pokewiki

The skill resolves the pokewiki command itself (an installed binary, otherwise uvx straight from this repo) via scripts/ensure-pokewiki.sh.

Contributing

Contributions are welcome. The docs/*.dog.md files are the behavioural spec — keep them in sync with the code and run dog lint docs before opening a PR. See CONTRIBUTING.md for the full workflow.

License

MIT — see LICENSE.