mtg_python_deckbuilder/README.md

# 🃏 MTG Python Deckbuilder

A fast, menu-driven CLI to build MTG Commander/EDH decks. Supports interactive and headless runs, CSV/TXT exports, and Docker.

🔹 Features

• Commander search with smart theme tagging (primary/secondary/tertiary)
• Power bracket selection and ideal count prompts
• CSV and TXT exports with stable filenames
• Headless mode (non-interactive) and a headless submenu in the main menu
• Config precedence: CLI > env > JSON > defaults

✨ Highlights

• Smart tagging and suggestions for commander + themes
• Exports CSV and TXT decklists to deck_files/
• Interactive menu with a headless submenu
• Works locally or in Docker (Windows PowerShell friendly)

🚀 Quick start

Docker Hub (PowerShell)

docker run -it --rm `
  -v "${PWD}/deck_files:/app/deck_files" `
  -v "${PWD}/logs:/app/logs" `
  -v "${PWD}/csv_files:/app/csv_files" `
  mwisnowski/mtg-python-deckbuilder:latest

From source

pip install -r requirements.txt
python code/main.py

From this repo with Docker Compose (PowerShell)

docker compose build
docker compose run --rm mtg-deckbuilder

🤖 Headless mode (no prompts)

• Auto-headless: set DECK_MODE=headless
  • Example (PowerShell):

    docker compose run --rm -e DECK_MODE=headless mtg-deckbuilder
    

• Use a JSON config: mount ./config to /app/config and set DECK_CONFIG=/app/config/deck.json
  • Example (PowerShell):

    docker compose run --rm `
      -e DECK_MODE=headless `
      -e DECK_CONFIG=/app/config/deck.json `
      mtg-deckbuilder
    

• Override via env vars (subset): DECK_COMMANDER, DECK_PRIMARY_CHOICE, DECK_ADD_LANDS, DECK_FETCH_COUNT, DECK_USE_MULTI_THEME
• Precedence: CLI > env > JSON > defaults

Headless submenu notes:

• If one JSON exists in config/, it auto-runs it
• If multiple exist, they’re listed as "Commander - Theme1, Theme2, Theme3"; deck.json shows as "Default"
• CSV/TXT are exported as usual; JSON run-config is exported only in interactive runs

Example JSON (config/deck.json):

{
  "commander": "Pantlaza",
  "use_multi_theme": true,
  "primary_choice": 2,
  "secondary_choice": 2,
  "tertiary_choice": 2,
  "add_lands": true,
  "fetch_count": 3,
  "ideal_counts": { "ramp": 10, "lands": 36, "basic_lands": 16, "creatures": 28, "removal": 8, "wipes": 3, "card_advantage": 8, "protection": 3 }
}

Notes: headless honors ideal_counts (leave prompts blank to accept). Only fetch_count is tracked/exported for lands.

🕹️ Usage (interactive)

1. Start the app (Docker or from source)
2. Pick Build a New Deck
3. Search/confirm commander
4. Pick primary/secondary/tertiary themes (or stop at primary)
5. Choose power bracket and review ideal counts
6. Deck builds; CSV/TXT export to deck_files/

⚙️ Environment variables (common)

• DECK_MODE=headless
• DECK_CONFIG=/app/config/deck.json
• DECK_COMMANDER, DECK_PRIMARY_CHOICE, DECK_SECONDARY_CHOICE, DECK_TERTIARY_CHOICE
• DECK_ADD_LANDS, DECK_FETCH_COUNT
• DECK_ADD_CREATURES, DECK_ADD_NON_CREATURE_SPELLS, DECK_ADD_RAMP, DECK_ADD_REMOVAL, DECK_ADD_WIPES, DECK_ADD_CARD_ADVANTAGE, DECK_ADD_PROTECTION
• DECK_USE_MULTI_THEME

<EFBFBD> Folders

• deck_files/ — CSV/TXT exports
• csv_files/ — card data
• logs/ — logs
• config/ — JSON configs (optional)

🧰 Troubleshooting

• Use docker compose run --rm (not up) for interactive sessions
• Ensure volumes are mounted so files persist (deck_files, logs, csv_files)
• For headless with config, mount ./config:/app/config and set DECK_CONFIG

<EFBFBD> License & help

• License: MIT (see LICENSE)
• Issues/Requests: GitHub Issues/Discussions
• Docker details: see DOCKER.md