Andreas/mtg_python_deckbuilder
1
0
Fork 0
mirror of https://github.com/mwisnowski/mtg_python_deckbuilder.git synced 2025-12-16 15:40:12 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
mtg_python_deckbuilder/docs/headless_cli_guide.md

3.6 KiB
Raw Blame History

Headless & CLI Guide

Leverage the shared deckbuilding engine from the command line, in headless mode, or within containers.

Table of contents

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.

# 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:

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

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