🇺🇸 English · 🇧🇷 Português

HOWL

Hoard Optimizer, What to Launch

Ranks your Steam library by quality × time invested using data from HowLongToBeat, Metacritic and Steam Reviews. No more decision paralysis staring at your backlog.

Requirements

• Python 3.11+
• Steam API Key (free, instructions below)
• Steam account with public profile and library (or private, using your own key)

Installation

pip install howl-steam-backlog

Or with pipx (recommended for CLI tools — isolated environment):

pipx install howl-steam-backlog

For development:

git clone https://github.com/albertosca/howl.git
cd howl
uv sync --extra dev               # resolves from uv.lock into .venv
uv run --extra dev pytest         # run the suite

Dependencies are pinned in uv.lock, so uv sync reproduces the exact versions the tests were last green against. pip install -e ".[dev]" in a plain venv still works and is what CI does, but it resolves fresh and ignores the lock.

After installing, the howl command becomes available:

howl --help

Configuration

Quick way: howl --setup

howl --setup

The interactive wizard walks you through the required variables, validates them live against the Steam API, and writes them to ~/.config/howl/.env (loaded automatically, created with 0600 permissions). If you still have a legacy .env in the current directory, it offers to migrate it.

Manual way: environment variables

STEAM_API_KEY:

1. Go to https://steamcommunity.com/dev/apikey
2. Log in with your Steam account
3. Fill "Domain Name" with any value (e.g. localhost)
4. Copy the generated key

STEAM_USERNAME: The vanity URL of your Steam profile: steamcommunity.com/id/gabelogannewell → username is gabelogannewell

IGDB_CLIENT_ID and IGDB_CLIENT_SECRET (optional): IGDB complements Metacritic for games where Steam returns no score (delisted, very old, etc.).

1. Go to https://dev.twitch.tv/console and log in with your Twitch account (create one if needed — it's free)
2. Click Register Your Application
3. Fill in:
   • Name: anything (e.g. howl-igdb)
   • OAuth Redirect URLs: http://localhost
   • Category: Website Integration
4. Click Create
5. In the app list, click Manage
6. Copy the Client ID
7. Click New Secret and copy the Client Secret (shown only once)

With the credentials configured, run:

howl --migrate-igdb

The OAuth token is generated and refreshed automatically. You don't need to repeat this process.

STEAM_VDF_PATH (optional): Required to use --collection and automatic exclusion of finished games.

The <steamid> is numeric (different from the vanity URL). Find it in: Steam → Settings → Account → Steam account ID.

Credentials live in ~/.config/howl/.env (respects $XDG_CONFIG_HOME). The wizard writes this file for you; to set it up by hand, create it with one KEY=value per line:

# ~/.config/howl/.env
STEAM_API_KEY=your_key_here
STEAM_USERNAME=your_username
# STEAM_VDF_PATH is optional (collection filters)
STEAM_VDF_PATH=/path/to/sharedconfig.vdf

Prefer this over exporting the keys in your shell profile (~/.zshenv, ~/.bashrc): shell exports leak the values to every process on your system.

Language

howl speaks English and Brazilian Portuguese. howl --setup asks which one you want and stores the answer in ~/.config/howl/.env.

To override it for a single run:

howl --lang pt-BR

Resolution order, highest first: --lang → HOWL_LANG environment variable → HOWL_LANG in ~/.config/howl/.env → your operating system locale → English.

Usage

# First run: populates the cache (may take ~5 min for 300 games)
howl --username my_steam_id --verbose

# Top 10 good and short games (default)
howl --username my_steam_id

# Interactive visual interface
howl --username my_steam_id --tui

# Filter by genre, progress and formula
howl --username my_steam_id --genre "action,rpg" --not-started --sort quick-wins

# Filter by release era
howl --username my_steam_id --era "2010-2015,2015-2020"

# See what's available in the cache
howl --list-genres
howl --list-tags
howl --list-collections

With STEAM_USERNAME set in the environment, --username can be omitted.

Sort formulas (--sort)

composite = weighted average of Metacritic and Steam reviews (tune with --weight-mc / --weight-steam).

Games without Metacritic or Steam reviews get zero weight on that source (the other takes 100%).

Available filters

TUI (visual interface)

howl --username my_steam_id --tui

The filter panel applies all changes in real time.

Cache

HLTB, Steam Reviews and game detail data are cached in games_cache.json to avoid repeated requests. To update:

# Re-fetch everything from scratch
howl --username my_steam_id --refresh

# Fill missing fields in old entries (genres, release_year)
howl --migrate-cache

# Fetch IGDB scores for games without Metacritic (requires IGDB_CLIENT_ID and IGDB_CLIENT_SECRET)
howl --migrate-igdb

--migrate-cache is useful if you had a cache from earlier versions that didn't have all fields.

--migrate-igdb fills critic scores via IGDB for games where Steam returns no Metacritic — especially useful for delisted games (e.g. the original Deus Ex: Human Revolution). It can be re-run at any time; games that already have IGDB data in the cache are skipped.

Troubleshooting

"Username not found on Steam" Check that the vanity URL is correct. Visit https://steamcommunity.com/id/your_id/ — if it redirects to your profile, it's right.

Games without Metacritic or Steam reviews Normal — not all games have data. They still show up but with score 0 in some formulas. Use --sort loved or --sort rated to see only games with data.

"0 entries to migrate" The cache is already complete. If you just built the cache with howl --verbose, all games already come with every field.

Cache with few games If the Steam library is set to private, the API returns 0 games. Go to Steam → Profile → Edit → set games to public (you can switch back to private afterwards).

Development

pytest                          # run all tests
pytest tests/test_score.py -v   # specific module