cli-mon-showdown 0.1.15

Command line interface for battling with a local Pokemon Showdown simulator

CLI-Mon Showdown

A terminal-based Pokémon battle CLI that drives the official Pokémon Showdown simulator for accurate mechanics, quick testing, and lightweight play.

Note: You need a local clone of Pokémon Showdown. This repo expects it at pokemon-showdown/ in the project root.

Features

• Accurate engine: uses the official Pokémon Showdown simulator
• AI opponents: Gemini AI agent for strategic battle decisions
• Teams: load Showdown import/export text files
• CLI-first: fast feedback loop and readable battle feed
• Random battles: generate teams via Showdown

Project Structure

• src/cli_mon_showdown/ - installable Python package (CLI, wrapper, Gemini agent)
• cli.py - shim so cli-mon still works locally
• pokemon-showdown/ - expected checkout of the Node simulator
• teams/ - example team files in Showdown format
• BATTLE_FIXES.md - notes on battle handling improvements

Requirements

• Python 3.10+
• Node.js 18+
• A local checkout of smogon/pokemon-showdown (default path pokemon-showdown/)

Quick Start

Install from PyPI

pip install cli-mon-showdown

# After installation, set up Pokemon Showdown dependencies with one command
cli-mon --init

# Optional: Set up Gemini AI agent with your API key
cli-mon --init --gemini-api-key YOUR_GEMINI_API_KEY

# Now you can use the CLI
cli-mon --help

Note: When installing from PyPI, Pokemon Showdown files are included but Node.js dependencies are not installed by default to avoid platform conflicts. You need to run npm install in the Pokemon Showdown directory after installation.

Run from a local clone

git clone https://github.com/papichoolo/cli-mon-showdown.git
cd cli-mon-showdown

python -m venv .venv
.venv\Scripts\activate

# Install the package in editable mode (includes Python dependencies)
pip install -e .

# Fetch the Showdown simulator
git clone https://github.com/smogon/pokemon-showdown.git
cd pokemon-showdown
npm ci
cd ..

# Run a battle with sample teams
cli-mon teams/p1.txt teams/p2.txt --format gen7ou

Gemini AI Agent Configuration

The CLI includes an optional Gemini AI agent that can play as Player 2, making strategic decisions based on battle state analysis. This provides a more challenging and realistic opponent compared to the default random AI.

Prerequisites

1. Google AI API Key: You need access to Google's Gemini API

   • Get an API key from Google AI Studio
   • The API may require billing setup depending on usage

2. Python Dependencies: Install the required packages

   pip install -r requirements.txt
   

Configuration

Set your API key using one of these methods:

Option 1: Environment Variable (Recommended)

# PowerShell (persistent)
[Environment]::SetEnvironmentVariable("GOOGLE_AI_API_KEY", "your-api-key-here", "User")

# PowerShell (current session only)
$env:GOOGLE_AI_API_KEY = "your-api-key-here"

Option 2: Alternative Environment Variable

$env:GEMINI_API_KEY = "your-api-key-here"

Usage with Gemini AI

Once configured, the Gemini AI agent will automatically be used for Player 2 when the --p2-ai flag is enabled (which is the default):

# Gemini AI will control Player 2 automatically
cli-mon teams/p1.txt teams/p2.txt --format gen7ou

# Support for Random Battles as well
cli-mon --randbat

Features of the Gemini AI Agent

• Strategic Analysis: Evaluates complex battle states including HP, status conditions, type matchups, and team composition
• Advanced Decision Making: Considers win conditions, hazard management, momentum, and endgame scenarios
• Competitive Play Style: Follows high-level competitive Pokemon principles and strategies
• Fallback Safety: Automatically falls back to basic heuristics if API calls fail

Model Configuration

The default model is gemini-2.5-flash-lite for optimal performance and cost. Advanced users can modify the model in gemini_agent.py:

# In gemini_agent.py, modify the init_gemini_agent function
agent = init_gemini_agent(model_name="gemini-2.5-flash")  # More capable but slower/costlier

Available models:

• gemini-2.5-flash-lite (default): Fast, cost-effective
• gemini-2.5-flash: More capable, higher cost
• gemini-2.0-flash-exp: Experimental features

Troubleshooting Gemini Setup

