mgz-pkmn 1.1.0

CLI and web app to look up Pokemon cards across open data sources, fetch images and prices, and emit an .xlsx, PDF binder, set-completion checklist, and JSON report for card-show prep.

🌐 Project site: https://mgz-pkmn.com · 🚀 Live demo: https://mgz-pkmn.onrender.com

A toolkit for prepping Pokemon card binders for a card show: take a list of cards, look each one up across three open data sources, download images, and write an .xlsx with embedded thumbnails, current market price, and 80 / 85 / 90 / 95 % negotiation comps. Optional PDF binder, condensed binder, set-completion checklist, and JSON report alongside.

Two ways to drive it:

• CLI — ./pkmn lookup cards.txt produces xlsx + (optional) PDF + JSON; ./pkmn set-cards emits printable set ID cutouts.
• Web UI — FastAPI backend in api/ and a React + Vite frontend in web/ put the same pipeline behind a live in-browser interface with streaming results and one-click export.

The tool tries sources in this order:

1. pokemontcg.io — primary. Best coverage of English / international English releases, with TCGPlayer (USD) + Cardmarket (EUR) prices.
2. TCGdex — multilingual fallback (en, ja, ko, zh-tw, zh-cn, de, fr, es, it, pt, …). Has Cardmarket prices for many cards.
3. PriceCharting — opt-in via an explicit URL on the line. Ideal for region-exclusive products neither aggregator indexes (Chinese Gem Pack, etc.). Returns USD loose / new / graded prices.

Install

Requires Python 3.11+ and uv.

brew install uv                                   # macOS
curl -LsSf https://astral.sh/uv/install.sh | sh   # any platform

make install-cli          # CLI only — fastest
# or
make install              # CLI + API + web + pre-commit hook

Run make help for the full target list.

Quickstart

./pkmn lookup input/ --no-images \
  -o output/cards.xlsx \
  --pdf output/binder.pdf \
  --condensed-pdf output/binder-condensed.pdf \
  --checklist output/checklist.pdf \
  --report-json output/summary.json

./pkmn set-cards -o output/set-cards.pdf   # printable set ID cutouts (no input needed)

The bundled input/ directory ships four small example lists that exercise every input syntax and lookup mode the tool supports — including example-url-overrides.txt, which walks through the "paste a PriceCharting URL once and forget it" workflow. The tracked files in output/ were generated by exactly the command above. See the CLI reference for the full breakdown.

API key (optional but recommended)

The pokemontcg.io API works without a key (~1000 requests/day, 30/min) but a free key raises that to 20k/day. Grab one at https://dev.pokemontcg.io, then set it as an env var:

export POKEMONTCG_IO_API_KEY=your-key-here          # current shell
echo 'export POKEMONTCG_IO_API_KEY=your-key-here' >> ~/.zshrc   # persistent

Prefer the env var over --api-key — flags get saved to shell history.

Environment variables

Every variable the tool reads, in one place:

Variable	Purpose
POKEMONTCG_IO_API_KEY	Raises pokemontcg.io rate limits from 1k/day to 20k/day. Free key at https://dev.pokemontcg.io.
MGZ_PKMN_NO_CACHE	Disables the disk cache for the current process. The CLI's --no-cache flag sets this internally.
MGZ_PKMN_CACHE_WARN_BYTES	Threshold for the cache-size soft-warn at startup (default 50 MB, 0 disables).
XDG_CACHE_HOME	Overrides the cache root ($XDG_CACHE_HOME/mgz-pkmn). Standard XDG semantics.

See docs/cache.md → Environment variables for the full behavior of the cache-related vars.

Web UI

make install         # one-time setup
make dev-api         # Terminal 1 — API on :8000
make dev-web         # Terminal 2 — Vite dev server on :5173

Open http://localhost:5173. The Vite dev server proxies /api/* to the FastAPI server. Swagger UI lives at http://localhost:8000/docs.

Prefer not to install anything? The same UI is hosted at https://mgz-pkmn.onrender.com.

For deeper docs (endpoint reference, troubleshooting, architecture), see api/README.md and web/README.md.

License

Released under the MIT License.

Documentation

Reference docs live under docs/ and are mirrored to the GitHub Wiki on every push to main.

Topic	Page
Every flag and pkmn invocation pattern	CLI reference
Single-card + bulk top:N / All … syntax	Input format
pokemontcg.io / TCGdex / PriceCharting layering	Sources & coverage
Non-English / regional handling	Languages
Spreadsheet + JSON report shape	Outputs
Standard 3×3 + condensed 6×4 layouts	PDF binder
Front-of-binder set checklist	Checklist PDF
Disk cache + URL overrides	Cache
Render / Docker / production recipe	Deployment
Marketing site (Astro + Tailwind, Cloudflare Pages)	site/README.md
Project layout, dev workflow, CI, release	Contributing

Community

Questions, ideas, or want to share what you built? Open a thread in GitHub Discussions.