Media and Entertainment

setlist.fm

pp-setlist-fm

Search setlist.fm artists, setlists, venues, cities, and concert histories through the setlist.fm API.

Printed by @davemorin (Dave Morin)

Install

npx — recommended

npx -y @mvanhorn/printing-press-library install setlist-fm

Installs the CLI binary and the agent skill (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and more). Add --cli-only or --skill-only for one half. Requires Node.

Hermes

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-setlist-fm --force

From the Hermes CLI. Inside a chat session use /skills install with the same path.

OpenClaw

Install the pp-setlist-fm skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-setlist-fm. The skill defines how its required CLI can be installed.

Paste this to your OpenClaw agent — the skill describes how to install its CLI.

Claude Desktop

This CLI ships an MCPB bundle. Download the latest release .mcpb and double-click it — Claude Desktop walks you through the install.

View source on GitHub →

Every Setlist.fm endpoint, plus offline analytics no API call can return — tour shape, song frequency, what's overdue, setlist prediction.

Setlist.fm rate-limits to 2 requests per second and 1,440 per day, which makes any real analytics workflow impossible against the live API. This CLI syncs an artist's full setlist history to a local SQLite store once, then runs every transcendence query — predict, overdue, tour shape, song gap, covers, attended stats — instantly and offline. Six SDK wrappers exist across five languages; none of them store anything. This one does.

Authentication

Get a free API key at https://www.setlist.fm/settings/api. The CLI looks for SETLISTFM_API_KEY in the environment and falls back to SETLIST_FM_API_KEY for compatibility with existing Python and JavaScript tooling. Run setlist-fm-pp-cli auth set-token <key> to persist it in the config file. All requests automatically throttle to 2 RPS and surface 429 responses with a backoff hint.

Quick Start

# Persist your API key once; every later command reads it from the config.
setlist-fm-pp-cli auth set-token $SETLISTFM_API_KEY

# Get the MusicBrainz ID without copy-pasting from the website.
setlist-fm-pp-cli artist resolve 'Radiohead'

# Pull the last few pages of setlists into the local SQLite store under your daily-request budget.
setlist-fm-pp-cli sync artist 'Radiohead' --max-pages 5

# Run the first transcendence query: which songs are most due for a comeback.
setlist-fm-pp-cli overdue 'Radiohead' --top 10 --agent

# Generate a predicted setlist for the next show from the recent tour.
setlist-fm-pp-cli predict 'Radiohead' --last 10 --songs 22 --agent

Unique Features

These capabilities aren't available in any other tool for this API.

Predictive analytics

predict — Generate a likely setlist for an upcoming show using recency-weighted per-song probability from the artist's recent tour.

When an agent or fan asks 'what will they play tonight', this answers it with confidence-ranked output instead of forcing a manual scrape of the last ten setlists.
```
setlist-fm-pp-cli predict 'Radiohead' --last 10 --songs 22 --agent
```
song-stats — For one song: total plays, first/last date, longest gap, average set position, percentage of shows that included it.

Answers the canonical fan question ('when was the last time they played X?') without burning 50 API calls.
```
setlist-fm-pp-cli song-stats 'Radiohead' 'Paranoid Android' --agent
```
overdue — Rank an artist's songs by shows-since-last-played to surface what is most due to return.

Lets an agent predict the 'wildcard' slot of a setlist without re-fetching the artist's whole tour.
```
setlist-fm-pp-cli overdue 'Radiohead' --top 10 --agent
```
song-gap — Biggest dry spells for one song and when the comeback happened.

Lets agents narrate band history without re-fetching the full setlist history.
```
setlist-fm-pp-cli song-gap 'Radiohead' 'Creep' --agent
```

Tour analytics

tour-shape — Median set length, encore frequency, song-position histogram, top openers and closers for one tour.

Gives an agent a one-shot summary of how an artist is structuring a tour, replacing dozens of read calls.
```
setlist-fm-pp-cli tour-shape 'Radiohead' --tour 'A Moon Shaped Pool Tour' --agent
```
compare — Overlap percent, dropped songs, debuts, and set-position shifts between two named tours of one artist.

Surfaces tour evolution in one call for review/journalism workflows.
```
setlist-fm-pp-cli compare 'Phoenix' --tour 'Ti Amo Tour' --tour 'Alpha Zulu Tour' --agent
```
encore — Top encore openers, top encore closers, percent of shows that had an encore at all.

