scratch-io is a command-line tool for managing, downloading, and launching games from itch.io.
- 🔑 Authentication with the itch.io API
- 📥 Game download with automatic extraction (zip, tar.gz, tar.xz, ...)
- 🗃️ Management of installed games (list, move, delete, import)
- 🚀 Game launch with smart heuristics to find the correct executable
- 🗂️ Support for collections and game keys
- 🖼️ Automatic cover art download
Requires Rust and cargo:
git clone https://github.com/Vidi0/scratch-io.git
cd scratch-io
cargo build --releaseThe binary will be placed in target/release/scratch-io.
You can find an itch.io game's ID in two ways:
- Append
/data.jsonto the itch.io game page's URL in your browser. The ID will be in theidfield of the JSON response. - Look for a
<meta>tag inside the<head>section of the game page's HTML source:The number after<head> <meta name="itch:path" content="games/123456"> ... </head>
games/is the game ID.
Authenticate with your itch.io API key:
scratch-io auth API_KEYDownload a game by its upload ID:
scratch-io download 123456List installed games:
scratch-io installedLaunch an installed game:
scratch-io launch 123456 --platform GAME_PLATFORMSee all options with:
scratch-io helpWarning
Due to how the itch.io API works, it is not possible to update a game in-place unless it has been packaged using butler.
To update a game that has not been packaged this way, you must remove it and install it again.
Note
Launching games is determined by heuristics, so it may not always work for every game.
If the executable for a game is not detected correctly, please leave an issue in the repository describing your case.
SCRATCH_API_KEY: itch.io API keySCRATCH_CONFIG_FILE: Custom path for the configuration file
- itchapi.ryhn.link – Unofficial itch.io API documentation
- itch.io docs: compatibility policy
- itch.io docs: manifest
- itch.io docs: butler
- itch.io docs: wharf
- Integration with Heroic Games Launcher:
This project was designed with the intention of being integrated into Heroic Games Launcher.
Note: Integration is not currently implemented.
- Read and use the itch.io manifest
- Detect game executable from manifest actions
- Handle game prerequisites from manifest
Note: Prerequisites are read from the manifest, but they must be handled and installed by the user
- Report game playtime to the itch.io servers
- Support updating and verifying games packed with butler
The code in this repository is released under the GPL-3.0-or-later license.
The protobuf definitions in the .proto files located in the wharf/src/protos directory were obtained from the wharf GitHub repository, so they are licensed by itch.io under the MIT license, which can be found in the LICENSE file in wharf/src/protos/LICENSE.
This project uses many third-party crates; their licenses are listed in LICENSE-THIRD-PARTY.html.
