mirror of
https://github.com/mwisnowski/mtg_python_deckbuilder.git
synced 2025-12-16 15:40:12 +01:00
92 lines
3.6 KiB
Markdown
92 lines
3.6 KiB
Markdown
# Headless & CLI Guide
|
|
|
|
Leverage the shared deckbuilding engine from the command line, in headless mode, or within containers.
|
|
|
|
## Table of contents
|
|
- [Entry points](#entry-points)
|
|
- [Switching modes in Docker](#switching-modes-in-docker)
|
|
- [Headless JSON configs](#headless-json-configs)
|
|
- [Environment overrides](#environment-overrides)
|
|
- [CLI argument reference](#cli-argument-reference)
|
|
- [Include/exclude lists from the CLI](#includeexclude-lists-from-the-cli)
|
|
- [Practical examples](#practical-examples)
|
|
|
|
---
|
|
|
|
## Entry points
|
|
- Interactive menu: `python code/main.py`
|
|
- Headless runner: `python code/headless_runner.py --config config/deck.json`
|
|
- Both executables share the same builder core used by the Web UI.
|
|
|
|
## Switching modes in Docker
|
|
Override the container entrypoint to run the CLI or headless flows inside Docker Compose or plain `docker run`.
|
|
|
|
```powershell
|
|
# Compose example
|
|
docker compose run --rm -e APP_MODE=cli web
|
|
|
|
# Compose with headless automation
|
|
docker compose run --rm `
|
|
-e APP_MODE=cli `
|
|
-e DECK_MODE=headless `
|
|
-e DECK_CONFIG=/app/config/deck.json `
|
|
web
|
|
```
|
|
|
|
Set `APP_MODE=cli` to switch from the Web UI to the textual interface. Add `DECK_MODE=headless` to skip prompts and immediately run the configured deck.
|
|
|
|
## Headless JSON configs
|
|
- Drop JSON files into `config/` (e.g., `config/deck.json`).
|
|
- Headless mode auto-runs the lone JSON file; if multiple exist, the CLI lists them with summaries (commander + themes).
|
|
- Config fields cover commander, bracket, include/exclude lists, theme preferences, owned-mode toggles, and output naming.
|
|
- Partner mechanics are optional: set `"enable_partner_mechanics": true` and supply either `"secondary_commander"` or `"background"` for combined commander runs.
|
|
|
|
## Environment overrides
|
|
When running in containers or automation, environment variables can override JSON settings. Typical variables include:
|
|
- `DECK_COMMANDER`
|
|
- `DECK_PRIMARY_CHOICE`, `DECK_SECONDARY_CHOICE`, `DECK_TERTIARY_CHOICE`
|
|
- `DECK_BRACKET_LEVEL`
|
|
- `DECK_ADD_LANDS`, `DECK_LAND_COUNT`, `DECK_CREATURE_COUNT`, `DECK_RAMP_COUNT`
|
|
|
|
Precedence order: **CLI flags > environment variables > JSON config > defaults**.
|
|
|
|
## CLI argument reference
|
|
Run `python code/headless_runner.py --help` to see the current argument surface. Highlights:
|
|
|
|
- Type indicators make expectations explicit (e.g., `PATH`, `NAME`, `INT`).
|
|
- Theme selection accepts human-readable names: `--primary-tag "Airbending"` instead of numeric indexes.
|
|
- Bracket selection via `--bracket-level`.
|
|
- Ideal counts such as `--land-count`, `--ramp-count`, `--creature-count`, and more.
|
|
|
|
## Include/exclude lists from the CLI
|
|
You can specify comma- or semicolon-separated lists directly through the CLI:
|
|
|
|
```powershell
|
|
python code/headless_runner.py `
|
|
--commander "Jace, Vryn's Prodigy" `
|
|
--include-cards "Sol Ring;Jace, the Mind Sculptor" `
|
|
--exclude-cards "Chaos Orb;Shahrazad" `
|
|
--enforcement-mode strict
|
|
```
|
|
|
|
Semicolons allow card names containing commas. Enforcement modes mirror the Web UI (`off`, `warn`, `strict`).
|
|
|
|
## Practical examples
|
|
```powershell
|
|
# Build a Goblins list with tuned counts
|
|
python code/headless_runner.py `
|
|
--commander "Krenko, Mob Boss" `
|
|
--primary-tag "Goblin Kindred" `
|
|
--creature-count 35 `
|
|
--land-count 33 `
|
|
--ramp-count 12
|
|
|
|
# Fire a headless run via Docker using an alternate config folder
|
|
docker compose run --rm `
|
|
-e APP_MODE=cli `
|
|
-e DECK_MODE=headless `
|
|
-e DECK_CONFIG=/app/config/custom_decks `
|
|
web
|
|
```
|
|
|
|
The CLI prints a detailed summary at the end of each run, including enforcement results, resolved themes, and export paths. All artifacts land in the same `deck_files/` folder used by the Web UI.
|