Lets agents answer 'what do they always close with?' offline.
```
setlist-fm-pp-cli encore 'Radiohead' --agent
```
venue-loyalty — Top venues an artist plays at, by frequency. Detects 'home venue' patterns.

Lets agents reason about artist-venue affinity without dozens of API calls.
```
setlist-fm-pp-cli venue-loyalty 'Phish' --agent
```

Discovery

covers — All cover songs an artist has played live, ranked by frequency with the original artist.

Surfaces fan-discovery moments (rare covers, recurring covers) for journalism or curation.
```
setlist-fm-pp-cli covers 'Phoebe Bridgers' --top 20 --agent
```
setlist-diff — Side-by-side song diff of two setlist IDs.

Lets agents answer 'what changed between these two shows' without parsing two responses by hand.
```
setlist-fm-pp-cli setlist-diff 53e3ab04 7be1aaa0 --agent
```
debut — Songs an artist has played exactly once live.

Surfaces one-off oddities (one-time covers, abandoned originals) for rare-finding workflows.
```
setlist-fm-pp-cli debut 'Phoenix' --agent
```

Collector tools

attended-stats — Total shows, unique artists/songs/venues/cities, biggest streak, longest gap, decade breakdown for a user.

Delivers a one-shot collector dashboard that the website does not produce.
```
setlist-fm-pp-cli attended-stats dave42 --agent
```
bingo — Printable bingo card of N most-likely-to-play songs for an upcoming show.

Fan-festival use case; gives a delightful tangible output the API was never going to ship.
```
setlist-fm-pp-cli bingo 'Radiohead' --songs 25
```
since — Setlist updates since a given timestamp; pair with sync for delta refresh.

Lets a daily-digest agent stay current without re-syncing the full history.
```
setlist-fm-pp-cli since 2026-05-01T00:00:00Z --artist 'Radiohead' --agent
```
playlist — Generate a Spotify playlist from an artist's most recent setlist (or merged last N setlists) — output as CSV, M3U, or Spotify-search URIs, or use the Spotify Web API to create the playlist directly.

Turns a concert log into something an agent or user can listen to in one command — the bridge between data and ear that no wrapper builds.
```
setlist-fm-pp-cli playlist 'Radiohead' --last 1 --output csv > radiohead-last-show.csv
```

Commands

Artists & Setlists

Command	Description
`artist resolve <name>`	Resolve an artist name to a MusicBrainz MBID
`artist get <mbid>`	Get artist details by MBID
`artist setlists <mbid>`	List setlists for an artist
`setlist get <id>`	Get a specific setlist by ID
`setlist version <versionId>`	Get a setlist version by ID
`setlist-diff <idA> <idB>`	Side-by-side diff of two setlists

Search

Command	Description
`search artists --name <name>`	Search for artists
`search venues --name <name>`	Search for venues
`search cities --name <name>`	Search for cities
`search countries`	List all supported countries
`search setlists --artist <name>`	Search for setlists

Venues & Cities

Command	Description
`venue get <id>`	Get venue details
`venue setlists <id>`	List setlists at a venue
`city get <geoId>`	Get city details by GeoNames ID

Users

Command	Description
`user get <userId>`	Get user details
`user attended <userId>`	List setlists a user has attended
`user edited <userId>`	List setlists a user has edited
`attended-stats <userId>`	Collector dashboard: shows, artists, songs, venues, streaks

Analytics (offline, from local store)

Command	Description
`predict <artist>`	Generate a predicted setlist using recency-weighted probability
`song-stats <artist> <song>`	Total plays, first/last date, gap, position, frequency
`overdue <artist>`	Rank songs by shows since last played
`song-gap <artist> <song>`	Biggest dry spells between plays of one song
`tour-shape <artist>`	Set lengths, encores, openers, closers for one tour
`compare <artist>`	Compare two tours: overlap, dropped, added, position shifts
`encore <artist>`	Top encore songs and encore frequency
`covers <artist>`	All cover songs played live, ranked by frequency
`debut <artist>`	Songs played exactly once live
`venue-loyalty <artist>`	Top venues by frequency, home venue detection
`tour-route <artist>`	Chronological route of a tour: dates, cities, venues
`bingo <artist>`	Bingo card of most-likely songs for an upcoming show
`playlist <artist>`	Export setlist as CSV, M3U, or Spotify search URIs
`since <timestamp>`	Setlists updated since a given timestamp

Sync & Utilities

