gmfind 0.1.0

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

gmfind

A Python CLI tool for finding and purchasing Steam games. Check deals, view compatibility ratings, and manage your library from the terminal.

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.

Requirements

• Python 3.10+
• uv package manager
• Steam account with Steam Wallet funds (for purchases)

Installation

# Clone and install
git clone https://github.com/your-username/steam-bot.git
cd steam-bot
uv pip install -e .

# Initialize (installs Playwright browsers and creates config templates)
gmfind init

Configuration

Set your Steam credentials as environment variables:

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

Or create a .env file in your working directory (for development).

Config Files

Config files are stored in platform-specific locations:

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

Files:

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

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
gmfind buy 1145350 --force    # Skip validation checks
gmfind buy 1145350 --headful  # Show browser window
gmfind buy --auto             # Autonomous: 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"

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

Project Structure

steam-bot/
├── pyproject.toml              # Package configuration
├── src/gmfind/                 # Package source
│   ├── cli.py                  # CLI entry point (subcommands)
│   ├── config.py               # Configuration loading (Pydantic)
│   ├── paths.py                # XDG-compliant path handling
│   ├── steam_auth.py           # Headless authentication
│   ├── buy_game.py             # Purchase flow
│   ├── check_balance.py        # Wallet balance
│   ├── game_check.py           # Game details aggregator
│   ├── find_deals.py           # Deal discovery
│   ├── report_generator.py     # Markdown report output
│   ├── blocklist_checker.py    # Title filtering
│   ├── inventory.py            # API-based library export
│   ├── inventory_private.py    # Browser-based library export
│   └── recommendations/        # Rating clients
│       ├── protondb.py
│       ├── steam_deck.py
│       └── metacritic.py

Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Run checks
uv run ruff check .         # Lint
uv run ruff format .        # Format
uv run mypy src/gmfind      # Type check

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.

License

MIT License - see LICENSE for details.