balatro-seed-search/docs/searching.md

11 KiB
Raw Permalink Blame History

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-rank and --max-seeds bound the base-35 seed range. Seed counts accept case-insensitive K and M suffixes, such as 10k, 100k, 1M, and 10M.
  • --seed-size N uses the complete N-character seed space as the search range, automatically setting both the seed length and candidate count to 35^N. For example, --seed-size 5 covers 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-matches limit still applies; use --max-matches 0 to exhaust the entire calculated range.
  • --random-start chooses 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 0 scans the whole range; another value stops after that many matches.
  • --threads 0 uses available CPU parallelism; --threads 1 uses deterministic serial execution. Every thread count produces the same ordered results.
  • --progress 1s shows 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 use k/s. Interactive terminals get a smoothly filled dashboard with a neutral blue active state and green completion state; NO_COLOR disables its color. When standard error is redirected, each update is emitted as an ANSI-free log line instead. --progress 0 disables progress output.
  • --output human|pretty|jsonl|seeds selects compact human text, boxed terminal cards, machine-readable JSON Lines, or seed-only standard output.
  • --explain analyzes 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.
  • --deck and --stake select run rules.
  • --seed-length 1..8 chooses the generated seed space.
  • --max-rerolls 0..7 limits 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.