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: 0

I 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).

itch_rewards

Runtime