stools-cli 0.3.1

CLI to extract structured data from Steam (reviews, game search) — designed for LLM agents

stools

CLI tool to extract structured data from Steam. Outputs JSON to stdout, making it easy to pipe into other tools or consume from LLM agents.

Installation

macOS (Homebrew)

brew install pipx
pipx install stools-cli

Other platforms

python3 -m pip install stools-cli

Requires Python 3.9+. No external dependencies.

Commands

stools search

Search Steam for games by name.

stools search <query> [--limit N] [--fields f1,f2,...]

Argument	Description
query	Search term (e.g. megaman, dark souls)
--limit N	Max results to return. Default: 10
--fields	Comma-separated fields to keep per result (e.g. app_id,name)

Output schema

{
  "query": "megaman",
  "total_results": 10,
  "results": [
    {
      "app_id": 742300,
      "name": "Mega Man 11",
      "price": { "currency": "USD", "initial": 2999, "final": 2999 },
      "platforms": { "windows": true, "mac": false, "linux": false },
      "metascore": "80"
    }
  ]
}

Examples

# Search for a game
stools search "megaman"

# Get top 3 results, only app_id and name
stools search "dark souls" --limit 3 --fields app_id,name

# Search then fetch reviews for the first result
APP_ID=$(stools search "snake vs snake" 2>/dev/null | jq '.results[0].app_id')
stools reviews "$APP_ID"

stools reviews

Fetch all reviews for a Steam game.

stools reviews <app_id_or_url> [--language CODE] [--review-type TYPE] [--limit N] [--offset N] [--fields f1,f2,...] [--output FILE]

Argument	Description
app	Steam app ID (1005310) or store URL (https://store.steampowered.com/app/1005310/Snake_vs_Snake/)
--language	Filter by language code: english, spanish, french, german, etc. Default: all
--review-type	Filter by sentiment: all, positive, negative. Default: all
--limit N	Max reviews to return. 0 = all. Default: 0
--offset N	Skip the first N reviews. Use with --limit to paginate. Default: 0
--fields	Comma-separated fields to keep per review (e.g. review,voted_up)
--output FILE	Write JSON to a file instead of stdout

Output schema

{
  "app_id": 1005310,
  "query_summary": {
    "num_reviews": 33,
    "review_score": 7,
    "review_score_desc": "Positive",
    "total_positive": 33,
    "total_negative": 0,
    "total_reviews": 33
  },
  "total_fetched": 33,
  "reviews": [
    {
      "recommendationid": "210668843",
      "author": {
        "steamid": "76561198079866033",
        "personaname": "username",
        "num_reviews": 32,
        "playtime_forever": 1554,
        "playtime_at_review": 1554
      },
      "language": "english",
      "review": "Review text here.",
      "timestamp_created": 1764106395,
      "timestamp_updated": 1764106395,
      "voted_up": true,
      "votes_up": 0,
      "votes_funny": 0,
      "steam_purchase": true,
      "received_for_free": false,
      "written_during_early_access": false
    }
  ]
}

Examples

# Fetch all reviews for a game
stools reviews 1005310

# Fetch only English reviews, save to file
stools reviews 1005310 --language english --output reviews.json

# Fetch first 10 reviews
stools reviews 1005310 --limit 10

# Paginate through reviews
stools reviews 730 --limit 50
stools reviews 730 --limit 50 --offset 50

# Get only negative reviews
stools reviews 730 --review-type negative --fields review,voted_up

# Use a full Steam URL
stools reviews "https://store.steampowered.com/app/1005310/Snake_vs_Snake/"

# Get only review text and sentiment
stools reviews 1005310 --fields review,voted_up

Exit codes

Code	Meaning
0	Success
1	Usage / input error
2	Network / API error

Agent integration

stools bundles a SKILL.md following the agentskills.io open standard.

Claude Code

Via the plugin marketplace (installs the skill and keeps it updated):

claude install-plugin aotarola/stools

Or via the CLI:

stools install-skill claude   # → ~/.claude/skills/stools/SKILL.md

Hermes / Codex

stools install-skill hermes   # → ~/.hermes/skills/stools/SKILL.md
stools install-skill codex    # → ~/.agents/skills/stools/SKILL.md

Once installed, the agent can discover and use stools automatically.

Design notes

• JSON only: all output goes to stdout as JSON; errors go to stderr.
• No dependencies: uses only Python standard library.
• Subcommand structure: stools <command> — designed to grow with more Steam data commands.
• Agent-ready: includes .claude-plugin/ manifest and skills/ for automatic discovery by LLM agents.