Skip to content

Command flags

Every flag of the engines' command-line tools, read from the Go source by scripts/docs_flags.py. A test fails when this page and the source disagree. The tools use Go's flag package, so -name value, -name=value and --name all work. Using the engines says what each tool is for and shows examples.

mtgsim

go run -trimpath ./cmd/mtgsim. Plays seeded games on gorge between bots and checks each by replay.

Flag Type Default Meaning
-a string none bot policy name for seat 0 (default: heuristic)
-b string none bot policy name for seat 1 (default: heuristic)
-cpuprofile string none write a CPU profile here
-deckdir string none read each -decks name from /.json instead of the embedded repo decks
-decks string none comma-separated deck names (default: the first -seats of the repo decks)
-dir string .cards corpus directory (holds ir.gob.gz / cardsfolder)
-format string constructed game format: constructed or commander (40 life, commanders in the command zone)
-games int 1 number of games to play
-memprofile string none write an allocation profile here and print the run's allocation totals
-mulligans int 0 London mulligans each seat may take before turn 1 (default 0, none)
-policies string none comma-separated bot policy per seat, from seat 0; "-" or empty keeps a seat's default heuristic; overrides -a/-b
-sb-agent string repeatable register a SpellBench v2 stdio agent: name=/path/to/agent (repeatable)
-seats int 4 number of seats
-seed uint64 0 base seed; game i uses seed+i for both the engine and its bot
-shape string none write a JSON game-shape census to this file (game rows, then one aggregate)
-v bool false print the deck assigned to each seat before every game
-verify bool false replay each game and compare its event chain against the live run

forgec

go run -trimpath ./cmd/forgec. Fetches the Forge card corpus, compiles it into gorge's IR and reports coverage. The flags are shared by its four subcommands: fetch, compile, report and coverage.

Flag Type Default Meaning
-dir string .cards working directory for the corpus and IR cache
-out string .coverage coverage: gitignored directory to write coverage.md and summary.md into
-ref string master Forge git ref to fetch
-repo string cards.ForgeRepo Forge git repository to fetch from
-top int 25 how many missing primitives to list in report

cardfuzz

go run -trimpath ./cmd/cardfuzz. Plays random and exploring games over the whole corpus on gorge, records failures and tracks which cards and abilities it has reached.

