Metadata-Version: 2.4
Name: mgz-pkmn
Version: 1.4.0
Summary: 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-URL: Homepage, https://mgz-pkmn.com
Project-URL: Repository, https://github.com/mgzwarrior/mgz-pkmn
Project-URL: Issues, https://github.com/mgzwarrior/mgz-pkmn/issues
Project-URL: Documentation, https://github.com/mgzwarrior/mgz-pkmn/tree/main/docs
Author-email: Matt Grant <mattgrant33@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: card-collection,cli,pokemon,pricing,spreadsheet,tcg,trading-cards
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: openpyxl>=3.1
Requires-Dist: pillow>=10.0
Requires-Dist: reportlab>=4.5.1
Requires-Dist: requests>=2.34.2
Provides-Extra: api
Requires-Dist: alembic>=1.13; extra == 'api'
Requires-Dist: authlib>=1.3; extra == 'api'
Requires-Dist: fastapi>=0.136.1; extra == 'api'
Requires-Dist: httpx>=0.28.1; extra == 'api'
Requires-Dist: itsdangerous>=2.2; extra == 'api'
Requires-Dist: python-multipart>=0.0.20; extra == 'api'
Requires-Dist: sqlalchemy>=2.0; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.47.0; extra == 'api'
Description-Content-Type: text/markdown

<h1>
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mgzwarrior/mgz-pkmn/main/assets/logo-dark.svg">
    <img src="https://raw.githubusercontent.com/mgzwarrior/mgz-pkmn/main/assets/logo.svg" alt="mgz-pkmn" height="64">
  </picture>
</h1>

[![CI](https://github.com/mgzwarrior/mgz-pkmn/actions/workflows/ci.yml/badge.svg)](https://github.com/mgzwarrior/mgz-pkmn/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/mgzwarrior/mgz-pkmn/branch/main/graph/badge.svg)](https://codecov.io/gh/mgzwarrior/mgz-pkmn)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)

🌐 **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/](api/) and a React + Vite
  frontend in [web/](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.

[pokemontcg.io]: https://pokemontcg.io
[TCGdex]: https://tcgdex.dev
[PriceCharting]: https://www.pricecharting.com

## Install

Requires Python 3.11+ and [`uv`](https://docs.astral.sh/uv/).

```bash
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

```bash
./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/`](input/) directory ships four small example lists
that exercise every input syntax and lookup mode the tool supports —
including [`example-url-overrides.txt`](input/example-url-overrides.txt),
which walks through the "paste a PriceCharting URL once and forget it"
workflow. The tracked files in [`output/`](output/) were generated by
exactly the command above. See the [CLI reference](docs/cli.md#worked-examples)
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:

```bash
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](docs/cache.md#environment-variables) for the full behavior of the cache-related vars.

## Web UI

```bash
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>.

The hosted demo can sign users in with GitHub, Google, Discord, or an
email magic link when auth is enabled. See
[Deployment](docs/deployment.md#environment-variables) for the provider
credentials, callback URLs, and production session settings. Anonymous
hosted-demo lookups run against the warmed cache only; sign in to let a
cache miss query the live upstream API.

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

## License

Released under the [MIT License](LICENSE).

## Documentation

Reference docs live under [`docs/`](docs/) and are mirrored to the
[GitHub Wiki](https://github.com/mgzwarrior/mgz-pkmn/wiki) on every
push to `main`.

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

## AI-assisted development

mgz-pkmn uses a lightweight multi-agent workflow inspired by
[@bobbylough](https://github.com/bobbylough)'s
[ai-pit-crew](https://github.com/bobbylough/ai-pit-crew) project. GitHub
itself is the active-work board — issues, milestones, branches, PRs, and
`agent:*` labels carry every piece of state. [docs/roadmap.md](docs/roadmap.md)
is the planning navigator.

Agents should start with [AGENTS.md](AGENTS.md), follow the shared loop in
[.agent-workflow.md](.agent-workflow.md), and expect cross-agent review before
human approval.

## Community

Questions, ideas, or want to share what you built? Open a thread in [GitHub Discussions](https://github.com/mgzwarrior/mgz-pkmn/discussions).

## Support the project

mgz-pkmn is free and MIT-licensed. If it's saved you time at a card show and you'd like to chip in, the [Buy Me a Coffee page](https://www.buymeacoffee.com/mgz.pkmn) takes one-off "buy me a pizza 🍕" tips and runs three recurring membership tiers:

|   | Tier | What you get |
|---|---|---|
| <img src="https://raw.githubusercontent.com/mgzwarrior/mgz-pkmn/main/assets/bmc/tier-common.png" alt="Common tier badge" width="160" /> | **Common**<br>$3 / month | Supporters listing, ~24h early peek at release notes, personal thank-you |
| <img src="https://raw.githubusercontent.com/mgzwarrior/mgz-pkmn/main/assets/bmc/tier-uncommon.png" alt="Uncommon tier badge" width="160" /> | **Uncommon**<br>$8 / month | Everything in Common, plus members-only Discussions, one monthly roadmap vote, name in the README Supporters section |
| <img src="https://raw.githubusercontent.com/mgzwarrior/mgz-pkmn/main/assets/bmc/tier-holo-rare.png" alt="Holo Rare tier badge" width="160" /> | **Holo Rare**<br>$20 / month | Everything in Uncommon, plus your logo on the marketing-site supporters strip, priority bug triage (best-effort), early-access booth in the virtual card-show pilot |

<a href="https://www.buymeacoffee.com/mgz.pkmn"><img src="https://img.buymeacoffee.com/button-api/?text=Buy%20me%20some%20pizza&amp;emoji=%F0%9F%8D%95&amp;slug=mgz.pkmn&amp;button_colour=6bac55&amp;font_colour=000000&amp;font_family=Lato&amp;outline_colour=000000&amp;coffee_colour=FFDD00" alt="Buy me a pizza on Buy Me a Coffee" /></a>