Command	Description
`sync artist <name-or-mbid>`	Sync all setlists for an artist into local store
`sync user <userId>`	Sync a user's attended setlists into local store
`workflow archive`	Sync all resources to local store
`workflow status`	Show local archive status and sync state
`doctor`	Check CLI health: config, auth, connectivity
`auth set-token <key>`	Save an API token to the config file
`auth status`	Show authentication status
`auth logout`	Clear stored credentials
`which <capability>`	Find the command that implements a capability
`import <resource>`	Import data from JSONL file

Output Formats

# Human-readable table (default in terminal, JSON when piped)
setlist-fm-pp-cli artist resolve 'Radiohead'

# JSON for scripting and agents
setlist-fm-pp-cli artist resolve 'Radiohead' --json

# Filter to specific fields
setlist-fm-pp-cli artist resolve 'Radiohead' --json --select mbid,name

# CSV output
setlist-fm-pp-cli overdue 'Radiohead' --csv

# Dry run — show the request without sending
setlist-fm-pp-cli artist get a74b1b7f-71a5-4011-9441-d0b5e4122711 --dry-run

# Agent mode — JSON + compact + no prompts in one flag
setlist-fm-pp-cli predict 'Radiohead' --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.

Cookbook

# Sync an artist and immediately run predictions
setlist-fm-pp-cli sync artist 'Radiohead' --max-pages 10 && \
  setlist-fm-pp-cli predict 'Radiohead' --last 20 --songs 22

# Which songs haven't been played in the longest time?
setlist-fm-pp-cli overdue 'Radiohead' --top 15 --json

# Compare two tours side by side
setlist-fm-pp-cli compare 'Phoenix' --tour 'Ti Amo Tour' --tour 'Alpha Zulu Tour' --json

# What does a typical show look like on this tour?
setlist-fm-pp-cli tour-shape 'Radiohead' --tour 'A Moon Shaped Pool Tour'

# Generate a bingo card for tonight's show
setlist-fm-pp-cli bingo 'Phish' --songs 25 --last 30

# Export last show as a Spotify-searchable playlist
setlist-fm-pp-cli playlist 'Radiohead' --last 1 --output spotify-search

# What covers does this artist play?
setlist-fm-pp-cli covers 'Phoebe Bridgers' --top 20

# What songs has this artist only played once?
setlist-fm-pp-cli debut 'Phoenix' --json

# How did two shows differ?
setlist-fm-pp-cli setlist-diff 53e3ab04 7be1aaa0

# Daily digest: what changed since yesterday?
setlist-fm-pp-cli since 2026-05-19T00:00:00Z --artist 'Radiohead' --agent

# Collector stats for a user
setlist-fm-pp-cli attended-stats dave42 --json

# Agent pipeline: sync, then answer a question
setlist-fm-pp-cli sync artist 'Radiohead' --max-pages 5 && \
  setlist-fm-pp-cli song-stats 'Radiohead' 'Karma Police' --agent

Health Check

setlist-fm-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/setlist-fm-pp-cli/config.toml

Environment variables:

Name	Required	Description
`SETLISTFM_API_KEY`	Yes	Primary API key (matches setlistfm-js convention).
`SETLIST_FM_API_KEY`	No	Fallback API key (matches setlist-fm-client convention).
`SETLIST_FM_BASE_URL`	No	Override API base URL (default: `https://api.setlist.fm/rest`).
`SETLIST_FM_CONFIG`	No	Override config file path.

Troubleshooting

Authentication errors (exit code 4)

Run setlist-fm-pp-cli doctor to check credentials
Verify the environment variable is set: echo $SETLISTFM_API_KEY Not found errors (exit code 3)
Check the resource ID is correct
Use search artists --name <name> or artist resolve <name> to find valid IDs

API-specific

HTTP 403 on every call — Your API key is missing or invalid. Run setlist-fm-pp-cli doctor to confirm SETLISTFM_API_KEY is loaded.
HTTP 429 Too Many Requests — You exceeded 2 req/sec or 1440/day. The client already throttles, but parallel runs will trip it. Wait, then re-run; consider sync --max-pages N to budget.
Empty results from predict/overdue/song-stats — These commands read from the local store. Run setlist-fm-pp-cli sync artist <name> first.
predict results feel random — Increase --last N (default 20) so more shows feed the probability model; sync more pages first.

Sources & Inspiration

This CLI was built by studying these projects and resources:

setlistfm-js — JavaScript
setlist-fm-client — Python
repertorio — Python
nucleos/setlistfm — PHP
SetlistNet — C#
SetListR — R

Generated by CLI Printing Press