Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tldrwtf/pokedo/llms.txt

Use this file to discover all available pages before exploring further.

The PokeDo multiplayer server is a FastAPI application backed by PostgreSQL. It handles JWT-based authentication, battle state, turn resolution, ELO updates, and leaderboard queries. You need it running before any pokedo battle or pokedo leaderboard commands will work. Single-player features are unaffected and continue using the local SQLite database. Docker Compose is the fastest way to get both PostgreSQL and the PokeDo server running together.
1

Clone the repository

git clone https://github.com/tldrwtf/pokedo.git
cd pokedo
2

Start the server and database

docker-compose up -d
This starts both the PostgreSQL container and the PokeDo server. The server listens on port 8000 by default.
3

Verify the server is healthy

curl http://localhost:8000/health
You should receive {"status":"ok"}.
4

Register your account

pokedo battle register -u myname -p mypass
This creates your account on the server and links it to your local trainer profile.

​
Manual setup

If you prefer to manage PostgreSQL separately, you can run the server directly with uvicorn. 
# Install with development dependencies
pip install -e ".[dev]"

# Start PostgreSQL separately, then start the server
uvicorn pokedo.server:app --reload --port 8000
The server uses the lifespan context manager to initialize database tables on startup — no separate migration step is required.

​
Environment variables

VariableDefaultDescription
POKEDO_DATABASE_URLpostgresql://pokedo:pokedopass@localhost:5432/pokedoPostgreSQL connection URL
POKEDO_SECRET_KEYyour-secret-key-keep-it-secretJWT signing secret
POKEDO_SERVER_URLhttp://localhost:8000Server URL used by the CLI client
Set these in your shell or in a .env file before starting the server. The CLI reads POKEDO_SERVER_URL to know where to send requests, so set it on each machine running the CLI if your server is not on localhost.
Change POKEDO_SECRET_KEY before deploying to a shared or public environment. Any JWT token signed with the default key will be accepted by any other PokeDo server also using the default key.

​
After the server is up

Register an account, then challenge another trainer to start your first battle: 
# Register
pokedo battle register -u myname -p mypass

# Challenge another registered trainer
pokedo battle challenge opponent -u myname -p mypass
See the battles guide for the full turn-by-turn flow.

Build docs developers (and LLMs) love

Get started for freeTalk to us