wcl — Warcraft Logs CLI

A command-line client for the Warcraft Logs GraphQL API with OAuth PKCE auth, disk caching, rate-limit awareness, and optional WoWSims database enrichment. Built for verifying sim damage calculations against real combat logs — but useful for any scripted WCL data access.

Also ships as an agent skill so coding agents (Claude Code, Cursor, etc.) can drive it.

Install

npm install -g @hillerstorm/wcl

Or from source:

git clone https://github.com/hillerstorm/wcl
cd wcl
npm install
npm run build
npm link   # puts `wcl` on your $PATH

Requires Node 22+.

Getting started

1. Register an API client at https://www.warcraftlogs.com/api/clients/:

• Name: anything you like
• Redirect URL: http://localhost:31337/callback
• Tick Public Client (the CLI uses PKCE — no client secret involved)

2. Configure:

wcl init

Interactive prompt for your client ID and, optionally, per-expansion WoWSims repo paths (used to enrich responses with item/spell data from the sim's db.json — hit Enter to skip any you don't have). Re-run any time; type - at a prompt to clear a value.

3. Authenticate:

wcl auth

Opens your browser for the OAuth flow and stores tokens locally (0600). Re-run with --reset to start over.

4. Try it:

wcl quota                                          # rate-limit usage
wcl search --encounter "Gruul the Dragonkiller" --class hunter --spec beastmastery
wcl fights <reportCode> --boss                     # fight list for a report
wcl actors <reportCode> --class hunter             # resolve actor IDs
wcl events <reportCode> <fightId> --source "Playername" --summary
wcl player <reportCode> <fightId> "Playername"     # full player snapshot
wcl character "Playername" <server-slug> <region>  # zone rankings

All output is JSON (add --pretty for human-readable). Errors go to stderr as JSON with stable code values and exit codes.

Commands

Command	Purpose
wcl auth [--reset]	OAuth PKCE flow
wcl quota	Current rate-limit usage
wcl query --file q.graphql [--var k=v] [--var k:=json]…	Raw GraphQL escape hatch
wcl report <code>	Report metadata, fights, masterData
wcl fights <code>	Compact fight table
wcl actors <code>	Actor table with resolved pet owners
wcl events <code> <fightId>	Filtered event stream, auto-paginated
wcl fight <code> <fightId>	Fight metadata + damage-done table
wcl player <code> <fightId> <name>	Player snapshot, casts, damage, buffs
wcl cast-snapshot <code> <fightId> <name>	Full state snapshot around a single cast
wcl gear <code> <fightId> <name>	Gear/enchants/gems/temp-enchants for a player (boss fights only)
wcl search	Public-log discovery via rankings
wcl character <name> <server> <region>	Character zone rankings
wcl cache stats / wcl cache clear	Cache management

Run any command with --help for full flags. Global flags: --instance / --expansion select the WCL host (retail, fresh, classic, vanilla, sod) and sim enrichment; --no-cache, --force, --pretty.

Data locations

	Repo checkout	npm install
config.json, credentials.json	repo root (gitignored)	~/.config/wcl/
response cache	<repo>/.cache/	~/.cache/wcl/

Override with $WCL_CONFIG_DIR, $WCL_CACHE_DIR, $WCL_CLIENT_ID, $WCL_WOWSIMS_ROOT.

Rate limits & caching

WCL grants a points-per-hour quota. Every response carries a rateLimit footer; the CLI refuses new requests above 95% usage unless --force is passed. Report-shaped data is cached on disk for 7 days, searches for 1 hour.

Using as an agent skill

The skill definition lives in skills/wcl/SKILL.md:

npx skills add hillerstorm/wcl

or symlink skills/wcl into your agent's skills directory (e.g. ~/.claude/skills/wcl). The skill expects the wcl binary on $PATH — install it via npm or from source as above.

Development

npm run dev -- quota   # run from TypeScript source (tsx)
npm test               # vitest
npm run typecheck      # tsc --noEmit
npm run build          # esbuild bundle → dist/cli.js

Attribution & terms

Data comes from Warcraft Logs, fetched through the official v2 GraphQL API. This is an unofficial tool — not affiliated with, sponsored, or endorsed by RPGLogs / Archon.

Your use of the API is subject to the RPGLogs API Terms of Service. In particular: every user registers their own API client (wcl init — no developer credentials ship with this project, and yours should stay out of any fork you publish), and commercial use of API data requires prior approval from RPGLogs.

License

MIT