Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/invvd/mtg-cheaper-deck/llms.txt

Use this file to discover all available pages before exploring further.

By the end of this guide you will have MTG Cheaper Deck installed, your local Scryfall card database populated, and your first deck analysis running — either as a local web app in your browser or as a one-shot CLI report in your terminal. The whole process takes under five minutes on a typical machine.
1

Clone the repository

Download the project from GitHub and move into the project directory.
git clone https://github.com/invvd/mtg-cheaper-deck.git && cd mtg-cheaper-deck
2

Create and activate a virtual environment

Create an isolated Python environment so the project’s dependencies do not conflict with anything else on your system.
python -m venv .venv
Then activate it for your platform:
.venv\Scripts\activate
3

Install dependencies

Install all required packages from requirements.txt.
pip install -r requirements.txt
This installs the five direct dependencies the project relies on:
  • requests — HTTP client used by both the Moxfield fetcher and the Scryfall sync.
  • python-dotenv — loads DATABASE_URL and other settings from the .env file.
  • sqlalchemy — SQLAlchemy Core powers the database layer; switching engines requires only a URL change.
  • rich — terminal formatting for the interactive mode and CLI report tables.
  • flask — lightweight web framework for the local web app interface.
4

Create the .env file

Create a .env file in the project root to configure the database connection.
.env
DATABASE_URL=sqlite:///./data/cards.db
SQLite is the default and requires no extra installation — the database file is created automatically inside ./data/ on first run. To use PostgreSQL instead, change DATABASE_URL to a postgresql+psycopg://... connection string and install psycopg[binary] (pip install "psycopg[binary]"). No other code changes are needed.
5

Sync the Scryfall database

Populate the local card database by downloading the Scryfall Oracle Cards bulk file.
python sync_scryfall.py
This fetches the current bulk-data download URL from api.scryfall.com/bulk-data/oracle-cards, streams the gzipped JSONL file (~38k cards), and upserts every card into ./data/cards.db in batches of 1,000. The sync stores card names, oracle text, keywords, color identity, CMC, EDHREC rank, legalities, and USD prices — everything the scoring algorithm needs.
The first sync takes approximately 30–60 seconds depending on your connection and machine. Re-run sync_scryfall.py daily (or set up a cron job) to keep card prices and EDHREC rankings fresh. The sync is completely independent of the user-facing tools and never blocks a deck analysis.
6

Run the tool

Choose whichever interface suits your workflow. All three read from the same local database.
python webapp.py
  • Web App — starts a local Flask server at http://127.0.0.1:5000. Open it in your browser to browse the full deck with real Scryfall card images, filter by card category, and apply replacements one click at a time while watching the deck total update live.
  • Interactive Terminal — steps through the deck card by card in your terminal, showing scored suggestions for each slot and letting you pick a replacement or move on.
  • CLI Report — prints a single-pass Rich table with original card, suggested replacement, price delta, savings percentage, similarity score, and the reasons behind each match. Append --json to get machine-readable output instead.

Next: Web App

Learn how to use the local Flask web app to review and replace cards across your entire deck with images and live price tracking.

Next: How Scoring Works

Understand the four-factor similarity formula — keywords, oracle text, CMC, and EDHREC rank — and how to read the score thresholds.

Build docs developers (and LLMs) love

Get started for freeTalk to us