stools-cli 0.1.0__tar.gz → 0.3.0__tar.gz

{stools_cli-0.1.0 → stools_cli-0.3.0}/.gitignore

@@ -1,3 +1,4 @@
 dist/
 *.egg-info/
 __pycache__/
+.DS_Store

{stools_cli-0.1.0 → stools_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stools-cli
-Version: 0.1.0
+Version: 0.3.0
 Summary: CLI to extract structured data from Steam (reviews, game search) — designed for LLM agents
 Project-URL: Repository, https://github.com/aotarola/stools
 Author: aotarola
@@ -17,20 +17,29 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 
-# stools
+<p align="center">
+  <img src="assets/logo.png" alt="stools banner" width="150" />
+</p>
 
-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.
+<h1 align="center">stools</h1>
+
+<p align="center">
+  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.
+</p>
 
 ## Installation
 
+### macOS (Homebrew)
+
 ```bash
+brew install pipx
 pipx install stools-cli
 ```
 
-Or with pip:
+### Other platforms
 
 ```bash
-pip install stools-cli
+python3 -m pip install stools-cli
 ```
 
 Requires Python 3.9+. No external dependencies.
@@ -45,11 +54,11 @@ 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`) |
+| 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
 
@@ -88,16 +97,18 @@ stools reviews "$APP_ID"
 Fetch all reviews for a Steam game.
 
 ```
-stools reviews <app_id_or_url> [--language CODE] [--limit N] [--fields f1,f2,...] [--output FILE]
+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` |
-| `--limit N`    | Max reviews to return. `0` = all. 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                                      |
+| 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
 
@@ -147,8 +158,16 @@ stools reviews 1005310
 # Fetch only English reviews, save to file
 stools reviews 1005310 --language english --output reviews.json
 
-# Fetch first 10 reviews, no progress output
+# 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/"
 
@@ -158,21 +177,38 @@ stools reviews 1005310 --fields review,voted_up
 
 ## Exit codes
 
-| Code | Meaning            |
-|------|--------------------|
-| `0`  | Success            |
-| `1`  | Usage / input error|
-| `2`  | Network / API error|
+| Code | Meaning             |
+| ---- | ------------------- |
+| `0`  | Success             |
+| `1`  | Usage / input error |
+| `2`  | Network / API error |
 
 ## Agent integration
 
-stools ships as a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code). To use it in your agent:
+stools bundles a [SKILL.md](skills/stools/SKILL.md) following the [agentskills.io](https://agentskills.io) open standard.
+
+### Claude Code
+
+Via the plugin marketplace (installs the skill and keeps it updated):
 
 ```bash
 claude install-plugin aotarola/stools
 ```
 
-This registers the `stools` CLI as a skill that Claude Code can discover and invoke automatically. See [`skills/stools/SKILL.md`](skills/stools/SKILL.md) for the agent-facing documentation.
+Or via the CLI:
+
+```bash
+stools install-skill claude   # → ~/.claude/skills/stools/SKILL.md
+```
+
+### Hermes / Codex
+
+```bash
+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
 

stools_cli-0.3.0/README.md

@@ -0,0 +1,199 @@
+<p align="center">
+  <img src="assets/logo.png" alt="stools banner" width="150" />
+</p>
+
+<h1 align="center">stools</h1>
+
+<p align="center">
+  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.
+</p>
+
+## Installation
+
+### macOS (Homebrew)
+
+```bash
+brew install pipx
+pipx install stools-cli
+```
+
+### Other platforms
+
+```bash
+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
+
+```json
+{
+  "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
+
+```bash
+# 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
+
+```json
+{
+  "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
+
+```bash
+# 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](skills/stools/SKILL.md) following the [agentskills.io](https://agentskills.io) open standard.
+
+### Claude Code
+
+Via the plugin marketplace (installs the skill and keeps it updated):
+
+```bash
+claude install-plugin aotarola/stools
+```
+
+Or via the CLI:
+
+```bash
+stools install-skill claude   # → ~/.claude/skills/stools/SKILL.md
+```
+
+### Hermes / Codex
+
+```bash
+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.

{stools_cli-0.1.0 → stools_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stools-cli"
-version = "0.1.0"
+version = "0.3.0"
 description = "CLI to extract structured data from Steam (reviews, game search) — designed for LLM agents"
 readme = "README.md"
 license = "MIT"

{stools_cli-0.1.0 → stools_cli-0.3.0}/skills/stools/SKILL.md

@@ -1,11 +1,17 @@
+---
+name: stools
+description: Search Steam games and fetch reviews as structured JSON. Use when the user asks about Steam game reviews, ratings, or wants to look up a game on Steam.
+license: MIT
+compatibility: Requires Python 3.9+ and stools-cli installed via pip or pipx.
+metadata:
+  author: aotarola
+  version: "0.1.0"
+---
+
 # stools — Steam data extraction CLI
 
 You have access to `stools`, a CLI that fetches structured data from Steam. All output is JSON on stdout. Errors go to stderr.
 
-## Requirements
-
-Python 3.9+. No external dependencies.
-
 ## Typical Workflow
 
 When a user asks about a Steam game by name (not by app ID or URL):
@@ -60,14 +66,16 @@ stools search <query> [--limit N] [--fields f1,f2,...]
 Fetch all reviews for a Steam game.
 
 ```
-stools reviews <app_id_or_url> [--language CODE] [--limit N] [--fields f1,f2,...] [--output FILE]
+stools reviews <app_id_or_url> [--language CODE] [--review-type TYPE] [--limit N] [--offset N] [--fields f1,f2,...] [--output FILE]
 ```
 
 **Arguments:**
 
 - `app` (required): Steam app ID (e.g. `1005310`) or full store URL
 - `--language CODE`: Filter by language — `english`, `spanish`, `french`, `german`, etc. Default: `all`
+- `--review-type 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 f1,f2,...`: Comma-separated fields to keep per review. Available: `recommendationid`, `author`, `language`, `review`, `timestamp_created`, `timestamp_updated`, `voted_up`, `votes_up`, `votes_funny`, `steam_purchase`, `received_for_free`, `written_during_early_access`
 - `--output FILE`: Write JSON to a file instead of stdout
 
@@ -122,6 +130,13 @@ stools reviews 1005310 --language english --fields review,voted_up
 # Get a sample of 10 reviews
 stools reviews 1005310 --limit 10 --fields review,voted_up
 
+# Paginate: first 50, then next 50
+stools reviews 730 --limit 50 --fields review,voted_up
+stools reviews 730 --limit 50 --offset 50 --fields review,voted_up
+
+# Get only negative reviews
+stools reviews 730 --review-type negative --fields review,voted_up
+
 # Save full reviews to file
 stools reviews 1005310 --output reviews.json
 ```
@@ -129,7 +144,8 @@ stools reviews 1005310 --output reviews.json
 ## Tips
 
 - Use `--fields` to reduce output size. For disambiguation, `--fields app_id,name` is usually enough.
-- Use `--limit` to fetch a small sample before pulling all reviews for large games.
+- Use `--limit` and `--offset` to paginate through large review sets in batches.
+- Use `--review-type negative` to focus on criticism without pulling all reviews.
 - The `reviews` command accepts full Steam URLs, so you can pass URLs directly from the user.
 - Timestamps are Unix epoch seconds.
 - Prices are in cents (e.g. `2999` = $29.99).

{stools_cli-0.1.0 → stools_cli-0.3.0}/src/stools_cli/cli.py

@@ -1,8 +1,9 @@
 """stools — CLI to extract structured data from Steam.
 
 Usage:
-    stools search <query> [--limit <n>]
-    stools reviews <app_id_or_url> [--language <code>] [--limit <n>] [--output <file>]
+    stools search <query> [--limit <n>] [--fields <f1,f2,...>]
+    stools reviews <app_id_or_url> [--language <code>] [--limit <n>] [--fields <f1,f2,...>] [--output <file>]
+    stools install-skill <claude|hermes|codex>
 
 All output is JSON on stdout. Errors go to stderr.
 Exit codes: 0 = success, 1 = usage error, 2 = network/API error.
@@ -10,14 +11,17 @@ Exit codes: 0 = success, 1 = usage error, 2 = network/API error.
 
 import argparse
 import json
+import os
 import re
+import shutil
 import sys
 import time
 import urllib.error
 import urllib.parse
 import urllib.request
+from pathlib import Path
 
-VERSION = "0.1.0"
+VERSION = "0.3.0"
 
 
 def pick_fields(items: list[dict], fields: list[str]) -> list[dict]:
@@ -42,18 +46,28 @@ def parse_app_id(value: str) -> int:
     sys.exit(1)
 
 
-def fetch_reviews(app_id: int, language: str = "all", limit: int = 0) -> dict:
+def fetch_reviews(
+    app_id: int,
+    language: str = "all",
+    review_type: str = "all",
+    limit: int = 0,
+    offset: int = 0,
+) -> dict:
     """Fetch reviews for a Steam app, paginating automatically."""
+    total_needed = limit + offset if limit else 0
     all_reviews: list[dict] = []
     cursor = "*"
     query_summary = None
     per_page = 100
 
     while True:
-        if limit and len(all_reviews) >= limit:
+        if total_needed and len(all_reviews) >= total_needed:
             break
 
-        batch_size = min(per_page, limit - len(all_reviews)) if limit else per_page
+        if total_needed:
+            batch_size = min(per_page, total_needed - len(all_reviews))
+        else:
+            batch_size = per_page
 
         params = urllib.parse.urlencode({
             "json": 1,
@@ -61,13 +75,13 @@ def fetch_reviews(app_id: int, language: str = "all", limit: int = 0) -> dict:
             "cursor": cursor,
             "filter": "recent",
             "language": language,
-            "review_type": "all",
+            "review_type": review_type,
             "purchase_type": "all",
         })
         url = f"https://store.steampowered.com/appreviews/{app_id}?{params}"
 
         try:
-            req = urllib.request.Request(url, headers={"User-Agent": "stools/0.1.0"})
+            req = urllib.request.Request(url, headers={"User-Agent": "stools/0.2.0"})
             with urllib.request.urlopen(req, timeout=30) as resp:
                 data = json.loads(resp.read().decode())
         except urllib.error.URLError as e:
@@ -93,6 +107,8 @@ def fetch_reviews(app_id: int, language: str = "all", limit: int = 0) -> dict:
 
         time.sleep(0.5)
 
+    # Apply offset and limit
+    all_reviews = all_reviews[offset:]
     if limit:
         all_reviews = all_reviews[:limit]
 
@@ -140,6 +156,33 @@ def fetch_search(query: str, limit: int = 10) -> dict:
     }
 
 
+SKILL_TARGETS = {
+    "claude": Path.home() / ".claude" / "skills" / "stools",
+    "hermes": Path.home() / ".hermes" / "skills" / "stools",
+    "codex": Path.home() / ".agents" / "skills" / "stools",
+}
+
+
+def get_bundled_skill_dir() -> Path:
+    """Return the path to the bundled skill directory inside the package."""
+    return Path(__file__).parent / "skill"
+
+
+def cmd_install_skill(args: argparse.Namespace) -> None:
+    agent = args.agent
+    target = SKILL_TARGETS[agent]
+    source = get_bundled_skill_dir()
+    skill_file = source / "SKILL.md"
+
+    if not skill_file.exists():
+        print(json.dumps({"error": "Bundled SKILL.md not found."}), file=sys.stderr)
+        sys.exit(1)
+
+    target.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(skill_file, target / "SKILL.md")
+    print(json.dumps({"installed": str(target / "SKILL.md"), "agent": agent}))
+
+
 def cmd_search(args: argparse.Namespace) -> None:
     result = fetch_search(args.query, limit=args.limit)
     if args.fields:
@@ -149,7 +192,13 @@ def cmd_search(args: argparse.Namespace) -> None:
 
 def cmd_reviews(args: argparse.Namespace) -> None:
     app_id = parse_app_id(args.app)
-    result = fetch_reviews(app_id, language=args.language, limit=args.limit)
+    result = fetch_reviews(
+        app_id,
+        language=args.language,
+        review_type=args.review_type,
+        limit=args.limit,
+        offset=args.offset,
+    )
     if args.fields:
         result["reviews"] = pick_fields(result["reviews"], args.fields)
 
@@ -169,6 +218,19 @@ def main() -> None:
     parser.add_argument("--version", action="version", version=f"stools {VERSION}")
     subparsers = parser.add_subparsers(dest="command", required=True)
 
+    # --- install-skill subcommand ---
+    install_parser = subparsers.add_parser(
+        "install-skill",
+        help="Install the stools skill for an AI agent.",
+        description="Copy the stools SKILL.md to the skills directory of the specified agent.",
+    )
+    install_parser.add_argument(
+        "agent",
+        choices=["claude", "hermes", "codex"],
+        help="Target agent: claude (~/.claude/skills/stools), hermes (~/.hermes/skills/stools), codex (~/.agents/skills/stools)",
+    )
+    install_parser.set_defaults(func=cmd_install_skill)
+
     # --- search subcommand ---
     search_parser = subparsers.add_parser(
         "search",
@@ -216,6 +278,12 @@ def main() -> None:
         metavar="CODE",
         help="Filter by language: english, spanish, french, german, etc. (default: all)",
     )
+    reviews_parser.add_argument(
+        "--review-type",
+        default="all",
+        choices=["all", "positive", "negative"],
+        help="Filter by review type (default: all)",
+    )
     reviews_parser.add_argument(
         "--limit",
         type=int,
@@ -223,6 +291,13 @@ def main() -> None:
         metavar="N",
         help="Max number of reviews to fetch. 0 = all (default: 0)",
     )
+    reviews_parser.add_argument(
+        "--offset",
+        type=int,
+        default=0,
+        metavar="N",
+        help="Skip the first N reviews. Use with --limit to paginate (default: 0)",
+    )
     reviews_parser.add_argument(
         "--output",
         metavar="FILE",

stools_cli-0.3.0/src/stools_cli/skill/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: stools
+description: Search Steam games and fetch reviews as structured JSON. Use when the user asks about Steam game reviews, ratings, or wants to look up a game on Steam.
+license: MIT
+compatibility: Requires Python 3.9+ and stools-cli installed via pip or pipx.
+metadata:
+  author: aotarola
+  version: "0.1.0"
+---
+
+# stools — Steam data extraction CLI
+
+You have access to `stools`, a CLI that fetches structured data from Steam. All output is JSON on stdout. Errors go to stderr.
+
+## Typical Workflow
+
+When a user asks about a Steam game by name (not by app ID or URL):
+
+1. Run `stools search "<game name>" --fields app_id,name` to find matching games.
+2. If multiple results match, present the options to the user and ask which one they mean.
+3. Use the `app_id` from the chosen result to run `stools reviews <app_id>`.
+
+When the user provides a Steam URL or app ID directly, skip to step 3.
+
+Use `--fields` on both commands to request only the data you need and keep context small.
+
+## Available Commands
+
+### `stools search`
+
+Search Steam for games by name.
+
+```
+stools search <query> [--limit N] [--fields f1,f2,...]
+```
+
+**Arguments:**
+
+- `query` (required): Search term (e.g. `"megaman"`, `"dark souls"`, `"snake"`)
+- `--limit N`: Max results to return. Default: `10`
+- `--fields f1,f2,...`: Comma-separated fields to keep per result. Available: `app_id`, `name`, `price`, `platforms`, `metascore`
+
+**Output:**
+
+```json
+{
+  "query": "megaman",
+  "total_results": 10,
+  "results": [
+    {
+      "app_id": 742300,
+      "name": "Mega Man 11"
+    }
+  ]
+}
+```
+
+**Key fields:**
+
+- `results[].app_id`: Use this to call `stools reviews`
+- `results[].name`: Display name to show the user
+- `results[].price.final`: Price in cents (divide by 100 for dollars)
+
+### `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]
+```
+
+**Arguments:**
+
+- `app` (required): Steam app ID (e.g. `1005310`) or full store URL
+- `--language CODE`: Filter by language — `english`, `spanish`, `french`, `german`, etc. Default: `all`
+- `--review-type 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 f1,f2,...`: Comma-separated fields to keep per review. Available: `recommendationid`, `author`, `language`, `review`, `timestamp_created`, `timestamp_updated`, `voted_up`, `votes_up`, `votes_funny`, `steam_purchase`, `received_for_free`, `written_during_early_access`
+- `--output FILE`: Write JSON to a file instead of stdout
+
+**Output:**
+
+```json
+{
+  "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": [
+    {
+      "review": "The review text content.",
+      "voted_up": true
+    }
+  ]
+}
+```
+
+**Key fields:**
+
+- `query_summary.review_score_desc`: Overall rating label (e.g. "Positive", "Mixed", "Overwhelmingly Positive")
+- `query_summary.total_positive` / `total_negative`: Vote counts
+- `reviews[].voted_up`: `true` = positive, `false` = negative
+- `reviews[].review`: The full review text
+- `reviews[].playtime_forever`: Total playtime in minutes
+- `reviews[].playtime_at_review`: Playtime at time of review in minutes
+
+## Exit Codes
+
+`0` = success, `1` = input error, `2` = network/API error.
+
+## Examples
+
+```bash
+# Search for a game (minimal output)
+stools search "snake vs snake" --fields app_id,name
+
+# Fetch reviews — just text and sentiment
+stools reviews 1005310 --fields review,voted_up
+
+# Get only English reviews
+stools reviews 1005310 --language english --fields review,voted_up
+
+# Get a sample of 10 reviews
+stools reviews 1005310 --limit 10 --fields review,voted_up
+
+# Paginate: first 50, then next 50
+stools reviews 730 --limit 50 --fields review,voted_up
+stools reviews 730 --limit 50 --offset 50 --fields review,voted_up
+
+# Get only negative reviews
+stools reviews 730 --review-type negative --fields review,voted_up
+
+# Save full reviews to file
+stools reviews 1005310 --output reviews.json
+```
+
+## Tips
+
+- Use `--fields` to reduce output size. For disambiguation, `--fields app_id,name` is usually enough.
+- Use `--limit` and `--offset` to paginate through large review sets in batches.
+- Use `--review-type negative` to focus on criticism without pulling all reviews.
+- The `reviews` command accepts full Steam URLs, so you can pass URLs directly from the user.
+- Timestamps are Unix epoch seconds.
+- Prices are in cents (e.g. `2999` = $29.99).

stools_cli-0.1.0/README.md

@@ -1,163 +0,0 @@
-# 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
-
-```bash
-pipx install stools-cli
-```
-
-Or with pip:
-
-```bash
-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
-
-```json
-{
-  "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
-
-```bash
-# 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] [--limit 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` |
-| `--limit N`    | Max reviews to return. `0` = all. 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
-
-```json
-{
-  "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
-
-```bash
-# 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, no progress output
-stools reviews 1005310 --limit 10
-# 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 ships as a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code). To use it in your agent:
-
-```bash
-claude install-plugin aotarola/stools
-```
-
-This registers the `stools` CLI as a skill that Claude Code can discover and invoke automatically. See [`skills/stools/SKILL.md`](skills/stools/SKILL.md) for the agent-facing documentation.
-
-## 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.