Flag Type Default Meaning
-autopay string off off|all|mixed: which production-bot seats cast through offered payment plans (heuristic.Bot.EnableAutoPayMana); mixed picks per game and seat from the seed
-autopay-mirror bool false mirror each auto-pay planned cast against float-then-cast (opt-in)
-batch int 400 games per batch (coverage snapshot granularity)
-cpuprofile string none with -repro: write a CPU profile of the replay here
-dir string .cards corpus directory
-dump-at uint64 0 with -repro: print the first pending decision whose Seq is at least this log index (options, payment actions, pool, battlefield)
-explore bool true one seat per game (by seed parity) plays the coverage-exploration policy (heuristic.NewExploreBot) instead of the production bot
-explore-autopay bool false the -explore seat auto-pays too wherever -autopay would select its seat (off by default: the wrapper hides priority mana activations, cutting explore coverage)
-failures string cardfuzz-failures.jsonl append failure records here
-games int 1000 games to play this run
-hang duration 90*time.Second wall-clock budget per game before it is recorded as a 'hang' (its goroutine is abandoned)
-journal string none append 'start ' / 'end ' around every game: a fatal runtime error (a stack overflow) kills the whole process past any recover, and the journal names the game the crashing goroutine was playing
-line int 1 1-based line of -repro to replay
-manabrew bool false play every seat through the ManaBrew wire (mbtest.TranslatingSeat + seeded-random MockClient): one shared census printed at the end, failures record "manabrew": true and replay through -repro; -explore is ignored and -autopay/-explore-autopay are rejected
-max-hangs int 6 stop the run once this many hung games are leaked (each burns a core)
-max-intents int 20000 intent cap (recorded as an 'intents' failure)
-max-objects int 20000 live object cap (recorded as a 'bigboard' failure; 0 disables)
-max-outcome-gap float64 0 with -spellbench outcome: fail when the paired 95% interval of the (v2 - native) seat-0 win rate excludes 0 and |gap| exceeds this many percentage points (0 disables); a forfeit always fails
-max-rebuild-fail float64 0.5 with -spellbench twin and -min-agree: fail when the neutral world could not rebuild the pick for more than this percentage of the run's decisions (0 allows none)
-max-stack int 256<<20 per-goroutine stack limit in bytes (runtime/debug.SetMaxStack): an unbounded recursion dies here instead of at Go's 1 GB default
-max-turns int 100 turn cap (a stall, not a failure)
-measure-manual-seat-plans bool false diagnostic: in -autopay off mode, force the payment planner on every priority window so manual_seat_priority_with_plan (the plans the eager publisher would have offered to manual seats) is populated. Rebuilds every seat's payment extension, so it costs runtime; it never changes game outcomes, intents, replay signatures or failure records, and it is ignored in all|mixed (which already measure)
-min-agree float64 0 with -spellbench twin: fail when a decision kind with at least 50 compared decisions agrees below this percentage (0 keeps the any-disagreement rule)
-missing bool false with -report: also list cards cast/played but with abilities never used, and which
-only-pair int -1 with -spellbench outcome: play only this pair index (0-based); the report keeps its original pair number
-plan-failures bool true record a game whose planned cast was reversed (kind planrev) or fell back to the manual window (planfb) as a failure
-policy string bot with -spellbench: the bot policy under test
-report bool false print coverage summary from -state and exit
-repro string none replay a failure record from this JSONL file (with -line)
-sb-v2-seats-both bool false with -spellbench outcome: both seats are v2 agents in the v2 lane (default: seat 0 only, against a native seat 1)
-seed uint64 1 base seed; game i of the run plays at hash(seed, games-so-far + i)
-skip string none JSONL of games not to play ({seed, sig, diag} per line, from a -journal crash): each is recorded as a 'fatal' failure instead
-spellbench string none twin|outcome: measure a gorge bot through the SpellBench v2 neutral world against its native play on fuzzed decks (spellbench.go); -autopay off|all applies, -failures takes the twin disagreements, -repro replays one
-state string cardfuzz-state.json persistent coverage state
-stats string none write the run's failure counts and auto-pay counters here as JSON
-tape bool false print the resolution kernel (engine/rules/resolve, the default engine path) counters, the legacy-ask census and the predicate-miss census at the end
-tape-worlds bool false with -tape: fork a redealt hypothetical world at every posed tape decision and drive it 6 random intents
-verify bool true replay every finished game and compare
-workers int 8 parallel games

kgen

go run -trimpath ./dirac/cmd/kgen. Compiles card pools from gorge's IR into dirac's binary card tables, and answers which cards dirac supports. dirac/cmd/kgen is a thin main over package dirac/kgen.

Flag Type Default Meaning
-all-blockers bool false with -census-std: keep lowering past a refusal and report every blocker of a card, not only the first of each node
-card-list string none card list file (one name per line) instead of -decks
-cards string .cards compiled card corpus directory
-census bool false print the (context, param) census instead of generating
-census-std bool false print refusal classes ranked by Standard-set carry instead of generating
-class string lockstep with -refuse: the kind of difference, the refused list's grouping
-decks string none deck pool directory (*.json)
-dump string none write a per-card IR dump here instead of generating (never commit it)
-four-seat bool false with -supported: a card a pod of three or more seats cannot hold (kop.CardPodLimited: StallTwoSeat at its start) is false
-layer-census bool false print the interim layer guard's reach (classified cards, refused pairs and deck pairs) instead of generating
-lir bool false print every card's lowered IR and refusals instead of generating
-ops string none write this pool's OPS.md to -out instead of generating
-out string none output directory; with -ops, the output file
-pool string fdn pool name
-refuse string none write this card's dirac/support/refused entry instead of generating (with -why and -repro)
-repro string none with -refuse: the game that shows it, POOL:SURFACE:PAIR[:POLICY[:MULLIGANS]]
-sets string none with -census-std: comma-separated set codes (default dirac/cardset/standard.txt)
-show string none print the kop.CardDef literal of the card named by the argument, from this pool's table, instead of generating
-supported string none print nametrue|false for every entry of this pool's table instead of generating
-synth-pools bool false write the synthetic evidence pools' binary tables under the corpus (make dirac-tables): nothing is written to the source tree
-tables bool false write every pool's binary table under the corpus (make dirac-tables): exit 3 means an ids.tsv changed, rebuild kgen and rerun
-tsv string none with -census-std: write a per-refusal TSV dump here
-unrefuse string none delete this card's dirac/support/refused entry instead of generating
-unverified bool false with -supported: cards without lockstep evidence count as playable (a refused card stays false)
-whatif string none with -lir: also refuse these cards (comma list) and report coverage
-why string none with -refuse: one line saying what differs

