Bandsintown CLI

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.

Created by @4.5.2 (printing-press).

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:

• subdigital/intown — Ruby
• aroscoe/bandsintown — Python
• chrisforrette/python-bandsintown — Python
• bandsintown/api-gem — Ruby
• TappNetwork/php-sdk-bands-in-town-api — PHP
• tobysimone/node-bandsintown — JavaScript
• adamcumiskey/BandsintownAPI — Objective-C

Generated by CLI Printing Press