Turn Bandsintown's two read-only endpoints into a tour-routing brain: local cache, calendar-gap detection, lineup co-bill mining, and tracker-count trends.
Every existing Bandsintown wrapper is a 10-year-old language binding for the same two API endpoints. This CLI absorbs all of them and adds the queries promoters and tour routers actually need: feasibility-ranked routing candidates for a target city and date, empty windows in an artist's calendar, co-bill patterns across past festivals, and tracker_count trends over time. Local SQLite store, FTS search, agent-native --json output, and MCP exposure are standard.
Learn more at Bandsintown.
Authentication
Bandsintown's API is partner-only as of 2025 — a free 'pick any app_id' string no longer works. Apply for partner access at help.bandsintown.com, then set BANDSINTOWN_APP_ID in your environment.
Quick Start
# Bandsintown's API requires an approved partner key as of 2025
export BANDSINTOWN_APP_ID=your-partner-key
# Verify auth and reachability before doing anything else
bandsintown-pp-cli doctor
# Build a local watchlist; every routing query reads from it
bandsintown-pp-cli track add "Phoenix" "Beach House" "Tame Impala"
# Pull every tracked artist's events into the local store
bandsintown-pp-cli pull --tracked
# Find routing candidates for your target Jakarta date
bandsintown-pp-cli route --to "Jakarta,ID" --on 2026-08-15 --window 7d --tracked --json
Unique Features
These capabilities aren't available in any other tool for this API.
Routing intelligence
-
route — Find which tracked artists already have shows near a target city within a date window — feasibility-ranked routing candidates for booking.
When booking an event in a specific city, the cheapest path is finding an artist already routing through the region. Reach for this before any cold outreach.
bandsintown-pp-cli route --to "Jakarta,ID" --on 2026-08-15 --window 7d --tracked --json
-
gaps — Find empty windows in an artist's tour calendar that match an event slot length, optionally constrained to a region.
Use this to identify artists with a touring gap that aligns with your event date — the most actionable booking lead.
bandsintown-pp-cli gaps "Beach House" --min 5d --max 21d --in SEA --json
-
sea-radar — One-shot Southeast Asia briefing: all upcoming shows in a date range across tracked artists, grouped by city, tagged with tracker tier.
Monday-morning briefing in one invocation: who is touring SEA in your event window, ranked by demand.
bandsintown-pp-cli sea-radar --date 2026-08-01,2026-08-31 --tier mid --json
Lineup intelligence
-
lineup co-bill — Surface which artists frequently co-bill with a given artist by aggregating lineup arrays across many events.
When building festival lineups, find natural co-bill pairings backed by real shared-stage history.
bandsintown-pp-cli lineup co-bill "Phoenix" --since 2024-01-01 --min-shared 2 --json
Demand intelligence
-
trend — Track tracker_count and upcoming_event_count over time per artist; surface rising and falling demand signals.
Rising tracker_count is a leading indicator of audience demand; use to decide who to book before peers notice.
bandsintown-pp-cli trend --top 20 --period 30d --json
Agent-native plumbing
-
pull — Re-fetch every tracked artist's events with a staleness window; emit a structured diff (added / removed / changed events) for downstream agents.
Run this in a daily cron; pipe the diff into Slack or a project tracker to alert when tracked artists add new shows.
bandsintown-pp-cli pull --tracked --since-stale 12 --json
Local state that compounds
-
track — Local watchlist of artists you care about. Drives sync, snapshot, route, and sea-radar.
Build a curated watchlist once; every other intelligence command reads from it.
bandsintown-pp-cli track add "Phoenix" "Tame Impala" "Beach House"
Usage
Run bandsintown-pp-cli --help for the full command reference and flag list.
Commands
artists
Manage artists
bandsintown-pp-cli artists artist - Get artist information
events
Manage events
bandsintown-pp-cli events artist_events - Get upcoming, past, or all artist events, or events within a date range
Output Formats
# Human-readable table (default in terminal, JSON when piped)
bandsintown-pp-cli artists mock-value --app-id 550e8400-e29b-41d4-a716-446655440000
# JSON for scripting and agents
bandsintown-pp-cli artists mock-value --app-id 550e8400-e29b-41d4-a716-446655440000 --json
# Filter to specific fields
bandsintown-pp-cli artists mock-value --app-id 550e8400-e29b-41d4-a716-446655440000 --json --select id,name,status
# Dry run — show the request without sending
bandsintown-pp-cli artists mock-value --app-id 550e8400-e29b-41d4-a716-446655440000 --dry-run
# Agent mode — JSON + compact + no prompts in one flag
bandsintown-pp-cli artists mock-value --app-id 550e8400-e29b-41d4-a716-446655440000 --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, 5 API error, 7 rate limited, 10 config error.
Health Check
bandsintown-pp-cli doctor
Verifies configuration and connectivity to the API.
Configuration
Config file: ~/.config/bandsintown-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Troubleshooting
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 403 "explicit deny" on every request — Your BANDSINTOWN_APP_ID is missing, expired, or not a partner-issued key. Apply at help.bandsintown.com — the free app_id model was deprecated.
- Artist name with special chars returns 404 — The CLI double-escapes /, ?, *, and " per the spec. If you're hitting 404, check the artist exists on bandsintown.com first.
route --tracked returns empty — Run bandsintown-pp-cli pull --tracked first to populate the local store, and check track list is non-empty.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press