11 KiB
Search guide
This guide covers day-to-day use of balatro-seed-search. Commands assume the
release binary is available on PATH; use
./target/release/balatro-seed-search when running directly from a checkout.
Joker searches
Search for one joker on or before an ante:
balatro-seed-search find-jokers \
--joker Blueprint --before-ante 2
Repeated jokers use AND semantics by default. Each requested joker may appear
in any ante from 1 through the inclusive --before-ante value:
balatro-seed-search find-jokers \
--joker Blueprint --joker Brainstorm \
--mode all --before-ante 4 --max-matches 5
Use --mode any for OR semantics:
balatro-seed-search find-jokers \
--joker Blueprint --joker Brainstorm \
--mode any --before-ante 3 --output seeds
Search Buffoon packs with --pack-joker. The command checks the first four
modeled packs in ante 1 and the first six in each later ante, ignoring packs
that cannot contain jokers:
balatro-seed-search find-jokers \
--pack-joker Blueprint --before-ante 3 \
--max-matches 5
--pack-joker is repeatable and can be mixed with shop --joker and Soul
--legendary targets. The selected --mode all|any, global ante limit, and
per-target NAME:MIN-MAX ranges apply across all three sources. Edition,
sticker, reroll, and exact-draw restrictions apply only to shop --joker
targets.
Search for any of the five legendary jokers through The Soul with
--legendary. This avoids writing an advanced JSON filter:
balatro-seed-search find-jokers \
--legendary Canio --before-ante 3 \
--random-start --max-matches 5
The option is repeatable and may be mixed with either joker option; the existing
--mode all|any applies across every requested target. Legendary searches
check all four modeled ante-1 packs and all six packs in each later ante.
Add an inclusive ante range to an individual target with NAME:MIN-MAX:
balatro-seed-search find-jokers \
--joker 'Brainstorm:2-5' \
--legendary 'Perkeo:3-' \
--mode all
Perkeo:-1 and Perkeo:.-1 mean “through ante 1.” Brainstorm:3- and
Brainstorm:3-. mean “ante 3 onward,” with an open upper bound ending at ante
8. Quote ranged targets so a leading or trailing hyphen is passed unchanged by
the shell. Targets without a suffix continue to use ante 1 through the global
--before-ante value. Explicit per-target ranges are independent of that
global default.
For example, the known five-character seed ALEEB can be checked without a
JSON file:
balatro-seed-search find-jokers \
--legendary Canio --before-ante 1 \
--seed-length 5 --named ALEEB --max-seeds 1
By default, the command checks the first 16 modeled shop-card draws in every
ante's queue. --max-rerolls X means the first two-card shop visit in that
ante, followed by at most X rerolls in that same visit. For example,
--max-rerolls 0 checks its two opening cards and --max-rerolls 3 checks
the first eight queue cards:
balatro-seed-search find-jokers \
--joker Blueprint --before-ante 3 --max-rerolls 3
The lower-level --slot 0..15 option selects one exact zero-based queue draw.
With one two-card visit, slots 0–1 are the opening cards, 2–3 are reroll 1,
and so on. Visiting another shop also consumes this queue; the same positions
could instead be opening cards of later visits without any rerolls. Explanations
therefore report queue positions, not guaranteed visit/reroll numbers.
--max-rerolls is not a per-visit or whole-run budget and assumes no shop-size
changes. It is rejected with Zodiac Deck, whose starting Overstock grants an
extra shop card; use explicit queue positions for that deck. --slot and
--max-rerolls are mutually exclusive.
Edition and sticker requirements may be combined with either scope:
balatro-seed-search find-jokers \
--joker Brainstorm --before-ante 4 \
--edition Negative --stake Gold \
--max-seeds 10M --max-matches 3
balatro-seed-search find-jokers \
--joker Blueprint --before-ante 3 \
--sticker Eternal --stake Black
Names are case-insensitive and validated before scanning. Misspellings fail
with a close-name suggestion. --legendary accepts only Canio, Triboulet,
Yorick, Chicot, and Perkeo. Use balatro-seed-search list to discover every
accepted joker, modifier, tag, boss, voucher, card, deck, and stake.
Search controls
--start-rankand--max-seedsbound the base-35 seed range. Seed counts accept case-insensitiveKandMsuffixes, such as10k,100k,1M, and10M.--seed-size Nuses the completeN-character seed space as the search range, automatically setting both the seed length and candidate count to35^N. For example,--seed-size 5covers all 52,521,875 five-character seeds. It supports--random-start(or a reproducible--start-rank) and wraps once to retain complete coverage. It cannot be combined with--seed-length,--max-seeds, prefix, or named-seed options. The normal--max-matcheslimit still applies; use--max-matches 0to exhaust the entire calculated range.--random-startchooses a new starting rank for each run and wraps at the end of the seed space. The final summary reports the chosen rank so the search can be reproduced later with--start-rank.--max-matches 0scans the whole range; another value stops after that many matches.--threads 0uses available CPU parallelism;--threads 1uses deterministic serial execution. Every thread count produces the same ordered results.--progress 1sshows a live progress bar with the scanned/total seed count, matches, search rate, and ETA on standard error. Rates above 1,000 seeds per second usek/s. Interactive terminals get a smoothly filled dashboard with a neutral blue active state and green completion state;NO_COLORdisables its color. When standard error is redirected, each update is emitted as an ANSI-free log line instead.--progress 0disables progress output.--output human|pretty|jsonl|seedsselects compact human text, boxed terminal cards, machine-readable JSON Lines, or seed-only standard output.--explainanalyzes every match and reports where each requested condition is first met. It works with human, pretty, and JSONL output; seed-only output remains intentionally machine-clean.--deckand--stakeselect run rules.--seed-length 1..8chooses the generated seed space.--max-rerolls 0..7limits joker targets to the first two-card shop visit plus that many rerolls in the same visit. Without it, use all 16 queue draws.
--random-start and --start-rank are mutually exclusive. A random search
visits at most the requested number of unique seeds; it never searches the
wrapped portion twice. With --seed-size, --seed-prefix, or --named, the
reported rank and wrapping refer to that mode's candidate space.
Named seeds
--seed-prefix restricts seeds to a fixed beginning, while --named finds the
text anywhere in the seed:
balatro-seed-search find-jokers \
--joker Blueprint --before-ante 3 --named CHAD --random-start
balatro-seed-search find-jokers \
--joker Brainstorm --before-ante 4 --seed-prefix CODEX
With the default eight-character length, --seed-prefix CODEX scans
CODEX111 through CODEXZZZ. --named CHAD scans only seeds containing
CHAD, whether it occurs at the beginning, middle, or end. Seeds containing
the fragment more than once are still visited only once. Lowercase input is
normalized to uppercase. --start-rank addresses the selected constraint's
compact candidate space, and a non-random search stops automatically at its
end.
Explaining search results
Add --explain to show the first useful location for every requested
condition. Locations identify the ante plus the modeled shop draw, pack number
and type, blind tag, boss, voucher, or card position as appropriate:
balatro-seed-search find-jokers \
--legendary Perkeo --before-ante 2 \
--seed-length 5 --named ALEEB --max-seeds 1 \
--explain
Human output uses a compact per-seed condition tree. With an any search, the
tree keeps each requested target separate and marks conditions that were not
present in that particular matching seed.
For structured analysis, combine it with JSON Lines:
balatro-seed-search find-jokers \
--legendary Perkeo --before-ante 2 \
--seed-length 5 --named ALEEB --max-seeds 1 \
--explain --output jsonl
Each result then contains an analysis object with condition, matched, and
detail for every condition. The existing inspect SEED --filter FILTER --output jsonl command provides the same analysis for one known seed without
running a search. --explain cannot be combined with --output seeds.
Pretty output
Use --output pretty for padded Unicode result cards instead of compact human
lines. It works on its own or with --explain:
balatro-seed-search find-jokers \
--legendary Perkeo --before-ante 2 \
--seed-length 5 --named ALEEB --max-seeds 1 \
--output pretty --explain
Long queries and analysis details wrap inside the box. The same format is
available from inspect, both for filter analysis and ante overviews. Use
human, jsonl, or seeds when output will be consumed by scripts.
Inspecting a seed
Without a filter, inspect prints an ante overview. With a filter, it explains
which clauses matched and where:
balatro-seed-search inspect 11111122 --antes 3
balatro-seed-search inspect 11111122 --filter blueprint.json
balatro-seed-search inspect 11111122 --filter blueprint.json --output jsonl
Creating advanced filters
Use create-filter to refine a joker and legendary query with normal command
line options and save the resulting JSON without starting a search:
balatro-seed-search create-filter \
--legendary Canio --legendary Perkeo --before-ante 2 \
--joker 'Blueprint:2-' --joker 'Brainstorm:2-' \
--joker 'Credit Card' --output hunt.json
balatro-seed-search search --filter hunt.json --random-start
The command accepts the same target, range, mode, edition, sticker,
--max-rerolls, and exact --slot options as find-jokers. See the
advanced filter format for piping and the generated format.
Other clause families can still be added by editing that JSON.
Shell completions
Generate a completion script for Bash, Zsh, or Fish:
balatro-seed-search completions bash > balatro-seed-search.bash
balatro-seed-search completions zsh > _balatro-seed-search
balatro-seed-search completions fish > balatro-seed-search.fish
See the advanced filter format for non-joker searches and the correctness notes before relying on game-version parity.