dplay

go run -trimpath ./dirac/cmd/dplay. Plays seeded games on dirac alone and prints a line per game and a summary.

Flag Type Default Meaning
-a string hbot seat A's player, who plays the pair's first deck: random, first, hbot or sbt
-b string random seat B's player
-cards string none gorge corpus directory (default: $GORGE_CARDS, else .cards in or above the working directory)
-config string configAutopay the verified surface to play: lockstep-autopay or lockstep-full
-cpuprofile string none write a CPU profile here
-deck-a string none deck JSON file for seat A, with -deck-b, instead of a pool
-deck-b string none deck JSON file for seat B
-decks string none deck directory (default: the set's pool, under $GORGE_POOLS or the module's .pools, else its committed slice)
-first-pair int 0 index of the first pair
-max-intents int 20000 decision cap per game; a capped game is a stall
-max-turns int 100 turn cap; a capped game is a stall
-memprofile string none write an allocation profile here and print the run's allocation totals
-mulligan-policy string coin how every seat mulligans: coin, lands, never, constructed or forge
-mulligans int 0 London mulligans each player may take (0 skips the round)
-out string none games file, one JSON line per game (default: stdout)
-pairs int 100 deck pairs, one game each
-pairs-file string none play these pairs: deckAdeckB[seed] per line; -first-pair skips lines and -pairs, when given, caps them
-pool string none pool.tsv (default: /../pool.tsv)
-sample-replay float64 0 fraction of games also written as koracle-game-2 records under .replays, which kfuzz -replay re-executes in gorge; needs -out
-seed uint64 1 base seed: pairs and game seeds derive from it, as in kfuzz
-set string fdn the card set to play: a deck pool by name, or a synthetic pool (std-trk, tail-NN)
-skip-refused bool false skip a pair the set refuses and count it, instead of failing
-split string all pool split the decks come from: train, eval or all
-summary string none summary file, one JSON object (default: stderr)
-wall duration 0 start no game after this much wall time (0: play every pair)
-workers int 1 games in parallel

sbv2dirac

go run -trimpath ./dirac/cmd/sbv2dirac. Serves dirac as a SpellBench v2 engine over stdio.

Flag Type Default Meaning
-corpus string none compiled Forge corpus directory (default: GORGE_CARDS or .cards)
-decks string none directory of gorge deck JSON files to serve beside the catalog (catalog_id = file stem)
-source-revision string none adapter source revision reported in hello_ok

kfuzz

go run -trimpath ./dirac/oracle/cmd/kfuzz. Plays seeded games on gorge and dirac in lockstep and reports the first decision where they differ.

