hs-cli

hs-cli

English · 한국어 · 日本語 · 中文 · Español

Hearthstone CLI for AI agents and humans. Decode deck codes, look up cards, query metadata — no API key required. Built on Bun.

hs-cli is a fast, agent-friendly command-line tool that wraps the public HearthstoneJSON data source and the deckstrings library to give you offline-capable Hearthstone deck and card data. Output is designed to be readable by both humans and LLM agents (Claude Code, Codex, etc.) without burning tokens on raw JSON.

Why this exists

The Hearthstone ecosystem has libraries and one official Blizzard API, but no production-grade CLI and no Claude-Code-ready integration. This fills that gap. Decisions and tradeoffs are documented in CLAUDE.md.

Install

Homebrew (macOS / Linux — recommended)

No runtime required. Installs a self-contained ~64 MB binary.

brew install say8425/tap/hs-cli

Supports darwin arm64/x64 and linux arm64/x64.

npm (any OS with Node 22+)

npm install -g @say8425/hs-cli

Requires Node 22+. Bun is not required.

Pre-built binary

Download the binary for your platform from GitHub Releases, then make it executable:

chmod +x hs-<platform>
mv hs-<platform> /usr/local/bin/hs

Available platforms: darwin arm64/x64, linux arm64/x64, windows x64. No runtime required.

From source (for development)

Requires Bun 1.3+ (install).

git clone https://github.com/say8425/hs-cli.git hs-cli
cd hs-cli
bun install
bun run build
bun link            # makes `hs` available everywhere

Verify:

hs --version
hs deck "AAECAQcAA0VjgAEAAA=="

Usage

Decode a deck

hs deck <deckcode>

Class:  Shaman (SHAMAN)
Format: Standard
Dust:   15,760
Cards:  30

Mana Curve
  1 █████ 4
  2 ████████████ 10
  3 ███ 2
  ...

Cards (30)
  ×2  (1) Earth Shock ·
  ×2  (1) Murloc Tidecaller ◇
  ×2  (2) Lorekeeper Polkelt ★
  ...

Rarity glyphs: ★ Legendary · ◆ Epic · ◇ Rare · · Common.

Look up a card

hs card 1124              # by dbfId
hs card CS2_151           # by card ID
hs card --search "Zilliax"
hs card --search "fire" --class MAGE --cost 3

Query metadata

hs meta classes           # all 14 classes
hs meta sets              # every release set
hs meta rarities          # FREE, COMMON, RARE, EPIC, LEGENDARY
hs meta types             # MINION, SPELL, WEAPON, HERO, ...

JSON output

Add -f json to any command for raw structured data:

hs deck <code> -f json | jq '.cards | length'
hs card --search "Lich King" -f json | jq '.[].dbfId'

Agent integration

This repo doubles as a Claude Code marketplace that exposes the hs-cli plugin. Install it once and Claude Code learns to drive the CLI for you:

/plugin marketplace add say8425/hs-cli
/plugin install hs-cli@say8425

For local development:

claude --plugin-dir ./plugins/hs-cli

The plugin ships the hearthstone-deck skill, namespaced as /hs-cli:hearthstone-deck.

Then ask your agent things like:

"Analyze this deck: AAECAQcAA0VjgAEAAA=="

"Find the cards that overlap between these two decks"

"Recommend 3-mana cards for Priest"

The skill teaches the agent:

• Use table format by default (token-efficient)
• Reach for json | jq only when extracting specific fields
• Translate class names for Korean users
• Detect old/invalid deck codes by Unknown (id) markers in output

Localization

hs defaults to enUS. Override with -l, --locale <code> on any command, or export HS_CLI_LOCALE to make it permanent.