CLI Reference

cli

Pokemon battle tournament simulator.

Simulate full round-robin tournaments across Smogon tiers, run head-to-head battles, search the roster, and manage local cached data.

Run 'pokerena COMMAND --help' for details on any subcommand.

Usage:

cli [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

battle

Run a single 1v1 battle and print the result.

Provide two Pokemon names to battle them directly, or use --random to pick two at random from the loaded generation roster.

Examples:

pokerena battle pikachu mewtwo
pokerena battle --random --gen 2
pokerena battle pikachu charizard --rand-ivs --seed 7

Usage:

cli battle [OPTIONS] NAME

Options:

Name	Type	Description	Default
--random	boolean	Pick two Pokemon at random instead of specifying names.	False
--gen	integer	Generation to draw Pokemon from when using --random.	1
--gen1-mode	boolean	Use Gen 1 stat formula.	False
--rand-ivs	boolean	Use random IVs instead of max IVs.	False
--seed	integer	Random seed for reproducibility.	None
--verbose, -v	boolean	Enable debug logging.	False
--help	boolean	Show this message and exit.	False

db

Manage the local PokeAPI and Smogon data cache.

Cached data lives at ~/.cache/pokerena/ (Linux/macOS) or %LOCALAPPDATA%\pokerena\Cache\ (Windows).

Usage:

cli db [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

clear

Delete cached files.

Omit NAMESPACE to clear everything. Specify 'smogon' or 'pokeapi' to clear only that namespace.

Examples:

pokerena db clear
pokerena db clear smogon
pokerena db clear pokeapi

Usage:

cli db clear [OPTIONS] NAMESPACE

Options:

Name	Type	Description	Default
--yes, -y	boolean	Skip confirmation prompt.	False
--help	boolean	Show this message and exit.	False

fetch

Download and cache PokeAPI and Smogon data.

Fetches all Pokemon data for the given generation and writes it to the local cache. Each generation covers a cumulative dex range starting from dex 1: Gen 1 = 151 Pokemon, Gen 2 = 251, Gen 9 = all 1025.

Subsequent runs (including tournaments) will use the cache and skip network requests. Use --force to re-fetch and overwrite existing cached files.

Examples:

pokerena db fetch --gen 1
pokerena db fetch --gen 9
pokerena db fetch --all-gens
pokerena db fetch --gen 1 --force

Usage:

cli db fetch [OPTIONS]

Options:

Name	Type	Description	Default
--gen	integer	Generation to fetch (1-9). Each generation fetches the cumulative dex range: Gen 1 = 151 Pokemon, Gen 2 = 251, ..., Gen 9 = all 1025. Use --all-gens to fetch every generation.	None
--all-gens	boolean	Fetch all generations 1-9.	False
--force	boolean	Re-fetch even if data is already cached.	False
--verbose, -v	boolean	Enable debug logging.	False
--help	boolean	Show this message and exit.	False

info

Show the cache location and per-namespace file counts.

Usage:

cli db info [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

status

Show per-generation cache coverage.

Reports how many Pokemon are cached for each generation and whether the data looks complete based on expected dex ranges.

Usage:

cli db status [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

search

List and filter Pokemon by name, type, tier, generation, or BST.

NAME is an optional case-insensitive substring match on Pokemon name. Results are printed as a table with columns: Name, Gen, Types, Tier, BST, HP, Atk, Def, SpA, SpD, Spe.

Examples:

pokerena search --gen 1 --sort bst --desc
pokerena search char --gen 1
pokerena search --type fire --tier ou --min-bst 500
pokerena search --sort bst --desc --limit 10

Usage:

cli search [OPTIONS] NAME

Options:

Name	Type	Description	Default
--gen	integer	Filter to a specific generation (1-9). Omit to search all gens.	None
--type	text	Filter by type (e.g. fire, water). Matches either type slot.	None
--tier	text	Filter by Smogon tier (ubers/ou/uu/ru/nu/pu).	None
--min-bst	integer	Only show Pokemon with BST >= N.	None
--max-bst	integer	Only show Pokemon with BST <= N.	None
--sort	choice (name | bst | tier | gen | hp | attack | defense | sp_atk | sp_def | speed)	Sort results by field.	name
--desc	boolean	Reverse sort order (descending).	False
--limit	integer	Maximum number of results to show.	None
--help	boolean	Show this message and exit.	False

tournament

Run a full tournament simulation for one or all generations.

Runs round-robin battles within each Smogon tier (Phase 1), adjacent-tier playoffs (Phase 2), and a grand final (Phase 3). Results are written to results/gen{N}/.

Examples:

pokerena tournament
pokerena tournament --gen 2 --battles 50
pokerena tournament --all-gens --workers 8
pokerena tournament --gen 1 --rand-ivs --seed 42

Usage:

cli tournament [OPTIONS]

Options:

Name	Type	Description	Default
--gen	integer	Generation to simulate (1-9). Controls the roster: Gen 1 = dex 1-151, Gen 2 = dex 1-251, ..., Gen 9 = all 1025 Pokemon. Use --gen 9 or --all-gens to include the full roster.	1
--all-gens	boolean	Run all generations 1-9 sequentially.	False
--battles	integer	Battles per matchup in Phase 1 tier round robins.	20
--rand-ivs	boolean	Use random IVs (0-15) instead of max IVs (31).	False
--seed	integer	Random seed for reproducibility. Use with --rand-ivs.	None
--fetch	boolean	Force re-fetch of PokeAPI and Smogon data before running.	False
--top	integer	Number of entries to show in console leaderboards.	10
--workers	integer	CPU workers for parallel battles. Default: CPU count.	None
--gen1-mode	boolean	Use Gen 1 stat formula instead of Gen 3+ default.	False
--verbose, -v	boolean	Enable debug logging to stderr.	False
--help	boolean	Show this message and exit.	False