gmfind 0.1.14

Steam automation CLI - find games, check deals, purchase, and manage your Steam library

gmfind: Game Finder

A Python CLI tool for recommendations and purchasing of PC games. Steam is the store front that is primarily supported.

gmfind will look for high quality games based on your configurable preferences for steam and metacritic ratings, discounts and compatibility ratings.

Features

• Game Discovery: Find discounted games filtered by price, Metacritic score, ProtonDB rating, and Steam Deck compatibility.
• Compatibility Checks: Get ProtonDB and Steam Deck verification status for any game.
• Smart Filtering: Exclude games you already own, match blocklist patterns, and enforce preference criteria.
• Headless Purchasing: Buy games using your Steam Wallet with Playwright browser automation.
• Private Profile Support: Export your game library even with a private Steam profile.

Safety Notice

Purchases use Steam Wallet only. This tool will never use credit cards, PayPal, or any external payment methods. All purchases are made exclusively from your Steam Wallet balance.

• Validation: The gmfind buy <APP_ID> command validates games against your price preferences, inventory, and blocklist before proceeding.
• Autonomous Buying: The gmfind rec-buy-auto command is fully autonomous—it will check your balance, find a suitable recommendation, and purchase it without user intervention.
• Auto-Confirm: Using the --auto flag with the buy command skips the final confirmation prompt.
• Spending Caps: Your Steam Wallet balance acts as a natural spending cap. We strongly recommend setting a conservative max_price in your config.yaml.

We recommend testing with --headful mode first to observe the purchase flow before enabling autonomous buying.

Installation

Homebrew (macOS/Linux)

brew tap automoto/gmfind
brew install gmfind

# Install browser binaries (required for browser commands)
$(brew --prefix gmfind)/libexec/bin/python -m playwright install chromium

uv

uv tool install gmfind
playwright install chromium

pip / pipx

# With pip
pip install gmfind
playwright install chromium

# With pipx
pipx install gmfind
playwright install chromium

Verify Installation

gmfind --version
gmfind init  # creates default config files

For Developers

See Development section below.

Configuration

Set your Steam credentials as environment variables:

export STEAM_USERNAME="your_username"
export STEAM_PASSWORD="your_password"
export STEAM_ID="76561198xxxxxxxxx"

Add these to your shell profile (~/.zshrc or ~/.bashrc) to make them permanent.

Config Files

Config files are stored in platform-specific locations:

• Linux/macOS: ~/.config/gmfind/
• Windows: %APPDATA%\gmfind\

Files:

• config.yaml - Preferences (max price, min ratings, etc.)
• block_list.yaml - Game title patterns to exclude

Command Reference

Commands are divided into two categories:

API Commands

These work immediately after installation:

Command	Description
gmfind check <APP_ID>	Get game details (price, ratings, compatibility)
gmfind deals [N]	Find N discounted games matching your preferences
gmfind id "<TITLE>"	Look up a game's Steam App ID
gmfind blocklist "<TITLE>"	Check if a title matches your blocklist
gmfind inventory --public	Export game library (requires public Steam profile)

Browser Commands

These require browser binaries (playwright install chromium):

Command	Description
gmfind buy <APP_ID>	Purchase a game using Steam Wallet
gmfind balance	Check your Steam Wallet balance
gmfind inventory --private	Export game library (works with private profiles)
gmfind rec-buy-auto	Autonomous recommend and purchase workflow

Usage

Check Game Details

Get comprehensive info including price, ProtonDB rating, Steam Deck status, and reviews:

gmfind check 1145350

Find Deals

Find discounted games matching your preferences:

gmfind deals           # Find 10 deals
gmfind deals 5         # Find 5 deals
gmfind deals --output ./deals.md   # Save to file

Purchase a Game

Buy a game by App ID (validates against your config first):

gmfind buy 1145350            # Buy specific game (shows confirmation prompt)
gmfind buy 1145350 --auto     # Skip confirmation prompt
gmfind buy 1145350 --headful  # Show browser window

Autonomous Buy

Automatically find a recommended game and purchase it:

gmfind rec-buy-auto           # Check balance -> recommend -> buy

Check Wallet Balance

gmfind balance

Export Game Library

gmfind inventory --private    # Browser-based (works with private profiles)
gmfind inventory --public     # API-based (requires public profile)

Check Blocklist

gmfind blocklist "FIFA 24"

Find Steam App ID

Look up a game's Steam App ID by title:

gmfind id "Hades"

Output: {"steam_id": 1145360, "title": "Hades"}

Search by Name

Look up a game by title and get full details in one command:

gmfind id "Hades II" | jq '.steam_id' | xargs gmfind check

Global Options

gmfind --version     # Show version
gmfind --verbose     # Enable debug logging
gmfind <cmd> --help  # Command-specific help

Per-Command Options

Most commands accept config overrides:

gmfind deals 5 --config ./config.yaml --block-list ./blocklist.yaml
gmfind check 1145350 --inventory ./my_games.csv

Development

Setup

# Clone the repository
git clone https://github.com/your-username/gmfind.git
cd gmfind

# Install in development mode with dev dependencies
make install

# Initialize Playwright browsers
make init

Running Locally

# Run commands through uv
uv run gmfind --help
uv run gmfind check 1145350

# Or activate the virtual environment
source .venv/bin/activate
gmfind --help

Code Quality

make lint        # Run ruff linter
make format      # Format code with ruff
make type-check  # Run mypy type checker
make check       # Run all checks

Building

# Install build tools
uv pip install build twine

# Build the package
uv run python -m build

# This creates:
#   dist/gmfind-0.1.0.tar.gz
#   dist/gmfind-0.1.0-py3-none-any.whl

Testing Locally Before Publishing

# Create a test environment
uv venv /tmp/test-gmfind
source /tmp/test-gmfind/bin/activate

# Install your local build
pip install dist/gmfind-*.whl

# Test it
gmfind --version
gmfind check 1145350

# Clean up
deactivate
rm -rf /tmp/test-gmfind

Publishing

# Upload to TestPyPI first
uv run twine upload --repository testpypi dist/*

# Then upload to PyPI
uv run twine upload --repository pypi dist/*

Versioning

Update version in src/gmfind/__init__.py before releasing:

__version__ = "0.2.0"

Then rebuild and publish.

Security

• Credentials are read from environment variables, never stored in config files.
• Session data is stored locally in XDG data directory.
• Browser automation uses real Chromium with human-like behavior.

Troubleshooting

When errors occur during login or purchase, screenshots are automatically saved for debugging.

File locations (platform-specific):

• Linux/macOS: ~/.cache/gmfind/
• Windows: %LOCALAPPDATA%\gmfind\Cache\

Troubleshooting files:

• screenshots/ - Error screenshots (e.g., login_failed.png, purchase_failed.png)
• logs/gmfind.log - Application logs

Common issues:

• Login fails: Check screenshots/login_*.png for the browser state at failure
• Purchase fails: Check screenshots/purchase_failed.png or checkout_failed.png
• Run with --headful flag to watch the browser in real-time