• "No API key found": Ensure your environment variable is set correctly and restart your terminal
• API errors: Check that your API key is valid and you have sufficient quota
• Import errors: Run pip install -r requirements.txt to install dependencies
• Fallback behavior: If Gemini fails, the system automatically uses random decisions with a warning message

Bash (macOS/Linux):

git clone https://github.com/papichoolo/cli-mon-showdown.git
cd cli-mon-showdown

python3 -m venv .venv
source .venv/bin/activate

git clone https://github.com/smogon/pokemon-showdown.git
cd pokemon-showdown && npm ci && cd ..

python3 cli.py teams/p1.txt teams/p2.txt --format gen7ou

Setup Details

• Python: this project uses the standard library plus optional AI dependencies. See requirements.txt for AI agent dependencies.
• Node: used to run the Showdown simulator and its CLI utilities (simulate-battle, pack-team, validate-team, generate-team).
• Showdown path: by default the code looks for pokemon-showdown/pokemon-showdown. Keep the folder at the project root or adjust the code if you move it.

CLI Usage

Basic:

cli-mon <p1_team> <p2_team> [--format FORMAT] [flags]

Random battle (no team files required):

cli-mon --randbat --format gen7randombattle

Flags

• p1: path to Player 1 team file (Showdown importable).
• p2: path to Player 2 team file.
• --format FORMAT: Showdown format id. Default: gen7ou. Examples: gen7ou, gen9ou, gen7randombattle.
• --randbat: generate random teams for both players (ignores p1/p2 positional args).
• --no-auto-preview: disable automatic team preview ordering; you’ll be prompted to choose.
• --side {p1|p2}: which side unprefixed commands control. Default: p1.
• --p2-ai / --no-p2-ai: enable/disable AI for Player 2. When enabled with Gemini configured, uses Gemini AI agent. Default: enabled.
• --humanize / --raw: show a summarized human-readable feed (default) or raw Showdown log lines.
• --window / --no-window: render a minimal in-terminal game window (default) or print plain text only.
• --debug: print additional debug information.

Examples:

# Gen 7 OU with built teams
cli-mon teams/p1.txt teams/p2.txt --format gen7ou

# Random battle using Showdown’s generator
cli-mon --randbat --format gen7randombattle

# Control p2 manually and show raw stream
cli-mon teams/p1.txt teams/p2.txt --side p2 --no-p2-ai --raw

# Disable the windowed UI and team auto-preview
cli-mon teams/p1.txt teams/p2.txt --no-window --no-auto-preview

# Play against Gemini AI with debug information
cli-mon teams/p1.txt teams/p2.txt --format gen9ou --debug --p2-ai

Teams

Team files should be in Pokémon Showdown’s import/export text format, for example:

Charizard @ Life Orb
Ability: Solar Power
EVs: 252 SpA / 4 SpD / 252 Spe
Timid Nature
- Solar Beam
- Fire Blast
- Air Slash
- Hidden Power Ice

When you run the CLI, your teams are packed and validated via Showdown’s CLI (pack-team and validate-team). If validation fails, the error output from Showdown is shown.

Troubleshooting

• “node: not found” or “file not found”: ensure Node.js is installed and node is on your PATH.
• Pokémon Showdown not found: confirm the folder exists at pokemon-showdown/ and run npm ci inside it.
• Validation errors: check that your team is legal in the chosen --format.
• Terminal window not rendering: some terminals may not support the UI; try --no-window.

---

Created by papichoolo. Uses the official Pokémon Showdown simulator.

Packaging and Release

Local build

python -m pip install --upgrade build twine
python -m build

Artifacts will land in dist/. Install one with pip install dist/cli_mon_showdown-<version>-py3-none-any.whl.

TestPyPI dry run

python -m twine upload --repository testpypi dist/*
python -m pip install --index-url https://test.pypi.org/simple/ cli-mon-showdown

Production release

1. Bump the version in pyproject.toml.
2. Tag the commit (git tag v0.1.1 && git push origin v0.1.1).
3. Upload with python -m twine upload dist/* or trigger the GitHub Action described below.

GitHub Actions automation

Store a PyPI token as the PYPI_API_TOKEN repository secret (optionally scope it with an environment named pypi). The workflow in .github/workflows/publish.yml publishes whenever a tag that looks like v* is pushed.