scratch-io

Crates.io	scratch-io
lib.rs	scratch-io
version	0.1.4
created_at	2025-09-03 21:21:08.884241+00
updated_at	2025-12-21 17:58:16.657308+00
description	A rust library for managing, downloading, and launching games from itch.io
homepage
repository	https://github.com/Vidi0/scratch-io
max_upload_size
id	1823288
size	222,381

Vidi (Vidi0)

documentation

README

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

🔍 Getting a game's ID

You can find an itch.io game's ID in two ways:

Append /data.json to the itch.io game page's URL in your browser. The ID will be in the id field of the JSON response.
Look for a <meta> tag inside the <head> section of the game page's HTML source:
```
<head>
  <meta name="itch:path" content="games/123456">
  ...
</head>
```
The number after games/ is the game ID.

🚀 Usage

Authenticate with your itch.io API key:

scratch-io auth API_KEY

Alternatively, log in using your username and password:

scratch-io login --username USERNAME --password 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 --platform 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.io docs: compatibility policy
itch.io docs: manifest
itch.io docs: butler
itch.io docs: wharf

📝 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
  
  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

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

Commit count: 175