@witchpot/steamboard-cli

Command-line tool for Steamboard API — Steam game data analytics, market research, and tag analysis.

Installation

npm install -g @witchpot/steamboard-cli

Authentication

Option 1: Browser Login (OAuth)

steamboard login

Opens your browser to authenticate via Steamboard. Tokens are stored locally in ~/.steamboard-cli/.

Option 2: API Key

# Via environment variable
export STEAMBOARD_API_KEY=your-api-key

# Or via flag
steamboard search --api-key=your-api-key --tags=roguelike

Usage

steamboard <command> [options]
steamboard --version            # print CLI version
steamboard --help               # global help
steamboard <command> --help     # per-command help (also: -h, help <command>)
steamboard completion bash      # bash completion script
steamboard completion zsh       # zsh completion script

Add the completion script to your shell rc file:

# bash
eval "$(steamboard completion bash)" >> ~/.bashrc

# zsh
eval "$(steamboard completion zsh)" >> ~/.zshrc

Game Discovery

steamboard search --tags=roguelike,action --sort=rating_desc --limit=10
steamboard get 553420
steamboard batch 553420,570,730
echo 553420,570,730 | steamboard batch -    # read appids from stdin
cat appids.txt | steamboard batch -          # one id per line, commas, or spaces
steamboard count --tags=indie --reviewsMin=1000
steamboard stats
steamboard tags

App Analysis

steamboard snapshots 553420
steamboard benchmark 553420
steamboard details 553420
steamboard dev-links 553420
steamboard reviews 553420
steamboard playtime 730
steamboard playtime-history 730 --filter=recent --limit=90

Market Analysis

steamboard analyze --groupBy=tag
steamboard analyze-benchmark --tags=roguelike,action --price=1999
steamboard analyze-related --tags=roguelike
steamboard analyze-pricing --tags=indie
steamboard analyze-niches --parentTags=RPG --sort=opportunity_score

Analytics

steamboard tags-common
steamboard tags-trends
steamboard languages
steamboard releases
steamboard upcoming
steamboard review-growth
steamboard playtime-distribution --tag=jrpg
steamboard playtime-distribution --developer=FromSoftware
steamboard playtime-distribution --tag=action --releaseFrom=2024-01-01

System

steamboard snapshot-runs
steamboard deep-dive-check
steamboard dev-links-check
steamboard openapi

Output Options

--format=json|table|csv   # Output format (default: json)
--output=json|table|csv   # Alias for --format
--raw                     # Include full response envelope
--fields=name,appid       # Filter output fields

CSV output works for list endpoints (search, tags, etc.) and for single records (get). For non-tabular payloads (e.g. analyze) the renderer falls back to JSON and prints a notice on stderr.

Debug & Verbose

steamboard search --tags=indie --verbose
STEAMBOARD_DEBUG=1 steamboard search --tags=indie

--verbose (or STEAMBOARD_DEBUG=1) prints HTTP request/response metadata to stderr. Authorization headers are masked.

Search Filters

--keyword=<text>       # Text search
--tags=<t1,t2>         # Filter by tags (comma-separated slugs)
--tagMode=or|and       # Tag matching mode (default: or)
--priceMin=<cents>     # Minimum price in cents
--priceMax=<cents>     # Maximum price in cents
--reviewsMin=<n>       # Minimum review count
--reviewsMax=<n>       # Maximum review count
--ratingMin=<n>        # Minimum rating percentage
--releaseFrom=<date>   # Release date from (YYYY-MM-DD)
--releaseTo=<date>     # Release date to (YYYY-MM-DD)
--developer=<name>     # Filter by developer (partial match)
--publisher=<name>     # Filter by publisher (partial match)
--sort=<option>        # reviews_desc, rating_desc, price_asc, playtime_asc, etc.
--limit=<n>            # Results per page (default: 20, max: 100)
--page=<n>             # Page number

Playtime Filters

Playtime statistics are sampled from Steam reviews and exposed as quantile distributions (p25 / median / p75 / p90 / mean) in minutes. Use these flags on search or count to find games matching a target playtime range.

--playtimeFilter=recent|all          # Sample source (default: all)
--playtimeMetric=at_review|forever   # Which playtime column (default: at_review)
--playtimeQuantile=p25|median|p75|p90|mean  # Quantile to compare (default: median)
--playtimeMinMinutes=<n>             # Lower bound (e.g. 600 = 10h)
--playtimeMaxMinutes=<n>             # Upper bound (e.g. 1800 = 30h)
--playtimeMinSample=<n>              # Minimum sample_size per game

Example: find popular games that take 10–30 hours to play through.

steamboard search --playtimeMinMinutes=600 --playtimeMaxMinutes=1800 \
  --playtimeMinSample=100 --sort=reviews_desc

The playtime, playtime-history, and playtime-distribution commands expose the same statistics directly. See steamboard help for full options.

Configuration

Configuration is resolved in this priority order:

1. CLI flags (--api-key, --api-url)
2. Environment variables (STEAMBOARD_API_KEY, STEAMBOARD_API_URL)
3. Config file (~/.steamboard-cli/config.json)
4. Stored OAuth token (from steamboard login)

The config file can be edited via the config subcommand:

steamboard config set apiUrl https://steamboard.witchpot.com
steamboard config set apiKey sk_live_xxx
steamboard config get apiUrl
steamboard config list      # apiKey is masked in the output
steamboard config unset apiKey
steamboard config path      # print the resolved file path

Valid keys: apiKey, apiUrl. The file is created with 0600 permissions.

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Generic error (unknown command, validation failure, network failure) | | 2 | Authentication error (auth/*) — token missing, expired, or rejected | | 3 | Resource error (resource/*) — game/tag not found, invalid appid | | 4 | Rate limit error (rate_limit/*) — back off and retry | | 5 | Server error (server/*) — upstream API failure |

The CLI prints a structured error block before exiting:

Error [auth/missing_token]: No API key provided
  Hint: Run "steamboard login" or set STEAMBOARD_API_KEY

Requirements

• Node.js >= 18.0.0

License

See LICENSE for details.