BoardGameGeek CLI

BoardGameGeek's official XMLAPI2 (https://boardgamegeek.com/xmlapi2), the canonical database for board games, RPGs, and video games. Every endpoint returns XML; the generated client normalizes it to JSON so --json/--select and MCP tools work like any JSON API.

Authorization: as of 2025-07-02 BGG requires a registered application and an Authorization: Bearer header on every request (register at https://boardgamegeek.com/applications, then create a token). Requests go to boardgamegeek.com (no leading www).

Scope: read-only lookup across the BGG taste graph — search, full game/thing detail with stats and rankings, the live "hot" list, user profiles, user game collections, logged plays, families, and guilds. No write/mutating endpoints.

Quirk worth knowing: collection (and occasionally thing/plays) can answer with HTTP 202 and a "your request is queued, retry shortly" body the first time a large query is requested; repeat the call until the data is returned.

Quick Start

1. Install

See Install above.

2. Set Up Credentials

Get your access token from your API provider's developer portal, then store it:

boardgamegeek-pp-cli auth set-token YOUR_TOKEN_HERE

Or set it via environment variable:

export BGG_TOKEN="your-token-here"

3. Verify Setup

boardgamegeek-pp-cli doctor

This checks your configuration and credentials.

4. Try Your First Command

boardgamegeek-pp-cli collection --username example-resource

Usage

Run boardgamegeek-pp-cli --help for the full command reference and flag list.

Commands

collection

A user's owned/rated/wishlisted game collection

• boardgamegeek-pp-cli collection - A user's collection by login name. Filter with the 0/1 status flags (own, rated, played, wishlist, want, trade). stats=1 adds per-game rating and rank. Large collections may answer with HTTP 202 the first time and need a retry.

family

Manage family

• boardgamegeek-pp-cli family - A BGG family (a shared series, theme, or IP grouping related things) by id. Comma-separate ids for a batch lookup.

guild

Guild details and membership

• boardgamegeek-pp-cli guild - A BGG guild by id. Set members=1 to include the member roster (paginated with page).

hot

The current BoardGameGeek "Hot" rankings

• boardgamegeek-pp-cli hot - The live BoardGameGeek Hot list. type selects the ranking (boardgame is the default and most common).

plays

Logged play sessions for a user or a game

• boardgamegeek-pp-cli plays - Logged play sessions. Provide username (a user's plays) or id (a game's plays). Filter by date range and paginate with page.

searches

Manage searches

• boardgamegeek-pp-cli searches - Full-text search across the BGG database. Returns matching things (id, name, year). Narrow with type and set exact=1 for exact-name matches.

thing

Full detail for one or more things (games, expansions, accessories)

• boardgamegeek-pp-cli thing - Full record for a game/expansion/accessory by id (comma-separate ids for a batch). Opt into extra sections with the 0/1 flags. stats=1 adds the rating, rank, and ownership statistics most callers want.

user

Public user profiles, buddies, and guild membership

• boardgamegeek-pp-cli user - Public profile for a BGG user by login name. Opt into buddies, guilds, and the user's personal hot/top lists with the 0/1 flags.

Output Formats

# Human-readable table (default in terminal, JSON when piped)
boardgamegeek-pp-cli collection --username example-resource

# JSON for scripting and agents
boardgamegeek-pp-cli collection --username example-resource --json

# Filter to specific fields
boardgamegeek-pp-cli collection --username example-resource --json --select id,name,status

# Dry run — show the request without sending
boardgamegeek-pp-cli collection --username example-resource --dry-run

# Agent mode — JSON + compact + no prompts in one flag
boardgamegeek-pp-cli collection --username example-resource --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

boardgamegeek-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/boardgamegeek-xml-api2-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
BGG_TOKEN	per_call	Yes	Set to your API credential.
BOARDGAMEGEEK_TOKEN	per_call	Yes	Set to your API credential.

agentcookie (optional)

If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, boardgamegeek-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.

Troubleshooting

Authentication errors (exit code 4)

• Run boardgamegeek-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $BGG_TOKEN Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

---

Generated by CLI Printing Press