# Fargorate > Look up pool player ratings and handicap data from FargoRate. Use when the user asks about a pool player's rating, FargoRate ID, match odds, race-to recommendations, handicaps, top-ranked pool players, or rating changes over time. A local db can be enabled to track rating changes across runs. Contact fields in the db are local-only and never sent to an API. - Skill: `dvcrn/fargorate` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add dvcrn/fargorate` - Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/fargorate/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: dvcrn (https://skillmd.com/u/dvcrn) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/dvcrn/fargorate --- # FargoRate Look up pool player ratings, match odds, and handicap data from [FargoRate](https://fargorate.com) using the `fargo` CLI tool. --- ## Commands ### `search` — Search players by name or FargoRate ID ```bash fargo search ``` ```bash fargo search "John Smith" fargo search 12345 ``` ### `lookup` — Lookup a player by FargoRate ID Alias for `search` that accepts a single ID. ```bash fargo lookup ``` ```bash fargo lookup 12345 ``` ### `bulk` — Lookup multiple players at once ```bash fargo bulk [id2 ...] fargo bulk --group ``` ```bash fargo bulk 12345 67890 11111 # Use a saved group (see `group` command) fargo bulk --db --group monday-league ``` | Flag | Description | |------------------|---------------------------------------------------------------------------| | `--group ` | Use a saved group of player IDs instead of listing them (requires `--db`) | Uses the configured custom list ID (see `setup`). Defaults to the built-in list ID. ### `odds` — Calculate match odds ```bash fargo odds ``` ```bash # Player rated 550 (races to 7) vs player rated 480 (races to 9) fargo odds 550 480 7 9 ``` ### `races` — Get recommended race lengths ``` fargo races [--type 0|1|2] [--length N] ``` | Flag | Default | Description | |------|---------|-------------| | `--type` | `1` | Race type: `0`=Scotch Doubles, `1`=Singles, `2`=Team | | `--length` | — | Fix the total race length; omit to auto-recommend | ```bash # Recommended singles race lengths for two players fargo races 550 480 # Scotch doubles race recommendation fargo races 550 480 --type 0 # Singles races that fit within a total of 15 games fargo races 550 480 --length 15 ``` ### `top` — View top 10 ranked players ```bash fargo top [--ranking World|US] [--gender M|F] ``` | Flag | Default | Description | |------|---------|-------------| | `--ranking` | `World` | `World` or `US` | | `--gender` | `M` | `M` or `F` | ```bash fargo top fargo top --ranking US --gender F ``` ### `setup` — Configure the tool ``` fargo setup [--list-id ID] ``` Saves a custom list ID used by the `bulk` command to `~/.nanobot/workspace/fargorate/config.json`. ```bash # Interactive prompt fargo setup # Non-interactive fargo setup --list-id myCustomListId ``` ### `group` — Manage named groups of player IDs Groups let you save a named list of FargoRate IDs so you don't have to type them every time. All group commands require `--db`. ```bash # Create or replace a group fargo --db group set monday-league 12345 67890 11111 # List all groups fargo --db group list # Show members of a group (shows cached name/rating if player has been looked up) fargo --db group show monday-league # Delete a group fargo --db group delete monday-league ``` Groups can then be used with `bulk`: ```bash fargo --db bulk --group monday-league fargo --changes --db bulk --group monday-league ``` ### Version ```bash fargo --version ``` --- ## Global Flags These flags work with every command: | Flag | Description | |---------------|--------------------------------------------------------------------------| | `--json` | Output raw JSON as received from the API | | `--db [path]` | Save retrieved player data into a SQLite database | | `--changes` | Only output players whose rating or robustness changed (requires `--db`) | --- ## Database (`--db`) The `--db` flag enables a local SQLite database that persists player data across runs. It works with `search`, `lookup`, and `bulk` — any command that retrieves player records from the API. ### Usage ```bash # Use the default database file (fargo.db in the current directory) fargo --db search "John Smith" fargo --db bulk 12345 67890 # Use a custom path (requires = syntax) fargo --db=~/data/fargo.db search "John Smith" # Combine with --json (outputs raw JSON AND updates the database) fargo --json --db search "John Smith" ``` ### Behavior - The database file is created automatically if it does not exist. - Player rows are inserted or updated on each run — existing records are refreshed, new ones added. - `previous_rating` is updated automatically whenever the rating changes. - A row is appended to `rating_history` only when the player is **new** or their **rating has changed**, avoiding duplicate history entries. ### Schema ```sql CREATE TABLE players ( id TEXT PRIMARY KEY, first_name TEXT NOT NULL, last_name TEXT NOT NULL, location TEXT, rating INTEGER NOT NULL DEFAULT 0, previous_rating INTEGER NOT NULL DEFAULT 0, provisional_rating INTEGER NOT NULL DEFAULT 0, robustness INTEGER NOT NULL DEFAULT 0, last_update_timestamp DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, email TEXT, mobile TEXT, telegram TEXT, discord TEXT, preferred_communication TEXT CHECK(preferred_communication IN ('email','mobile','telegram','discord')) ); CREATE TABLE rating_history ( id INTEGER PRIMARY KEY AUTOINCREMENT, player_id TEXT NOT NULL REFERENCES players(id) ON DELETE CASCADE, timestamp DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, rating INTEGER NOT NULL, provisional_rating INTEGER NOT NULL, robustness INTEGER NOT NULL ); CREATE TABLE fargo_groups ( name TEXT PRIMARY KEY, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE fargo_group_members ( group_name TEXT NOT NULL REFERENCES fargo_groups(name) ON DELETE CASCADE, player_id TEXT NOT NULL, PRIMARY KEY (group_name, player_id) ); ``` > **Note:** Contact fields (`email`, `mobile`, `telegram`, `discord`, `preferred_communication`) are stored in the database but are not populated by the FargoRate API. They can be set directly in the database and are included in `--changes` output when a player's rating changes. --- ## Change Detection (`--changes`) The `--changes` flag filters output to only players whose **rating or robustness changed** since the last run. It requires `--db` and works with `search`, `lookup`, and `bulk`. All fetched players are still written to the database on every run — `--changes` only affects what is printed. ### Examples ```bash # Report only players whose rating or robustness changed fargo --changes --db search "John Smith" fargo --changes --db bulk 12345 67890 11111 # Custom DB path fargo --changes --db=~/data/fargo.db bulk 12345 67890 # Machine-readable JSON output of changes (useful for bots) fargo --changes --json --db search "John Smith" ``` ### Example output ```text 1 change(s) detected: Name : John Smith ID : 12345 Rating : 480 → 495 (provisional: 0) Robustness : 200 → 215 Location : Phoenix AZ Email : john@example.com Preferred : email --- ``` New players (not previously in the database) are marked `[NEW]` and show their current values without a `→` arrow. ### JSON output example (`--json --changes`) ```json [ { "firstName": "John", "lastName": "Smith", "id": "12345", "rating": 495, "provisionalRating": 0, "robustness": 215, "location": "Phoenix AZ", "isNew": false, "previousRating": 480, "previousRobustness": 200, "email": "john@example.com", "preferredCommunication": "email" } ] ``` Contact fields (`email`, `mobile`, `telegram`, `discord`, `preferredCommunication`) are omitted from JSON output when empty. When no changes are detected, the output is: ```text No changes detected. ```