Quick Start¶

Get PokéDex Scanner running in under five minutes.

Prerequisites¶

Node.js 20.19.0 or later (22.x recommended)
npm 10 or later
A GitHub Personal Access Token (no extra scopes needed) — or an API key from another supported AI provider

1. Clone and install¶

git clone https://github.com/pacorreia/pokemon-card-scanner.git
cd pokemon-card-scanner
npm install

2. Set your AI provider¶

# GitHub Models (default) — no extra scopes needed
export AI_PROVIDER=github
export GITHUB_MODELS_TOKEN="ghp_..."

See AI Providers if you want to use OpenAI, Groq, Ollama, or another backend instead.

3. Start the app¶

npm run dev:full

This starts both the Node.js API server (port 8787) and the Vite dev server (port 5173) in a single command.

Open http://localhost:5173 in your browser.

Run servers separately

If you prefer separate terminals:

# Terminal 1 — API server
npm run dev:server

# Terminal 2 — Frontend
npm run dev

4. Download the card database¶

On first launch the app will display a banner asking you to download the Pokémon TCG database. Click Download and wait for it to complete (the app downloads the latest dataset files directly, and the total size may vary by release). This only needs to be done once per data directory.

5. Scan your first card¶

Click Scan Card (camera icon).
Allow camera access when prompted (or click Upload Image to use a file instead).
Point your camera at a Pokémon card and capture the image.
The AI will identify the card — confirm or adjust the result.
The card is added to your collection. 🎉

Next Steps¶

Installation — full setup options including Docker
AI Providers — switch to a different AI backend
Environment Variables — full reference for all env vars