itch-rewards
Commandline tool to update game rewards on Itch.io, and automatically update reward counts and descriptions based on sales.
Installation
$ gem install itch_rewards
Usage
Usage: itch-rewards COMMAND [options]
Commands:
itch-rewards list # List all rewards for a game
itch-rewards list-games # List all games
itch-rewards recalculate # Update reward quantity and description from configuration file
itch-rewards setup # Save cookies for itch.io and create reward config example file
itch-rewards update GAME_ID REWARD_ID # Update a reward
itch-rewards version # Print version
Authenticating
First, enable two-factor authentication for your itch.io account, if you haven't already. This prevents captcha prompts during login, which itch-rewards doesn't handle.
Then, run:
$ itch-rewards setup
You'll be prompted for your username, password, two-factor code, and a path to save a cookie file. Your credentials will not be saved, but the cookie will be used for subsequent logins (until the cookie expires).
You can use itch-rewards for multiple accounts by specifying a different cookie file path for each account:
$ itch-rewards setup --cookie-path my_first_account.yml
# ...
$ itch-rewards setup --cookie-path my_second_account.yml
# ...
$ itch-rewards list-games --cookie-path my_first_account.yml
You'll also be prompted to create an (optional) configuration file that can be used when automatically updating itch reward quantities and descriptions.
While logging in via cookies is easier (and required for non-interactive login, ex: for cron tasks), all commands also accept the following options.
--username=VALUE, -u VALUE # Itch username
--password=VALUE, -p VALUE # Itch password
--cookie-path=VALUE # Path to cookies file for future logins, default: ".itch-cookies.yml"
--[no-]cookies # Enable cookie storage, default: true
--[no-]interactive # Enable interactive prompts, default: true
--help, -h # Print help
List games
Return a list of game names and IDs. Useful for other commands that use game ID, or when creating a reward configuration file.
Usage:
itch-rewards list-games
Description:
List all games
List rewards
Show reward information for a single game.
Accepts either a game name, or game ID.
Usage:
itch-rewards list
Description:
List all rewards for a game
Options:
--id=VALUE # Game ID
--name=VALUE # Game name
Examples:
itch-rewards list --id 123456 # List rewards for game with ID 123456
itch-rewards list --name MyGame # List rewards for game with name MyGame
Update a reward
Update a single reward for a game. Quantity, title, description, price and archive status can be changed.
Command:
itch-rewards update
Usage:
itch-rewards update GAME_ID REWARD_ID
Description:
Update a reward
Arguments:
GAME_ID # REQUIRED Game with the reward to edit
REWARD_ID # REQUIRED Reward ID to update
Options:
--quantity=VALUE # Reward quantity (total, including redeemed)
--title=VALUE # Reward title
--[no-]archived # Reward archived status
--description=VALUE # Reward description
--price=VALUE # Reward price without currency (ex: 15.99)
Examples:
itch-rewards update 123456 78910 --quantity 5 # Set the reward count to 5 for reward ID 78910 in game ID 123456
itch-rewards update 123456 78910 --price 5.00 --archived # Set reward price to 5.00 and archive it
Automated reward updates
If you wish to update a reward description, or available quantity based on purchases or tips.
Usage:
itch-rewards recalculate
Description:
Update reward quantity and description from configuration file
Options:
--config=VALUE # Path to config file, default: "itch-reward-config.yml"
--[no-]save # Saves changes when enabled. Otherwise, dry-run and show result, default: false
Reward configuration
Automatic reward updates require a reward configuration file. You can create an annotated file, prepopulated with all of your itch games by using the setup command.
A reward configuration looks like this
---
games:
MyGame:
id: 123456
reward_id: 789012
reward_by_purchase: 0
reward_by_tip: 0.0
reward_offset: 0
minimum_available: 0
reward_description_template:
MyOtherGame:
...
Some example reward scenarios
I want every purchase to add one community copy
MyGame:
id: 123456
reward_id: 789012
reward_by_purchase: 1
reward_by_tip: 0.0
reward_offset: 0
minimum_available: 0
I want every two purchases to add one community copy
MyGame: id: 123456 reward_id: 789012 reward_by_purchase: 0.5 reward_by_tip: 0.0 reward_offset: 0 minimum_available: 0I want tips over the purchase price to add proportional community copies
MyGame:
id: 123456
reward_id: 789012
reward_by_purchase: 0
reward_by_tip: 1.0
reward_offset: 0
minimum_available: 0
For example: a $5 tip, on a $10 game will contribute 0.5 copies to the reward pool when reward_by_tip is 1.
The formula for this is: (tip_amount / game_price) * reward_by_tip
I want five community copies to always be available
MyGame:
id: 123456
reward_id: 789012
reward_by_purchase: 0
reward_by_tip: 0.0
reward_offset: 0
minimum_available: 5
Updating reward description
If present, the reward_description_template configuration value can be used to change the description of your reward with information about the reward itself.
For instance:
reward_description_template: <p>Rewards added: { amount }</p>
The above will change the reward description to "Rewards added: 10". The following placehoder values are available:
{ amount }: The total number of reward copies in the pool, including redeemed rewards.{ remaining_percent }: A number between 0.0 and 100.0, indicating the percentage until the next reward{ remaining_percent_integer }: A number between 0 and 100. As above (but with no decimal value included).