pkmn translates complete Pokémon Red and Blue save journeys into Pokémon
FireRed or LeafGreen. It carries forward supported Pokémon, identity, Pokédex,
inventory, badges, trainers, story progression, world state, and other save
semantics instead of moving only individual Pokémon.
The version 3.1 release packages are self-contained. Ordinary Windows, macOS, and Linux users do not need Python, CMake, Git, a compiler, the earlier Save Genie projects, or a separately downloaded template.
Download the package for your computer from GitHub Releases:
| Platform | Package | Beginner entry point |
|---|---|---|
| Windows x86-64 | installer or portable ZIP | Start Menu shortcut or pkmn-interactive.cmd |
| macOS Apple Silicon | arm64 package/archive | pkmn-interactive.command or pkmn interactive |
| macOS Intel | x86-64 package/archive | pkmn-interactive.command or pkmn interactive |
| Linux x86-64 | AppImage, .deb, or archive |
application launcher or pkmn interactive |
After installation, open a terminal and run:
pkmn interactiveGuided mode opens a task menu for conversion, save inspection, JSON, editing,
comparison, proof, and general tools. New users can follow the
complete interactive player's manual.
Its searchable command browser covers
the 124 current catalog endpoints, with typed questions and advanced options
for each runnable command. Type ? for help, B to go back, or Q to quit.
Paths with spaces can be pasted as one answer. File-writing tasks show a review
and require confirmation; they call the same handlers as direct commands.
Future roadmap commands remain unavailable until implemented.
Verify any installation with:
pkmn --version
pkmn doctor --deepThe doctor should report Runtime mode: bundled-private-executable for a
downloaded release. See the zero-to-conversion installation guide
if you have never used a command-line program before.
The four explicit routes are:
pkmn convert red-firered game.sav
pkmn convert red-leafgreen game.sav
pkmn convert blue-firered game.sav
pkmn convert blue-leafgreen game.savConvenience commands choose the paired remake by default:
pkmn red convert game.sav # Red -> FireRed; writes game_fr.sav
pkmn blue convert game.sav # Blue -> LeafGreen; writes game_lg.savChoose the other remake explicitly:
pkmn convert red-leafgreen game.sav
pkmn blue convert game.sav --target fireredIf only the Generation I checksum bytes are damaged, repair a temporary in-memory copy during conversion:
pkmn red convert game.sav --auto-repair-checksumThe original file is never modified. Add
--write-repaired-source repaired-game.sav only if you also want a separate
repaired Gen I copy. Every conversion writes an auditable manifest and readable
report beside the target save.
pkmn labels each route according to the evidence actually completed:
| Route | Status |
|---|---|
| Red → FireRed | EMULATOR_VERIFIED — MAQ Phase 5 and Phase 6 acceptance passed |
| Red → LeafGreen | STATICALLY_VALIDATED_COMMUNITY_TESTING |
| Blue → FireRed | STATICALLY_VALIDATED_COMMUNITY_TESTING |
| Blue → LeafGreen | STATICALLY_VALIDATED_COMMUNITY_TESTING |
Static validation is not described as emulator proof. The three new routes use the shared, regression-tested engines and explicit version overlays, but they remain open to community testing. Report reproducible problems through GitHub Issues; never upload a ROM or a private save.
| Domain | Treatment |
|---|---|
| Identity | Player/rival names, public Trainer ID, money, coins, play time, options, and supported target identity |
| Pokémon | Party, PC, Daycare, species, experience, moves, PP, names, OT, DVs/IVs, stat experience/EVs, PID, nature, ability, gender, friendship, origin, and shiny policy |
| Pokédex | Seen/owned state and required target mirrors |
| Trainers | All saved Red trainer events classified; accepted remake counterparts receive translated defeat state |
| Story | Supported starter, rival, Gym, Rocket, ship, tower, Silph, Safari, Cinnabar, League, and Kanto milestone bundles |
| Inventory | Items, Key Items, Balls, TMs/HMs, obtained history, pocket rules, and capacity policy |
| World | Supported blockers, objects, field permissions, transportation, and Fly destinations derived from source visit history |
| Remake-only content | Safe defaults, explicit policy, or omission; unsupported postgame progress is never invented |
The bridge is semantic. Raw event numbers, trainer IDs, item IDs, and physical offsets are never copied between generations.
Gen I .sav
→ canonical source JSON
→ semantic source state
→ evidence-backed bridge policy
→ deterministic Pokémon conversion
→ target semantic JSON
→ target sector generator
→ validated Gen III .sav + manifest + report
Japanese Green 1.0 now has an experimental route:
pkmn green-jp convert game-jp.sav --profile JP_GREEN_REV0.
It is also source choice 4 in simple interactive conversion. It currently
targets FireRed only. See the Green implementation and limits.
An experimental Japanese Red route is available with an explicit revision:
pkmn red-jp convert game-jp.sav --profile JP_RED_REV0. It archives the
Japanese source, projects an English-shaped bridge JSON with original name
provenance, and writes an international FireRed save with Japanese Pokémon
nicknames where encodable. This route has synthetic round-trip tests but not
real-save or emulator acceptance; keep the original save and review the
Japanese bridge limitations before use.
The optional --retain-playername flag writes the source Japanese player name
into the international FireRed identity field as an experimental byte-preserving
choice. Its in-game font display has not been verified.
Canonical JSON remains inspectable and migratable:
pkmn red decode game.sav
pkmn blue decode game.sav
pkmn fred decode game_fr.sav
pkmn leafgreen decode game_lg.sav
pkmn rjson convert_to_frjson game.red.json
pkmn rjson convert game.red.json
pkmn bjson convert game.blue.json
pkmn rjson update_schema game.red.json
pkmn bjson update_schema game.blue.json
pkmn frjson update_schema game.fred.json
pkmn lgjson update_schema game.lg.jsonGeneration and reconstruction remain separate:
| Mode | Authority |
|---|---|
| Decode | Real source save bytes |
| Generate | Semantic JSON; never hidden physicalImage authority |
| Reconstruct | Archived physicalImage bytes |
| Convert | Source semantics, bridge policy, and safe target template boundary |
| Edit | Validated working copy; source is not overwritten by default |
Physical FireRed/LeafGreen generation needs a structurally valid blank target container. Version 3 includes an identity-checked, clean save template for this purpose. It is not a ROM, contains no progressed personal journey, and is not semantic authority. Users normally never mention it.
Advanced users may provide an equivalent clean dump with
--template clean-save.sav or PKMN_FIRERED_TEMPLATE; strict validation rejects
progressed or unexpected templates.
Discover all 124 current endpoints with:
pkmn --help
pkmn get-all-cmds
pkmn convert routesMain domains are red, red-jp, blue, fred, leafgreen, rjson,
rjpjson, bjson, frjson, lgjson, convert, compare, proof, and
doctor. Existing pkmn
2.0 Red → FireRed commands and accepted behavior remain supported, including
the compatibility spelling pkmn convert red-to-firered.
See:
- installation on Windows, macOS, and Linux;
- complete usage guide;
- all commands;
- future planned commands (roadmap only; not available in the current executable);
- Version 3.0 interactive experience guide;
- interactive examples for every command;
- command reference;
- troubleshooting;
- privacy and publication;
- Japanese Red save research and source citations;
- experimental Japanese archive and bridge schema;
- Japanese fixture and evidence ledger;
- Japanese Red implementation record and acceptance gates;
- Japanese Red implementation and analysis walkthrough;
- pkmn 3.0 implementation record.
Released downloads have no development prerequisites. Contributors building from source need CMake 3.20+, a C++20 compiler, and Python 3 for tests and the developer runtime fallback:
git clone https://github.com/AAAMAQ/pkmn-cli.git
cd pkmn-cli
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
ctest --test-dir build --output-on-failureRelease maintainers additionally use PyInstaller 6.20 to produce the private runtime bundle. The tagged workflow builds Windows x86-64, macOS arm64 and x86-64, and Linux x86-64 packages; it publishes SHA-256 sums, an SPDX SBOM, licenses, and release notes.
- Existing inputs and outputs are never overwritten by default.
- Wrong-size, malformed, wrong-profile, and inconsistent inputs are rejected.
- Ambiguous trainers default to undefeated.
- Remake-only progression is not inferred from Gen I completion.
- Manifests disclose transfers, translations, defaults, omissions, repairs, warnings, and rejection reasons.
- No ROMs, copyrighted game images, private saves, screenshots, credentials, or emulator evidence are distributed.
- Release packages are checked by a privacy scan and accompanied by checksums and an SBOM.
This unified program grew from the Pokémon Red Save Genie, Red Save Generator, FireRed Save Genie, bridge research, and FireRed Save Generator projects. The research pins:
pret/pokered@d70d99ffbd329473d96eaaf19fd97c86d2220b7f;pret/pokefirered@df4449a27cd78dd747ce269e47d3ab4a0149d8f4.Narishma-gb/pokegreen@953f41b34108621b2bf13c3b1e53abfc9c3e5aecfor the experimental Japanese Red SRAM and text layout.
Pokémon conversion uses the Pokémon Community Conversion Standard ORIGINAL
profile as its foundation, with deterministic project policy recorded in each
manifest. StrategyWiki and Zerokid’s guide supplied human-readable
corroboration while pinned pret remained authoritative.
Thanks to the pret community, Striaton Lab Team and PCCS contributors, StrategyWiki contributors, Niels Lohmann and JSON for Modern C++ contributors, the Pokémon and Game Boy communities, everyone who encouraged MAQ’s original idea, and OpenAI Codex as a transparently used research and engineering collaborator.
The project is created and maintained by MAQ / BiG MAQ Studios for educational research, preservation, archival work, and personal save continuity.
MIT License. This independent project is not affiliated with, endorsed by, or sponsored by Nintendo, Game Freak, Creatures, or The Pokémon Company. Pokémon and related trademarks belong to their respective owners. No ROMs are included or required by the CLI.