Flag Type Default Meaning
-absolute bool false pool runs: exit 1 on any divergence, hang, panic, unmodelled stall, unknown option kind or error skip, or when no game was played; capacity stalls and refusals are counted and do not fail
-allow-unverified bool false pool runs: play the cards the table does not refuse, unverified ones too, as -evidence does
-answerers string first,rand -v2 transcript: comma-separated scripted answerers (first, rand)
-autopay-surface bool false deprecated alias of -surface autopay
-cards string none gorge corpus directory (default: $GORGE_CARDS, else .cards in or above the working directory)
-cmd-mini int 0 -seats above 2: cut every commander deck of the pool to this many cards, its commanders and an even spread of the rest (oracle.MiniCommanderDeck), so a Commander pod fits the oracle's card table: -kernel gorge
-coverage string none write the run's per-card/per-ability coverage TSV (oracle.Coverage) here and print a coverage summary line
-cpuprofile string none write a CPU profile here
-decks string none pool deck directory (default: the fdn pool's, under $GORGE_POOLS or the module's .pools, else its committed slice)
-events int 0 -repro: print the last N events of gorge's log when the game ends, objects named by card
-evidence string none pool runs: play the cards the table does not refuse, unverified ones too, and write the cards the run's clean games evidence (oracle.Coverage.Evidence), one name a line, here
-explain string none print this repro's actions rendered, one a line, and exit (what a recorded repro's old readable field held)
-features bool false vanilla/fdn: also assert the network inputs (dirac/feat vs policynet) at every decision
-first-game int 0 -v2 transcript: index of the first pool pair (repro anchor)
-first-pair int 0 index of the first pair
-focus string none -synth: deal a focus pool instead: every deck holds -focus-per-deck cards of this list (one card a line, enablers after a tab, ';'-separated) beside the enablers they name; the run is named after the file (fx-dsk.txt: fx-dsk)
-focus-per-deck int oracle.FocusPerDeck -focus: focus cards per deck
-game-timeout duration 30*time.Second a game with no result after this long, twice (one retry), is recorded as a hang and the run moves on; a hang fails the run (0: no watchdog)
-games int 100 -v2 transcript: seeded games per answerer
-implicates-all bool false pool runs: name every implicated card instead of the top ten, and print one line per game that fails -absolute: bad-game, pair, seed, outcome, class, the implicated cards joined by |, the sources of its latest actions joined by |, the cards of both decks joined by |, tab-separated; a game that recorded an unknown option kind also prints unknown-game, pair, seed, the kinds joined by |
-json bool false print the summary as JSON
-keep-going bool false count every divergence instead of stopping at the first
-kernel string gorge the kernel under test: gorge (gorge-vs-gorge self-check), gorge-api (the same through the contract's Kernel surface), vanilla (package kernel on dirac/vanilla's decks), fdn (package kernel on a registered card set's pool pairings) or any other registered pool such as blb (fdn's path on that set and its pool, oracle.Pools; see -list-pools)
-lead string gorge which side leads the lockstep: gorge or kernel (fdn/vanilla paths)
-list-pools bool false print the registered lockstep pools (name, inputs, label, decks, tree digest) and exit
-list-synth bool false print the synthetic evidence pools, one a line, and exit
-max-decisions int 20000 canonical decision cap; a capped game is a stall
-max-turns int 100 turn cap; a capped game is a stall
-memprofile string none write an allocation profile here and print the run's allocation totals
-mulligans int 0 London mulligans each player may take (0 skips the round)
-only string none -synth: play the supported cards and, of the unverified ones, only those this file names (one a line): a targeted evidence run deals the cards it owes evidence among cards that have it
-out string none directory for the first divergence's repro.json, and one file a bad game: capacity--pair.repro.json for a capacity stall, unmodelled--pair.repro.json for an unmodelled kernel stall, divergent-pair.repro.json for a divergent game (default: none written)
-pairs int 100 deck pairs (one game each)
-pairs-file string none pool runs: play these pairs instead of drawing from pool.tsv: deckAdeckB[seed] per line (oracle.ExplicitPairs); -first-pair skips lines and -pairs, when given, caps them
-pass-elision bool false elide priority decisions whose only option is pass (must match the kernel's)
-play-refused bool false pool runs: play the pairs holding a card refused by name too, as scripts/dirac-first-refusals.py settle does
-pods int 0 -seats above 2: pods to play (one game each; 0: -pairs)
-policy string random random, heuristic, explore (gorge's coverage-exploration bot, cmd/cardfuzz's) or first
-pool string none pool.tsv (default: /../pool.tsv)
-reach string none -synth: write one row per card of the list here: card, how far it got, decks, games, plays in clean games
-replay string none re-execute this kernel game (koracle-game-2) in gorge and report
-repro string none re-run this repro in lockstep and report
-search string paranoid -search-seats: the search, paranoid or maxn
-search-seats string none pool runs (-kernel a registered pool or -synth, -lead gorge): answer these seats, comma-separated (0 or 0,2), with dirac/search on the kernel's state; every other seat keeps -policy. Lockstep still compares every decision. Two seats
-search-sims int oracle.SearchSeatDefaultSims -search-seats: simulations per searched decision
-seats int 2 seats a game: 2 plays deck pairs; 3 or 4 plays pods of distinct decks (oracle.PodAt) with -kernel gorge (dirac holds two seats)
-seed uint64 1 base seed: pairs and game seeds derive from it (the pairing rule)
-set string fdn the generated card set the fdn kernel plays (a name in dirac/cardset)
-shrink int 200 shrink reruns for the first divergence (0: none)
-split string all pool split the decks come from: train, eval or all
-stats bool false fdn/blb: print each kernel pool's peak occupancy and the pair that reached it (kstats)
-surface string none the option surface both sides offer: autopay (neither side offers the plain casts gorge's planner never prices, oracle.Config.GorgeAutopaySurface) or full (default)
-synth string none play a synthetic evidence pool (make dirac-tables writes them): deal its decks in memory from -seed and report its reach; replaces -kernel, -set and -decks
-synth-decks int oracle.SynthDecks -synth: decks to deal
-v bool false list the unpriced plays by card (fdn: every game's first divergence)
-v2 string none run a v2 engine-parity check instead of lockstep: "transcript" plays the same seeded games on dirac/cmd/sbv2dirac and gorge's env and diffs their transcripts
-v2-max-decisions int 500 -v2 transcript: v2 decision cap per game (a prefix is compared; 0 uses 500)
-v2-no-chance bool false -v2 transcript: negative control: the gorge host keeps its secret-stream shuffles instead of dealing the dirac kernel's chance (must diff)
-v2-rand-full bool false -v2 transcript: no-op (a rand game is always compared whole; the flag keeps the old spelling working)
-v2-workers int 4 -v2 transcript: games in parallel
-workers int 1 games in parallel

khbot

go run -trimpath ./dirac/oracle/cmd/khbot. Compares gorge's heuristic bot with its port on dirac, decision by decision.

Flag Type Default Meaning
-autopay-surface bool true oracle.Config.GorgeAutopaySurface (gorge's own autopay surface)
-cards string none gorge corpus directory (default: $GORGE_CARDS, else .cards in or above the working directory)
-dealt string none play decks dealt from a pool's table (fdn), as a clone without the deck pool does, instead of -decks and -pool
-decks string none pool deck directory (default: the fdn pool's, under $GORGE_POOLS or the module's .pools, else its committed slice)
-first-pair int 0 index of the first pair
-hold bool false arm gorge TimingRules.HoldInstant on both sides (hbot must hold too)
-max-decisions int 20000 canonical decision cap per game
-pairs int 100 deck pairs (one game each)
-pass-elision bool true elide single-option decisions (the kernel's default configuration does)
-pool string none pool.tsv (default: /../pool.tsv)
-seats int 2 seats per game, at most dirac.MaxSeats; above 2 a game is a pod of consecutive pairings' decks, -pairs counting pods
-seed uint64 78 base seed (the pairing rule)
-split string eval pool split: train, eval or all
-synth string none play a synthetic evidence pool (make dirac-tables writes them) instead of -decks and -pool
-v bool false print every disagreement
-workers int 4 games in parallel

ksbt

go run -trimpath ./dirac/oracle/cmd/ksbt. Compares gorge's sb-tactical bot answering on gorge with the same bot answering through a view built from the dirac position.

Flag Type Default Meaning
-autopay-surface bool true oracle.Config.GorgeAutopaySurface (gorge's own autopay surface)
-cards string none gorge corpus directory (default: $GORGE_CARDS, else .cards in or above the working directory)
-decks string none pool deck directory (default: the fdn pool's, under $GORGE_POOLS or the module's .pools, else its committed slice)
-first-pair int 0 index of the first pair
-max-decisions int 20000 canonical decision cap per game
-pairs int 100 deck pairs (one game each)
-pass-elision bool true elide single-option decisions (the kernel's default configuration does)
-pool string none pool.tsv (default: /../pool.tsv)
-seed uint64 78 base seed (the pairing rule)
-split string eval pool split: train, eval or all
-v bool false print every disagreement
-workers int 4 games in parallel