🎮 scratch-io

scratch-io is a command-line tool for managing, downloading, and launching games from itch.io.

✨ Features

• 🔑 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

⚡ Build

Requires Rust and cargo:

git clone https://github.com/Vidi0/scratch-io.git
cd scratch-io
cargo build --release

The binary will be placed in target/release/scratch-io.

🚀 Usage

Authenticate with your itch.io API key:

scratch-io auth YOUR_API_KEY

Alternatively, log in using your username and password:

scratch-io login USERNAME PASSWORD

Download a game by its upload ID:

scratch-io download 123456

List installed games:

scratch-io installed

Launch an installed game:

scratch-io launch 123456 GAME_PLATFORM

See all options with:

scratch-io help

[!WARNING] Due to how the itch.io API works, it is not possible to update a game in-place.
To update a game, 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.

🛠️ Environment variables

• SCRATCH_API_KEY: itch.io API key
• SCRATCH_CONFIG_FILE: Custom path for the configuration file

📚 References

• itchapi.ryhn.link – Unofficial itch.io API documentation
• itch-downloader – Example itch.io API usage
• itch.io docs: compatibility policy
• itch.io docs: manifest
• itch.io docs: butler

📝 Roadmap

• 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.

📝 TODO

• Read and use the itch.io manifest
  • Detect game executable from manifest actions
  • Handle game prerequisites from manifest
• Report game playtime to the itch.io servers
• Support updating and verifying games packed with butler

📝 License

The code in this repository is released under the GPL-3.0-or-later license.
This project uses many third-party crates; their licenses are listed in LICENSE-THIRD-PARTY.html.