Skip to main content

​
Introduction

Pokemon Showdown provides a comprehensive command-line utility called pokemon-showdown that enables you to:
  • Simulate battles programmatically
  • Generate and validate teams
  • Convert between team formats
  • Start a Pokemon Showdown server
The CLI is designed to be “unixy” - it uses standard input/output streams, making it easy to pipe commands together and integrate with other tools and programming languages.

​
Installation

1

Install Node.js

Ensure you have Node.js version 22 or later installed on your system.
2

Clone the repository

git clone https://github.com/smogon/pokemon-showdown.git
cd pokemon-showdown
3

Build the project

./build
Windows users should use node build instead of ./build, and replace ./ with node in all commands.
4

Rebuild after updates

Every time you update the code (e.g., with git pull), run ./build again. If you encounter errors, try:
./build --force

​
Getting Help

You can access help for any command at any time: 
./pokemon-showdown -h
./pokemon-showdown help

​
Available Commands

simulate-battle

Simulate battles by sending commands via stdin and receiving output via stdout

Team Commands

Generate random teams, validate teams, and convert between team formats

Server Commands

Start a Pokemon Showdown server on a specified port

​
Command-Line Options

The pokemon-showdown executable supports several command-line flags:
FlagShortDescription
--help-hDisplay help information
--skip-buildSkip the automatic build step (server only)
--debug-DEnable debug mode for battle simulation
--replay-RGenerate replay data during battle simulation
--spectate-SGenerate spectator-compatible output

​
Piping Commands

One of the most powerful features of the CLI is the ability to pipe commands together:

​
Example: Generate and Export a Team

./pokemon-showdown generate-team gen8randombattle | ./pokemon-showdown export-team
This generates a random team and immediately converts it to human-readable format: 
Kartana @ Choice Band
Ability: Beast Boost
Level: 74
EVs: 85 HP / 85 Atk / 85 Def / 85 SpA / 85 SpD / 85 Spe
- Smart Strike
- Sacred Sword
- Knock Off
- Leaf Blade

Rotom (Rotom-Heat) @ Heavy-Duty Boots
Ability: Levitate
Level: 82
...

​
Example: Generate and Validate

./pokemon-showdown generate-team gen8randombattle | ./pokemon-showdown validate-team gen8ou
This generates a Random Battle team and validates it against OU format rules, which will typically produce errors: 
Your set for Coalossal is flagged as Gigantamax, but Gigantamaxing is disallowed
(If this was a mistake, disable Gigantamaxing on the set.)
Octillery's ability Moody is banned.

​
Team Format Requirements

Commands that accept team input expect teams in packed format or JSON format.Teambuilder export format (the human-readable format) is NOT supported as direct input. Use pack-team to convert exported teams to packed format first.
For detailed information about team formats, see the Teams documentation.

​
Usage from Other Languages

Since the CLI uses standard input/output, you can easily call it from any programming language that supports subprocess execution: 
import subprocess

result = subprocess.run(
    ['./pokemon-showdown', 'generate-team', 'gen9randombattle'],
    capture_output=True,
    text=True
)
team = result.stdout.strip()

​
Next Steps

Battle Simulation

Learn how to simulate battles programmatically

Team Management

Master team generation, validation, and conversion

Build docs developers (and LLMs) love

Get started for freeTalk to us