proxdex

The librarian for making proxy cards. proxdex keeps every card's assets in a predictable place keyed by its set + collector number (ex3-90, neo-136), tracks which pipeline stage each card has reached, corrects thin card frames, and records what you've actually printed — so a growing collection stays easy to search, and you never reprint a card you already have.

It handles Pokémon (pokemontcg.io + scrydex) and Magic: The Gathering (Scryfall), and one library can hold both — each card records its own game, so searching, backs and border specs follow the card.

It uses cardbleed (border extension) and Upscayl (upscaling), and imposes the print sheet itself — so it owns the whole path to paper.

Think of it as author a master, then reproduce it: the four card stages produce a device-independent, trim-size master (what the card should look like); the sheet step reproduces it faithfully on a specific printer + medium (colour-correct + add bleed outside the trim).

Pipeline

Each card's stored file is the actual trim-size card — no bleed. Four stages, one file per stage:

Every step is one you run or skip — nothing is automatic. Steps 2–4 each carry their own state: pending → done (you ran it) or skipped (you decided it isn't needed). Skipping is a real answer: the next step just reads the previous stage instead, and sheet prints the furthest stage that exists.

proxdex skip upscale ex3-90     # bypass a step: drops its output, marks it skipped
proxdex unskip upscale ex3-90   # back to pending (the output is not restored)
proxdex reset upscale ex3-90    # delete the output and any skip mark

Changing an upstream stage removes every output after it — those went stale — so you can always re-border a card and rebuild from there without stale pixels surviving.

Special printings

Almost every card is one picture on one side of one 63×88mm card. Providers name two dozen layouts — saga, adventure, prototype, leveler, battle — but nearly all of them differ in rules text, not in ink, so proxdex records only what changes what goes on paper: one side, two sides, or half of a meld pair, plus whether the card is oversized. proxdex ls shows it in a Kind column, proxdex show spells it out, and the UI badges it on the tile and the card page.

Two sides

A Magic transform, modal, reversible or art-series card is one card with two sides, and fetch downloads both. Each side runs the pipeline on its own — a back face is a different picture and needs its own border fit — so every step, skip and reset takes --face 1 (front) or --face 2 (back). Without it they act on both.

Which side goes on the paper is your call, because a transform card has two real fronts and no back of its own:

proxdex flip isd-51             # swap which side prints on the front of a sheet
proxdex flip isd-51 --face 2    # or name it outright

sheet --faces duplex then prints that card's other side on the reverse instead of the shared card back. A one-sided card still takes the configured back. On a fronts-only sheet only the flipped-to side is imposed, and sheet says so.

Meld

A meld pair is three physical cards: both halves and the melded card, each with its own id and its own picture. So proxdex files them as three cards and records the relationship rather than pretending one card has three sides — fetch --related follows the provider's own links and gets the lot:

proxdex fetch --related inr-14
#   ↳ melds into Brisela, Voice of Nightmares (inr-14b)
#   ↳ melds with Gisela, the Broken Blade (inr-24)

The same flag picks up the tokens a card makes. proxdex show <id> lists what a card is printed alongside and which of those you already have; the card page in the UI shows the same list with an Add button per row.

Oversized

Planar, scheme and Vanguard cards are printed at 89×127mm, not 63×88. proxdex records that at fetch time and imposes each card at its own size — no flag, no config. Cards of one size share pages; a size that isn't the configured trim gets pages of its own, with as many cells as the page actually holds:

$ proxdex sheet deck
⬗ 1 oversized card(s) — oafr-21 — print at 88.9×127mm on their own pages (2×2 per page)
✓ 4 cards (fronts) → 2 page(s) @ 1400dpi → print-batches/…/fronts.pdf

The configured trim keeps the configured cols/rows exactly as before, so a library of ordinary cards sees the layout it always did. A card's size is never silently changed to fit the sheet.

Cut bleed and medium colour-correction are not baked into the card — they're applied at sheet time, extended outside the trim, so the master stays a clean, resizable, device-neutral card. Where do effects go? Author the look in grade (after upscaling, WYSIWYG); frame expansion goes before upscale in border; bleed + medium reproduction happen in sheet. See uniform prints.

Layout on disk

<library>/
├── proxdex.toml                     # config + library marker
├── INDEX.md                         # generated: search hub + print status
├── back-mtg.png                     # shared card back, per game (optional)
├── cards/
│   ├── ex3-dragon/
│   │   ├── .game                    # "pokemon" — set codes alone can't say
│   │   └── ex3-90_dragonite-ex/
│   │       ├── .game
│   │       ├── .skip-upscaled       # this step was deliberately bypassed
│   │       ├── ex3-90_1_original.png
│   │       ├── ex3-90_2_bordered.png   # only if the frame needed expanding
│   │       ├── ex3-90_3_upscaled.png
│   │       └── ex3-90_4_edited.png     # trim-size master (no bleed)
│   └── isd-innistrad/
│       ├── .game                    # "mtg"
│       └── isd-51_delver-of-secrets-insectile-aberration/   # two-sided
│           ├── .faces               # the side names, front first
│           ├── .front               # which side prints on the front (default 1)
│           ├── .skip-bordered_f2    # per-side state, like everything else
│           ├── isd-51_1_original.png       # side 1 keeps the plain names
│           └── isd-51_1_original_f2.png    # side 2 carries the _f2 suffix
├── profiles/
│   └── matte-200.json               # one print medium: your notes, its recipe,
│                                    # and every calibration round measured on it
└── print-batches/
    └── 2026-07-18_dark-deck/
        ├── fronts.pdf
        └── batch.toml               # cards + copies, the profile and page
                                     # settings used, printed?, notes

Install

uv tool install proxdex        # global CLI in ~/.local/bin  (or: pip install proxdex)
uv tool install "proxdex[ui]"  # + the local web UI (`proxdex ui`)
uv tool install .              # from a local checkout
uv tool upgrade proxdex        # later

macOS, Linux and Windows, on Python 3.11–3.13. CI runs the suite and a real library end to end — init, import, border fit, imposed PDF — on all three, because the defects that only appear on one platform live in that path and not in a unit test. One caveat, inherited rather than ours: on Linux arm64 (a Pi, Graviton, Docker on Apple Silicon) cardbleed's jpeglib dependency has no prebuilt wheel, so apt install build-essential first. x86_64 Linux, macOS and Windows all install from wheels with no compiler.

cardbleed ships as a dependency, so it's bundled in proxdex's own venv — no separate install, and proxdex finds it there even though it isn't on your PATH. It is pinned >=0.4.1: cardbleed runs inside proxdex's process and prints to proxdex's stdout, and 0.4.1 is the first release whose own output survives a stream that cannot encode it.

Upscayl is installed separately, and cannot be otherwise

Everything proxdex needs comes with it — except the upscaler. That one is a desktop application, and no pip/uv install can supply it:

• Upscayl is not a Python package. It is an Electron app whose engine, upscayl-bin, is a native Vulkan binary. It is not published on PyPI, so there is nothing for an extra to depend on. (There is an upscayl name on PyPI — version 0.0.0a1, described as "A small example package". It is unrelated. proxdex does not depend on it and neither should you.)
• So there is no proxdex[upscale] extra, deliberately. An extra can only pull Python wheels, and the upscale step has no Python dependencies at all — it runs a binary. An extra here would install nothing and mean nothing.

Install it the way you install applications:

brew install --cask upscayl      # macOS
# or download from https://upscayl.org — macOS, Windows (installer or portable
# zip), Linux (AppImage, deb, rpm)

proxdex then finds it by itself on all three platforms, in Upscayl's own install layout — the engine at resources/bin, the models at resources/models:

Some installs have no fixed home and cannot be guessed: Upscayl's Windows installer lets you choose the directory, its portable zip unpacks wherever you put it, and a Linux AppImage runs from a temporary mount. Point at those:

[tools]
upscayl_bin    = "D:/Apps/Upscayl/resources/bin/upscayl-bin.exe"
upscayl_models = "D:/Apps/Upscayl/resources/models"

Keep the binary in its own folder — on Windows it needs the vcomp140.dll shipped beside it, so copying just the .exe out will not work.

proxdex where tells you what this machine has, and when it finds nothing it says where it looked, which is usually the answer:

upscaler  upscayl ✓ /Applications/Upscayl.app/Contents/Resources/bin/upscayl-bin

Without it, proxdex still works. The upscale step is the only thing affected, and it is affected honestly: proxdex upscale refuses up front with what to install (not per card, halfway through a batch), and in the web UI its Run button is disabled with the same sentence and the Skip button beside it. Nothing else changes — the stage still exists, an upscaled image a card already holds is still shown and still printed, and proxdex skip upscale is a first-class choice that leaves the earlier stage as the master.

Internally the step talks to an Upscaler backend rather than to Upscayl by name (upscale.BACKENDS), so a second engine is one class and one registry entry — including, if one ever ships wheels for every Python proxdex supports, a pip-installable one. Today there is exactly one backend, and it is Upscayl.

Library vs. tool

The tool is installed once; your library (cards, config, batches) is just a folder. proxdex locates it, git-style:

1. --root DIR (accepted before or after the command), else
2. the nearest proxdex.toml searching up from the current directory, else
3. $PROXDEX_ROOT (set this in your shell profile to run from anywhere):

export PROXDEX_ROOT=~/Documents/Proxies
proxdex where     # confirm which library, config and default game are active

Config lives in <library>/proxdex.toml (created by init), so it travels with the data and each library can differ. New config keys added by a tool upgrade fall back to defaults, so old libraries keep working. INDEX.md is regenerated automatically after any command that changes state (no need to run index by hand).

Usage

cd ~/Documents/Proxies
proxdex init                   # one-time: create the library here

proxdex sets                   # every set of the game, grouped as the game groups them
proxdex browse base1           # page through one set, ✓ on the cards you already have
proxdex search entei ex        # find a card by name, pick which print to fetch
proxdex fetch ex3-90 ex6-105   # or download directly by id

proxdex border ex3-90 --inner-top .04 --inner-right .05 \
                      --inner-bottom .04 --inner-left .05   # reshape to spec
proxdex upscale ex3-90         # Upscayl
proxdex grade ex3-90           # the uniform look → the trim master

proxdex sheet dark-deck        # correct for the medium + bleed + impose → PDF + batch
#   ...print the PDF (colour management OFF), then:
proxdex printed dark-deck      # mark the batch printed

proxdex ls                     # every card, side, stage progress, printed?
proxdex ls --only ready --sort recent   # same filters the contact sheet offers
proxdex ls --per-page 40 --page 2       # a long library, by the page
proxdex show ex3-90            # everything the card's API says, plus local state

Two-sided cards read the same way, one row per side, with ↑ on the side that prints on the front:

proxdex fetch isd-51           # downloads both sides
proxdex border isd-51 --face 2 --inner-top .04 --inner-right .05 \
                               --inner-bottom .04 --inner-left .05
proxdex flip isd-51            # print the other side on the front
proxdex sheet dfc --faces duplex   # its reverse prints on the back

That's the loop: search → prepare (per step) → sheet → printed. Any of border, upscale and grade can be skipped instead of run — a card is ready to impose once grade is settled either way.

import files loose images (Upscayl-GUI output, or --id an arbitrary scan). Where each file lands is read off its name — the card id it starts with, the stage (upscayl → upscaled), the side (_f2) — and --dry-run shows the whole plan before a byte moves:

proxdex import ~/upscaled/*.png --dry-run   # what each file would become
proxdex import ~/upscaled/*.png             # ex*_upscayl_*.png → the upscaled stage
proxdex import scan.png --id ex6-105        # arbitrary file → looks up + files it
proxdex import ~/dump/*.png --on-existing skip   # keep the stages already there

The plan names what it replaces, what two files would collide over, and which later stages go stale — and it is the same plan the web UI's import wizard shows, so the preview and the import cannot disagree.

Commands accept card ids to scope them (proxdex upscale ex6-105); with none, they act on the whole library. proxdex searches up from the current directory for proxdex.toml, or pass --root DIR.

Everything the web UI can do has a verb here, and the reverse — settings included:

proxdex config show dpi        # every setting with its meaning and default
proxdex config set sheet.dpi=1200 sheet.faces=duplex   # comment-preserving
proxdex batches                # what has been imposed, and what is printed
proxdex rm ex3-90              # delete a card (asks first)
proxdex ls --json              # the same shape /api/cards serves the UI
proxdex doctor                 # stored images that aren't what proxdex writes now

doctor — the files you already have

proxdex learns things about how a stage image has to be stored, and a library filled last year does not benefit from a fix applied at the front door. doctor reads the header of every stored image and names what a current proxdex would have written differently: a die-cut corner left transparent (it prints as whatever was under the alpha), a grayscale or CMYK file, an unreadable file, or a bordered master that is not the trim aspect — which sheet crops to fit, losing border off two edges without saying so. Nothing about any of them is visible on screen.

proxdex doctor                 # report only; reads headers, writes nothing
proxdex doctor --fix           # repair what is a repair, in place (asks first)
proxdex doctor ex3-90          # or scope it to some cards

A repair rewrites only the file it names and leaves every later stage alone — the picture does not change, so nothing derived from it went stale. A wrong aspect is not repaired: re-fitting a border needs to know where the border is, which is a decision, so doctor names the step to re-run instead. The same check is the settings screen's stored images panel in the web UI.

Two games in one library

Each card records its game in a .game file next to its images, so a mixed library just works — ls shows it, backs and frame specs follow it. --game picks which TCG a command means; without it, [library] game from proxdex.toml is the default (and fetch falls back to trying the others).

proxdex search --game mtg delver of secrets --set isd
proxdex fetch neo-136              # tries the default game, then the rest
proxdex fetch --game mtg 4ed-100   # or say it outright

Web UI

Prefer clicking to typing? proxdex ui (needs the [ui] extra) starts a local server and opens a browser with full parity to the CLI — nothing leaves your machine (localhost only):

• Contact sheet — every card as a thumbnail with its game, stage strip and print status. Filter by name, game, set or state, sort, change tile size, and select cards to run or skip one step across all of them. A header strip counts where the whole library stands per stage, and how much is ready to print.
• Card console — the pipeline as a filmstrip: one frame per stage, carrying that stage's actual image, so the rail is the card's own history. Pick a frame and the panel beside it holds that step's settings — always, from the moment you focus it, with no mode to enter — plus Run / Skip / Reset. A step that has run shows its output, with a compare tool above the card: Result on its own (the default), Wipe to drag a split between the step's input and output, or Fade to cross-dissolve them on a slider — one at a time. A step that hasn't run shows its input at full colour, with the fact stated in the chrome around the card rather than dimmed over it. Two-sided cards get a side tab strip and a control for which side prints on the front. ←/→ cards, ↑/↓ steps, F flips side, C cycles compare.
• Border tool — focusing Border draws the card untouched, with a dashed outline over it showing where this printing's border should be, from its frame spec. Nothing has measured where it actually sits: that is yours to place, because a border read off the image is wrong in ways no screen shows until the card is cut (see Border correction). From there you Skip, or press Align the border to bring up four draggable marks starting at the spec's own numbers. Drag one and a loupe shows the source pixels at 6× with the mark on a crosshair; arrow keys nudge it, or type the inset as a percentage. Run stays disabled until the marks are up and a fit solves — a reshape with no idea where the border is has nothing to reshape against. A borderless printing needs no marks at all, so it says so and Run is live immediately. The dashed lines are what the fit is aiming at and the solid ones are what you drag; once the step has run, the outline stays over its output, which is the cheapest check there is that the fit landed.
• Browse — every set of a game as a grid of its own logos, under the game's own grouping (a Pokémon series, a Magic set_type), with a bar on each tile showing how much of that set you already hold. Open one and it is a paged card grid with the set's symbol beside every print, a green ✓ on the ones already filed, and the same filter bar Search has. This is the screen for when you know the set and not the name, which is most of the time.
• Adding cards, two ways — because they are two intentions. + Add under a card downloads that one now, and the button becomes ✓ In your library the moment it lands. Or click the artwork to pick cards — a picked card takes the accent on its own frame and a badge you can read across the grid, and a tray at the foot of the window shows the thumbnails of everything picked with one Add N to library. The tray outlives the page you picked on: it survives turning the page, changing a filter, switching between Browse and Search, and a reload. It can hold both games at once, and each card is fetched under its own.
• Search — pick a game, query by name with filters served from the provider's own catalogs (rarities, types, subtypes; colours for Magic), sorted and paged, add selected, with or without the cards they're printed alongside. Hover a hit for full ↗ — the provider's own scan at full size, for telling two prints apart. Every filter is a removable chip, and the whole query lives in the URL.
• Import wizard — drop a folder of scans or an Upscayl output and review it one row per file before anything is sent: the card it goes to, the stage, the side, and what it would do — a new stage, a replacement, a slot two files want, a name with no id in it. The review is import --dry-run computed on the server from the filenames alone, so a two-hundred-file folder previews without uploading a byte; the thumbnails are the browser's own copies. A row with no id gets a Find… search to name the card, or an id for every unnamed row at once from a set code plus the number already in each filename (4.png under base1 → base1-4; a name with no number is left for you). already there chooses replace-or-keep for the run, a checkbox narrows the table to just the rows that need a decision, and the files then go one request at a time so a failure belongs to one named file instead of the folder. Before you have dropped anything the screen states the three steps and what a filename tells it — which is knowable up front, and much cheaper to act on before you have chosen two hundred files.
• Card data sheet — every field the provider returns, its outbound links, and what the card is printed alongside — a meld partner, the melded card, the tokens it makes — each addable in one click.
• Settings — a real form: every setting carries its label, explanation, unit and default, all read from the code itself, with the raw TOML key kept visible. Nothing is written until you save, and the save bar only exists while something differs. Card backs, the frame specs (with the warnings frames check reports) and the calibration loop live here too.
• Make sheet — the whole library or just what you selected, with a per-card side choice for two-sided cards, made where the consequence is. If the batch mixes card sizes it says so up front, with how many of each fit a page. The PDF it writes is linked the moment it exists — the browser's version of sheet --open, which opens the file on whatever machine you typed it on. Mark printed and rebuild index from the toolbar.
• The border is two steps, and the second one is the fill. Step one is the reading: place the marks and Run, with cardbleed's defaults. That reading is recorded, so it never has to be taken again. Step two appears once the step is done — cardbleed's thirteen fill settings, right under the step's own controls, and changing one re-borders the card there and then. What you are looking at is the output, not a preview; the geometry never moves, only the invented border, and the later stages are rebuilt as with any re-run. What you settle on is kept on the card. Where nothing is being added — the marks already on the spec — the panel says so rather than offering controls that cannot change the picture.
• Waiting tells you what it is waiting for. A batch of cards or the pages of a PDF shows a real bar — the running command's own count, 3 of 12, with the card or page it is on. The long single jobs that nothing can count (one card through Upscayl) show elapsed time and, once you have run that command twice, ~41s typical — the median of your last runs, labelled as the estimate it is, never dressed up as a bar position. A plain read is quicker than a dialog deserves and gets a hairline at the top of the window instead.

? shows every keyboard shortcut; G then L/S/, jumps between screens.

Every screen has its own URL — /library, /card/ex3-90/upscale, /card/isd-51/border?side=2, /browse?game=mtg, /browse/base1?sort=number&page=2, /search?q=charizard&rarity=Rare+Holo, /settings — so back and forward work, a card (and a side) is bookmarkable, and a reload lands where you were (scroll included). A set you are browsing is a path, because it is a page you navigated to; the filters beside it are parameters, because they narrow that page rather than replacing it. Switching views does no round-trip at all: the library, search results, the set index and settings are held client-side, and images are served under a version stamp so the browser caches them permanently and never refetches one it already has.

Set logos and card scans come through the server, shrunk and kept. The providers serve a set's wordmark at 1000px and a card at full scan size, and the set index draws 174 of the former in a slot 2.25rem tall: 24.7 MB, and 45 MB for one 60-card page, every visit. proxdex fetches each once, resizes it to the size it is actually drawn at and keeps it in the cache directory — so the first screen of the index is 215 KB instead of 4.2 MB, and the second visit does no network at all. proxdex where counts what is held and --clear-cache drops it.

A result tile also asks for a smaller picture in the first place, since shrinking on arrival only helps the browser — the server was still pulling the full scan to fill its cache. A tile takes Pokémon's /small (245px, ~30 KB against 825 KB) and Magic's image_uris.normal (488×680, ~120 KB against a median 1657 KB), which took a cold 60-card page from 3.5s to 0.7s. Only the full scan is ever filed — the thumbnail never becomes a master — and a card's full ↗ link still opens the provider's original, which is what it is for.

The whole pipeline — its order, each step's label and skippability, and each step's settings schema with this library's defaults — is served from Python. The UI renders its stepper and its control panels from that and spells no step name or option of its own, so a step added in the code appears in the browser with its controls already built.

The UI bundles its own component library (Bootstrap, MIT), so it never reaches out to a CDN — everything is served from localhost.

proxdex ui                 # → http://127.0.0.1:8756

Print sheet

proxdex sheet <name> [ID[:COPIES]...] corrects each master for the medium, extends cut bleed outside the trim (cardbleed), imposes onto pages, and writes print-batches/<date>_<name>/<faces>.pdf plus a manifest. proxdex renders the PDF itself, so the print path is fully determined — print with your printer's colour management OFF so a calibration holds.

• Copies and per-run overrides. ID:4 prints a playset, --copies N applies to the whole run, and --faces/--page/--orientation/--cols/--rows/--bleed/--dpi/ --guides/--profile change this run without touching the library's settings. --dry-run reports the page plan and writes nothing.
• Any input size → exact card size. Whatever resolution a card is, it's scaled to its own physical size at sheet DPI — the configured dimensions ([card], default 63×88mm) for an ordinary card, 89×127mm for an oversized one. fit = cover fills the card preserving aspect (matching-aspect cards lose nothing); contain pads; stretch forces it.
• Mixed sizes get their own pages. Cells are grouped by trim size, and each group is imposed with its own grid, so an oversized card never has to share a 63×88 cell. Duplex mirroring happens within each group, so backs still land behind their fronts.
• Fronts, backs, or duplex (--faces or [sheet] faces). Duplex emits a front page then a mirrored back page (duplex_flip = long|short), so double-siding lines up. Backs come from a shared [sheet] back_image or a per-card <id>_back.png.
• Offsets nudge the whole image (mm): front_offset_* and, crucially for duplex registration, back_offset_* (e.g. 0.4, 0.35).
• Cut guides: guide_style = full (grid lines) / corners (crop marks) / none, with placement, length, color, width, and independent guides_front / guides_back (cut from the front, so backs default off). Optional printer reg_marks. All under [sheet].

The PDF is lossless (Flate-embedded, never JPEG) and rendered at [sheet] dpi (default 1400, --dpi to override) so the printer never upsamples; only one page raster is held in memory at a time.

Card backs

proxdex back sets the shared back used by sheet --faces backs|duplex. Backs are per game — a mixed library needs both — and each card picks its own, so a duplex sheet of Pokémon and MTG cards comes out right:

proxdex back --game mtg                        # Scryfall's standard MTG back
proxdex back --game pokemon --file my-back.png # your own scan
proxdex back --game mtg --url https://…/back.png

The file lands at back-<game>.png and is applied at sheet time through the same medium colour-correction and bleed as the fronts. Per-card backs: drop <id>_back.png in a card's folder. Note: there's no reliable Pokémon-back API (the back is one image, owned by TPC) — supply your own high-res scan.

Finding cards

There are two ways in, and they answer different questions. Search needs a name. Browse does not — which matters, because most of the time what you know is the set.

Browsing by set

proxdex sets lists every set of a game, grouped the way that game groups them, and says how many of each set your library already holds:

$ proxdex sets --game pokemon --group "Mega"

Mega Evolution 6 sets · 979 cards · 2025-2026
Set     Name               Cards    Released  Yours
me5     Pitch Black          120  2026-07-17      ·
me4     Chaos Rising         122  2026-05-22      ·
...

The grouping is the game's own, not proxdex's, and the two are different kinds of fact: a Pokémon series is an era, so the newest leads; a Magic set_type (Expansion, Core, Commander, Masters, …) is a kind of product, which has no date order, so those follow a fixed list. --group, --match and --owned narrow the list; --json gives you the whole thing as data.

Then proxdex browse <set> pages through one set, with a ✓ on every card already in your library:

$ proxdex browse base1 --sort number --per-page 8
Base base1 · 102 cards · 1999-01-09 · Base  1/102 in your library
#     ID       Name       Set   Year    No.  Rarity     Artist
1     base1-1  Alakazam   Base  1999  1/102  Rare Holo  Ken Sugimori
...
4  ✓  base1-4  Charizard  Base  1999  4/102  Rare Holo  Mitsuhiro Arita
...
1-5 of 102 · page 1 of 21 · ✓ 1 already in your library · --page 2 for more

Searching by name

proxdex search queries the game's API by name — every word must appear in the card name — and shows each match's set, release year, collector number, rarity and artist so you can tell prints apart:

$ proxdex search entei ex
#  ID       Name            Set                       Year     No.  Rarity        Artist
1  ex4-91   Entei ex        Team Magma vs Team Aqua   2004   91/95  Rare Holo EX  Ryo Ueda
2  ex7-97   Rocket's Entei  Team Rocket Returns       2004  97/109  Rare Holo EX  Ryo Ueda
3  bw5-13   Entei-EX        Dark Explorers            2012  13/108  Rare Holo EX  Shizurow
Fetch which? [numbers/ranges/ids · 'all' · blank to cancel]: 1

Type 1, 1,3, 1-3, an id, or all. Skip the prompt with --select 1,3 or --fetch; add --open to preview the first 12 result images in your browser. (The web UI's equivalent is a full ↗ link on each hit — a browser cannot ask the machine running the server to open anything, and should not.)

The filters are the same on both

search and browse take one set of filters, because browsing a set is a search with a set and no name — one code path, one result row, one pager:

Every filter is pushed to the provider, so the count in the footer is the whole answer's and not this page's — 1-5 of 102, with a real page count and a real last page. An earlier version fetched a hundred rows and sieved them locally, which could only ever report "100 results" for a set of 553 and re-fetched the same hundred for page 2. Ask for a page past the end and it says so, and names the last real one, rather than reporting no matches over an answer that has plenty.

Upscaling

This is the one step that needs software proxdex does not ship — see Upscayl is installed separately for why that cannot be fixed with an extra, and what happens when it is missing (short version: only this step is affected, and it says so).

proxdex upscale drives Upscayl's engine (upscayl-bin) directly — no GUI round-trip — and mirrors the app's own options: any of the seven built-in models, an output scale, and optional Double Upscayl (runs the model twice, so 2× doubled = 4×, up to 16×). The command construction matches the app exactly, including only passing -s when the scale differs from the model's native 4×. The bundled binary and models are auto-detected on macOS, Windows and Linux; for an install in a non-standard place, set the paths under [tools].

Set defaults once in proxdex.toml:

[tools]
upscayl_model  = "digital-art-4x"  # + upscayl-standard-4x, upscayl-lite-4x, high-fidelity-4x,
                                   #   remacri-4x, ultramix-balanced-4x, ultrasharp-4x
upscayl_scale  = 2                 # 1 | 2 | 3 | 4
upscayl_double = true              # run the model twice (default on → 2× becomes 4×)

Every one of these is a closed set — model, scale and double are validated in the config, on the CLI and in the web UI alike, so a typo names the valid options at load instead of failing later inside upscayl-bin. (The flip side: custom .param models are not selectable.)

Override per run: proxdex upscale --model ultrasharp-4x --scale 4 --double. Prefer the GUI? Skip this step and proxdex import its output instead — the import wizard reads _upscayl_ in a filename as "this is the upscaled stage", so a whole output folder files itself.

Border correction (frame expansion)

Some scans are cut into the card's printed frame, so its border is too thin. proxdex border expands the frame up to the real thing — before upscaling — using cardbleed to continue the existing pattern rather than smear pixels. This is frame correction, distinct from cut bleed (which sheet adds outside the trim).

You say where the border currently sits with --inner-top/-right/-bottom/-left (fractions of the image; the UI's align marks do this by dragging), and the card's frame spec supplies the target widths. The art is un-distorted so the borders land exactly on spec — that is the point of the step, so it is on by default; --no-stretch gets as close as the source allows instead.

There is no --auto, and removing it was the point. There was: it scanned each edge inward and pre-placed the marks for you. It shipped, and it was wrong in three ways that no screen showed — each found only by comparing it against a reading taken by hand:

• On a Beta Sol Ring (stone frame at luminance 37 against a black border at 27) it walked straight past the real edge to the light text box: 37-41px where the border ends at 23px, 65% too far.
• On dft-501 it crossed a black keyline, a thin yellow line and a second black keyline, answering 56px where the flat yellow band ends at 50px.
• On sld-912, which is full-bleed, it found a border anyway — the dark art read as one at T4.04 R6.45%, and the fit then cropped into the picture on all four edges.

Each of those produces four plausible numbers, and a plausible number presented as a measurement is worse than no number at all: it looks finished. So proxdex asks where the border is instead of inventing it, and the measurements that replaced the detector are one row per card in docs/measuring-frames.md, taken by hand. Do not expect it back.

Only measured specs ship

Twelve do, and every millimetre in them was read off a real card by hand:

$ proxdex frames
Spec                Name                                                        Game                  Border T/R/B/L (mm)        Card
pokemon-wotc        Pokémon · WOTC vintage (Base-Neo Destiny)                   Pokémon               3.45 / 3.15 / 3.45 / 3.15
pokemon-ecard       Pokémon · e-Card (Expedition-Skyridge)                      Pokémon               3.12 / 3.24 / 6.76 / 7.16
mtg-1993            MTG · 1993 frame (Arabian Nights-4th Edition)               Magic: The Gathering  2.74 / 2.47 / 2.74 / 2.47
mtg-1993-alpha      MTG · 1993 frame (Alpha, Beta, Collectors' Edition)         Magic: The Gathering  2.74 / 1.96 / 2.74 / 1.96
mtg-1993-unlimited  MTG · 1993 frame (Unlimited, Revised)                       Magic: The Gathering  3.63 / 2.98 / 3.63 / 2.98
mtg-1997            MTG · 1997 frame (Mirage-7th Edition)                       Magic: The Gathering  3.42 / 3.07 / 3.42 / 3.07
mtg-2003            MTG · 2003 frame (8th Edition-M14, and the `future` frame)  Magic: The Gathering  2.99 / 2.98 / 2.99 / 2.98
mtg-m15             MTG · M15 frame (Magic 2015-present)                        Magic: The Gathering  2.56 / 2.56 / 2.56 / 2.56
mtg-yellow-band     MTG · yellow box-topper band                                Magic: The Gathering  3.76 / 4.27 / 3.76 / 4.27
mtg-oversized       MTG · oversized plane or scheme (89×127mm)                  Magic: The Gathering  2.98 / 2.99 / 2.98 / 2.99  oversized
mtg-vanguard        MTG · oversized Vanguard                                    Magic: The Gathering  5.30 / 4.03 / 5.30 / 4.03  oversized
borderless          Borderless (no printed frame)                               any                   0.00 / 0.00 / 0.00 / 0.00

There is no confidence column, and that was a correction rather than a simplification. There were three levels, and one of them — "read off the publisher's scans" — rested on a false premise: a scan carries its own crop. Trimmed 0.3mm inside the real cut edge, every border read from it is 0.3mm narrow, every card in the sample agrees with every other, and nothing in the image says so. Grading that "trusted" dressed up a guess. So the account of where a number came from lives where it cannot be rendered as a verdict: a comment above each spec in frames.py, and a row per card in docs/measuring-frames.md.

A printing with no measured spec resolves to nothing, and border refuses it — rather than fitting it to another era's numbers, which looks perfect and is wrong:

$ proxdex border sv1-1
SKIPPED sv1-1: no frame spec has been measured for this printing (sv1, Pokémon).
Measure a card and record it with `proxdex frames set`, assign it, or pass
--frame to fit against a spec for this run.

proxdex frames check lists every card in that position, along with the other three faults it reports: a frames/*.json that will not parse, a pin or rule naming a spec that is gone, and a trait rule on a card whose traits were never recorded.

proxdex frames coverage is the same question about cards you do not own yet — what has nobody measured at all — and it asks each game the question its own border followed. Pokémon's ran for known runs of sets, so a row is a set:

$ proxdex frames coverage --game pokemon
○ Pokémon — 21 of 174 sets covered

Scarlet & Violet — 0 of 18 covered
Set       Name              Year  Held  Spec           From
sv10      Destined Rivals   2025  —     none measured  —
sv9       Journey Together  2025  —     none measured  —
…

Magic's changed with the printing's frame generation — a modern set holds retro-frame cards beside modern ones — so a row is a generation and there is deliberately no per-set verdict, which comes out ✓ 5 of 5 frame generations covered. Pokémon from Diamond & Pearl onward (2007-05) is the real gap today; the e-Card sets closed with hand readings, and the whole ex series answers — though only its first five sets were actually read, with ex5–ex16 inheriting that era's plain border rather than being measured, which docs/measuring-frames.md records as inherited.

The e-Reader specs are the ones whose four numbers differ, and that is the card's doing. Expedition, Aquapolis and Skyridge carry the Nintendo e-Reader dot-code strip down the left edge and along the bottom, so those two are roughly twice the other two — and the other two, at 3.12 and 3.24mm, are WOTC's border almost exactly. Collapsing opposite edges the way every other spec here does would have split the difference on all four, asking ~2.5mm too much border on two edges and too little on the others, and it would have looked right on screen because the overlay is drawn in fractions too.

The strip then moved: across Ruby & Sapphire, Sandstorm, Dragon, Team Magma vs Team Aqua and the promos beside them (ex1–ex4, np) it runs along the bottom alone, and some cards in those sets carry no dot code at all and have a plain square border. So those five sets resolve to two specs, nothing in the metadata says which a given card is, and border names both and lets you pick — the same offer the e-Card sets get.

Which spec a card gets, and why

Seven things can decide it, and border says which one did: --frame for this run, the card's own pin, the printing (the provider said borderless), one of your rules, a set default, the shipped baseline for its era or frame generation, or nothing at all. Add your own with frames set, and rules in frames/rules.json match on a number range, an id list, or a trait the provider recorded — so one set can need more than one spec without anybody choosing per card.

A borderless or full-art print has no frame to match, and a modern set mixes both under one set code — so the set cannot answer this but the printing can. proxdex reads it from the provider at fetch (Scryfall's border_color and the art-series layout) and records it in the card's own .frame marker, so the border step reshapes it to the card aspect and nothing else. --frame borderless is the whole fix for a print whose metadata is wrong about its own border:

proxdex border neo-136 --frame borderless
proxdex border neo-136 --frame mtg-m15 --save    # and pin it to the card for good

Changing a spec's numbers invalidates nothing on its own — a master fitted to the old ones still looks perfect. So border records what it fitted to beside the file, and proxdex doctor reports a master whose spec has moved since.

Uniform prints

grade applies one look — brightness, contrast, saturation, gamma — to every card, so a mixed batch prints as a set. Defaults live under [grade] and every one of them is also a per-run flag:

[grade]
brightness = 1.03   # printers + matte paper dull the image
contrast   = 1.06
saturation = 1.10
gamma      = 1.0
levels     = 0.0    # optional: stretch ONE card's own black/white points

proxdex grade ex3-90                       # the library's look
proxdex grade ex3-90 --saturation 1.2      # this run only
proxdex grade base1-4 --levels 0.4         # a flat, hazy scan

--levels reads that card and changes only that card: it pulls its own darkest and brightest pixels toward full range, blended by the amount you give.

Grade does not try to match cards to each other by colour. An earlier version did — it read the colour of each card's frame and white-balanced every frame to one shared target. That is wrong at the premise: a card frame is yellow on a Pokémon card, black on a Magic one, and absent on a full-art print, so there is no common baseline to pull them to. With a mixed library the shared target came out olive, and a neutral grey inside a yellow-bordered card graded to deep blue while the same grey in a black-bordered card blew out to white. Both were measured; both are gone.

Matching the medium is a real problem, but a print-time one — the paper and ink are the same for every card on the sheet. That is what a print profile is for.

Print profiles (one per medium you own)

A profile is everything proxdex needs to know about "matte 200 g on the XP-15000 with colour management off": a name, your notes, and how it corrects. They live in <root>/profiles/<name>.json; [print] profile names the default.

proxdex profile list
proxdex profile new matte-200 \
        --notes "Canon TS8350 · matte 200 g · plain-paper setting · CM OFF" --use
proxdex profile show matte-200        # notes, numbers, every round, the trend
proxdex profile set matte-200 --note "switched to the rear tray"
proxdex profile rename matte-200 matte-200-rear
proxdex profile rm old-glossy

Write the notes down. Six months later they are the only way to reproduce a print.

Nothing ships pre-filled. There is one built-in name, none, and it is the identity — no correction at all. A new profile starts there too. proxdex has no numbers to offer for your paper: "foil needs saturation 1.38" was true of exactly one setup that nobody reading this owns, so a recipe like that is a guess wearing a label. Every real profile is one you made, one of two ways.

Fronts and backs can be corrected for different media — [print] back_profile or sheet --back-profile. Leave it unset and both sides use one profile, which is right for duplex, since a duplex sheet is one piece of paper. It exists because that is not always true: the reverse of a one-sided glossy stock is a different surface, and a backs-only run often goes on other paper entirely.

Defining a profile without a scanner

Four multipliers, set by hand, applied at print time. The trick is not to guess them on screen — a screen is not the paper — but to print one page of the same card at a row of values and pick the one that looks right:

proxdex profile strip matte-200 --vary saturation --from 1.0 --to 1.6 --steps 4
#   → one page, four cards at true size, each labelled with its saturation
#   → print it on the medium (colour management OFF), look at it, then:
proxdex profile set matte-200 --saturation 1.4
proxdex profile preview matte-200      # before | after on a card, on screen

One knob at a time: a page where two things changed tells you which page you like, not which value to keep. --vary takes saturation, contrast, brightness or gamma, and profile show tells you the numbers currently in force.

The web UI has the same thing under Print → By hand: the four numbers, an inline before/after, and a strip to print.

Calibrating a medium (a loop, on one sheet of paper)

With a scanner, proxdex measures the correction instead of guessing it. The loop is designed to be walked several times on one sheet: each round prints the chart into a different slot of a 2×3 grid, so six rounds fit an A4 page.

proxdex calibrate chart                      # → profiles/<name>_round1.pdf, slot 1,1
#   print it on the medium (colour management OFF)
#   scan the whole page (scanner auto-correction OFF), then:
proxdex calibrate add --scan scan.png        # records the round, refits, reports
#   feed the SAME sheet back in and repeat — the next chart goes in slot 2,1
proxdex profile show                         # watch the error fall
proxdex calibrate proof                      # target vs scan, patch by patch
proxdex calibrate disable --round 3          # a misfeed or a crooked scan
proxdex calibrate enable  --round 3          # …and put it back

Every round is kept, and the correction is refitted over all of them at once, so each round makes it truer rather than replacing what you measured last time. Round 1 prints the raw target, which measures how far off the medium is; every round after prints the target through what is known so far, which samples the space where your cards actually live. Against a simulated press it converges 16.1 → 2.2 → 1.6 → 1.5 → 1.4 mean RGB.

It also tells you when to stop. A loop you are invited to repeat forever wastes paper: once three rounds in a row have improved the fit by under half a level each, calibrate add and profile show say so and stop suggesting the next chart — what is left is the medium's own gamut, and no amount of measuring puts ink in the printer that is not there. Measure again when the ink, the paper or the driver changes.

The error you are shown covers only colours this medium can reach. White paper is not 255, ink is not 0, and a saturated blue at mid-lightness can need more cyan than exists — so those patches are named and excluded rather than averaged in, which would leave a floor that can never fall. Reachability is measured by inverting your print's own response, and it is a property of the medium, so every round is scored over the same patches: the trend moves when the print improves, not when the patch set does.

The chart is 80 patches: a 16-step neutral ramp, then a 4×4×4 lattice of the cube's interior. Two decisions there are worth knowing, because both were measured rather than assumed:

• The lattice is pulled inside the printable box on purpose. Paper is not 255 and ink is not 0, so a patch at pure red or pure white measures nothing — it clips, and gets dropped from the fit. The chart proxdex shipped through 0.5.0 spent 24 of its 36 patches that way, leaving ~12 usable samples to fit a 10-parameter model. Same press, same code: the old chart settled at 2.31 mean RGB, this one at 1.36.
• Denser is not better. Patch area is the budget. At six charts per A4 these are 5.1 mm of ink with 1.1 mm gutters — 121 px across on a 600 dpi scan. Push to 228 patches and accuracy gets worse; a 512-patch near-continuous chart was worse than the 36-patch one it would replace, because read noise and neighbour bleed grow faster than coverage helps. A continuous gradient is worse again: there is no flat area to average, and 1% of geometric error becomes a correlated 2.3 levels of error in every reading. (A 3-D LUT, which is what a dense lattice would justify, also lost to the polynomial at every density tested.)

Rounds are never deleted. A bad one — a misfeed, a scan with the scanner's auto-correction left on — is switched off: the correction refits without it, and switching it back on restores exactly what it was doing. That is the only way to see with and without. proxdex profile show also gives each round a pull: how far the correction moves if that round is left out. A round pulling much harder than its neighbours is either your most informative measurement or an outlier, and it is worth knowing which. In a run where round 3 was scanned with auto-correction on, its pull came out at 17.7 against 5.6 / 5.4 / 4.4 for the others.

The chart travels the same renderer as a card sheet, so the correction is measured on the exact path it is applied to. proxdex sheet then applies it, and the stored masters stay neutral — switching media is a different --profile, not a re-grade.

Honest limits. The scanner is the measuring device, so this makes prints true as your scanner sees them — excellent for proxies, not colorimetric. Some target colours are simply outside a medium's gamut: paper is not 255 and ink is not 0, so those patches can never be hit, and proxdex says how many rather than folding them into an average that could never reach zero. And you must turn off the scanner's auto colour/contrast, or it fights the loop.

Building a print sheet

proxdex sheet <name> [ID[:COPIES]...] imposes the masters. Copies are how proxies are actually printed, and every page setting can be overridden for this run only — a print run is this paper on this printer today, not a library preference.

proxdex sheet playset ex3-90:4 base1-4:2      # a playset, and a pair
proxdex sheet deck --copies 4                 # four of everything ready
proxdex sheet deck --dry-run                  # the page plan, writing nothing
proxdex sheet deck --orientation landscape --cols 4 --rows 2 --bleed 3
proxdex sheet deck --profile foil-clear --notes "third attempt, rear tray"
proxdex sheet deck --faces duplex --profile matte-200 --back-profile glossy-reverse

--dry-run reports the pages per card size before anything is rendered, from the same code that imposes the PDF. The batch manifest records the copies, the profile and the page settings, so a reprint is reproducible rather than remembered.

The web UI has the same thing as a screen (Sheet): pick cards, set copies, and the page plan updates as you go. Print manages profiles and walks the calibration loop — the slot map shows which part of the sheet is used, and the round table shows the error falling.

Development

One command for the environment, and it is the same one CI uses:

uv sync --group dev      # ruff, pyright, pytest — plus the [ui] extra

The dev group deliberately pulls the [ui] extra rather than listing its packages again, so lint and typecheck see webui.py. node is needed too, for one test (below); every CI runner ships one, and the test skips loudly without it.

The gate

Five commands, and they are exactly what CI runs — if these pass locally, CI passes:

uv lock --check                             # the lock still agrees with pyproject
uv run --group dev ruff check src tests
uv run --group dev ruff format --check src tests
uv run --group dev pyright                  # strict
uv run --group dev pytest

webui.html is a vanilla-JS SPA and is not linted or typechecked by any of them. After editing its <script>, extract the block and run node --check on it — that is the only thing standing between a typo and a blank page. scripts/release.sh does it for you, and so does the parity test below, indirectly.

The suite is deliberately small: it covers only what a person cannot re-check by eye, which is why tests/test_fit_parity.py exists — it cuts solveFit out of webui.html and runs it in node against cardbleed's Python solve_fit, because a drift between the two makes the align overlay lie about where a card will land.

Running your checkout vs. the installed tool

These are not the same program, and the difference has shipped bugs twice:

# your checkout, on a library in the current directory
uv run proxdex ls

# your checkout, on a library somewhere else
uv run proxdex --root ~/Documents/Proxies ls

# your checkout, from *any* directory (handy when the library is the cwd)
uv run --project ~/Code/proxdex proxdex --root ~/Documents/Proxies ls

# what a user actually gets: no dev group, no extras
uv tool install .

uv run gives you the dev group, and a user has no dev group. Because that group carries the [ui] extra, an import that a core module needs but that is declared under [ui] works perfectly in a checkout and dies for everyone else. That is not hypothetical: tomlkit shipped that way for two releases — green on six CI jobs across three platforms — and a plain pip install proxdex wrote the print PDF and then died with ModuleNotFoundError. Two things guard it now, and both are worth knowing about before you add a dependency:

• tests/test_deps.py reads the declaration in pyproject.toml rather than trying the import, because in the environment the suite runs in every import works. Every non-stdlib import must be a declared dependency, or sit inside a try/except ModuleNotFoundError that says how to install it.
• CI's installed job builds the wheel, installs it into a bare venv with no extras and no dev group, and drives the whole pipeline through it.

To reproduce that job locally before you push:

uv build && uv venv bare && VIRTUAL_ENV=bare uv pip install dist/*.whl
bare/bin/proxdex init lib && bare/bin/proxdex --root lib where

Test against a throwaway library

Never your real one. A temp directory with a proxdex.toml marker is a library, so:

uv run proxdex init /tmp/lib
uv run proxdex --root /tmp/lib <command>

cardbleed ships its own suite — cardbleed --selfcheck.

Releasing

One command, from a clean main:

scripts/release.sh 0.6.0 notes.md    # or omit the file and write the tag message

It runs the full gate (lint, format, typecheck, node --check on the web UI's script, and a wheel build that asserts the data files are in it), bumps _version.py, commits, writes an annotated tag, and pushes. Nothing is mutated until every check passes. Pushing the tag runs the Release workflow, which re-checks the gate, refuses a tag whose version does not match _version.py, publishes to PyPI by trusted publishing, and creates the GitHub release from the tag's own message with the artifacts attached.

License

MIT