Metadata-Version: 2.4
Name: stools-cli
Version: 0.2.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
License-Expression: MIT
License-File: LICENSE
Keywords: agent,cli,llm,reviews,steam
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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)

```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] [--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 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.
