ÿþ# <ØÏÜ MTG Python Deckbuilder



[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

[![Docker](https://img.shields.io/badge/docker-supported-blue.svg)](https://www.docker.com/)



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



## =Ø9Ý 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)

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

```powershell

pip install -r requirements.txt

python code/main.py

```



### From this repo with Docker Compose (PowerShell)

```powershell

docker compose build

docker compose run --rm mtg-deckbuilder

```



## >ØÝ Headless mode (no prompts)



- Auto-headless: set `DECK_MODE=headless`

  - Example (PowerShell):

    ```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):

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



### Run locally (no Docker)

```powershell

# Show resolved settings (no run)

python code/headless_runner.py --config config/deck.json --dry-run



# Run with a specific config file

python code/headless_runner.py --config config/deck.json



# Point to a folder and choose one

python code/headless_runner.py --config config --auto-select-config



# Override via CLI

python code/headless_runner.py --commander "Pantlaza, Sun-Favored" --primary-choice 2 --secondary-choice 0 --add-lands true --fetch-count 3

```



### CLI flags

- --config <path>                Path to JSON config file or a folder to discover configs (uses DECK_CONFIG by default)

- --commander <name>             Commander name to search and select

- --primary-choice <n>           Primary theme index

- --secondary-choice <n|none>    Secondary theme index or omit with "none"

- --tertiary-choice <n|none>     Tertiary theme index or omit with "none"

- --add-lands <bool>             Include land building steps (true/false)

- --fetch-count <n>              Requested number of fetch lands

- --dual-count <n>               Requested number of dual lands

- --triple-count <n>             Requested number of triple lands

- --utility-count <n>            Requested number of utility lands

- --add-creatures <bool>         Add creatures

- --add-non-creature-spells <bool>  Add non-creature spells orchestrator

- --add-ramp <bool>              Add ramp (when not using orchestrator)

- --add-removal <bool>           Add removal (when not using orchestrator)

- --add-wipes <bool>             Add board wipes (when not using orchestrator)

- --add-card-advantage <bool>    Add card draw (when not using orchestrator)

- --add-protection <bool>        Add protection (when not using orchestrator)

- --use-multi-theme <bool>       Enable multi-theme selection logic

- --dry-run                      Print resolved config and exit

- --auto-select-config           If --config points to a folder, list configs to choose



Booleans accept: 1/0, true/false, yes/no, on/off.



### JSON export in headless

- By default, headless runs do not export a JSON run-config to avoid duplicates.

- Opt-in with:

  ```powershell

  $env:HEADLESS_EXPORT_JSON = "1"

  python code/headless_runner.py --config config/deck.json

  ```

- Tip: when opting in, prefer using `--config` instead of a `DECK_CONFIG` file path to avoid creating both a stem-based JSON and a second explicit-path JSON.



Example JSON (`config/deck.json`):

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



## =ØyÝþ 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



## ÁÜ 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`



## =ØæÜ Releases

- Release notes are maintained in `RELEASE_NOTES_TEMPLATE.md`. Automated workflows read from this file to populate Docker Hub and GitHub releases.



## ÄÜ License & help

- License: MIT (see `LICENSE`)

- Issues/Requests: GitHub Issues/Discussions

- Docker details: see `DOCKER.md`