🎵 SpotiB0T — Spotify Playlist Manager & Automation Bot

A powerful, full-featured Spotify playlist manager with a stunning interactive CLI and automated bot for rule-based playlist management.

---

✨ Features

🎧 Playlist Management

• List all playlists with track counts, visibility, and owner info
• View tracks with paginated browsing (50 per page)
• Create new playlists
• Edit playlist name, description, and visibility
• Clone any playlist (full deep copy)
• Remove tracks interactively with multi-select
• Shuffle playlists with smart artist separation
• Merge multiple playlists into one (with dedup)
• Delete (unfollow) playlists
• Follow / Unfollow playlists by ID or URL

🔍 Search

• Search the Spotify catalog and add results to any playlist
• Quick search for fast lookups with popularity stars

📊 Analytics

• Playlist stats — duration, popularity, top artists, decade breakdown, diversity metrics
• Audio analysis — danceability, energy, valence, acousticness, tempo, key distribution
• Library overview — total playlists, tracks, public/private split, largest playlists

💾 Export & Backup

• Export playlists to JSON or CSV
• Import playlists from JSON files
• Full backup of all playlists to a single timestamped file
• Restore from backup — recreates playlists and re-adds all tracks

⚡ Automation (9 Rule Types)

Rule	Description
❤️ Add Liked Songs	Auto-add recently liked songs to a playlist
🗑️ Remove Unplayed	Remove tracks not played in X days
🔄 Sync Playlists	Mirror or append from one playlist to another
🔮 Discover Clone	Archive each week's Discover Weekly
🧹 Deduplicate	Remove duplicate tracks (keep first or last)
📊 Sort Playlist	Sort by name, artist, date, popularity, or duration
🏆 Top Tracks	Auto-fill your top tracks into a playlist
🔀 Auto-Shuffle	Smart shuffle with artist separation
💡 Recommendations	Generate recs from a seed playlist

🤖 Bot Mode

• Cron scheduling — runs rules automatically (configurable schedule)
• Dry-run mode — preview changes without modifying Spotify
• Run history — every execution is logged and auditable

🚀 Direct CLI Commands

Run commands without entering the interactive menu:

npm run dev -- list                  # List all playlists
npm run dev -- search "daft punk"    # Search tracks
npm run dev -- stats                 # Library overview
npm run dev -- backup                # Backup all playlists
npm run dev -- export <playlistId>   # Export a playlist to JSON

---

📦 Quick Start

1. Prerequisites

• Node.js 20+ installed (download)
• A Spotify Developer account — Create one here

2. Create a Spotify App

1. Go to https://developer.spotify.com/dashboard
2. Click Create App
3. Set the Redirect URI to: http://localhost:8888/callback
4. Note your Client ID and Client Secret

3. Install & Configure

git clone https://github.com/ColinGamez/SpotiB0T.git
cd SpotiB0T
npm install

# Copy the example env file and fill in your credentials
cp .env.example .env

Edit .env with your Spotify app credentials:

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here

4. Authenticate

npm run dev

On first launch the app opens your browser for Spotify login. After authorizing, tokens are stored securely in a local SQLite database and auto-refresh.

5. Use the CLI

The interactive menu is organized into clear sections:

╔════════════════════════════════════════════╗
║   SpotiB0T  ·  Playlist Manager & Bot     ║
╚════════════════════════════════════════════╝
  Logged in as: YourName

─── PLAYLISTS ───────────────────────────────
  List my playlists
  View playlist tracks
  Create new playlist
  Edit playlist details
  Clone a playlist
  Remove tracks
  Shuffle a playlist
  Merge playlists
  Delete a playlist
  Follow / Unfollow

─── SEARCH ──────────────────────────────────
  Search & add tracks
  Quick search

─── ANALYTICS ───────────────────────────────
  Playlist stats
  Library overview

─── EXPORT & BACKUP ─────────────────────────
  Export playlist (JSON/CSV)
  Import playlist
  Backup all playlists
  Restore from backup

─── AUTOMATION ──────────────────────────────
  List rules
  Add rule
  Run a rule
  Toggle rule
  Delete rule
  View run history

  Logout

6. Run the Bot

# Run all enabled rules once
npm run dev -- --once

# Run in cron mode (stays alive, executes on schedule)
npm run dev -- --bot

# Dry-run mode
DRY_RUN=true npm run dev -- --once

---

🏗️ Project Structure

src/
├── auth/                    # OAuth 2.0 authentication
│   ├── oauth.ts             # Authorization Code Flow with PKCE-ready server
│   ├── tokenStore.ts        # Token persistence (SQLite)
│   ├── login.ts             # Standalone login script
│   └── index.ts             # Barrel export
├── spotify/                 # Spotify Web API layer
│   ├── apiClient.ts         # Axios client with retry, rate-limit, token refresh
│   ├── playlistService.ts   # 20+ playlist/library operations
│   ├── types.ts             # TypeScript interfaces for Spotify objects
│   └── index.ts
├── rules/                   # Automation engine
│   ├── types.ts             # Rule type definitions (9 types)
│   ├── ruleStore.ts         # Rule CRUD (SQLite)
│   ├── ruleExecutor.ts      # Rule dispatch & execution handlers
│   └── index.ts
├── bot/                     # Scheduled runner
│   ├── runner.ts            # Cron-based automation + run-once mode
│   └── index.ts
├── commands/                # CLI command handlers
│   ├── playlistCommands.ts  # 10 playlist operations
│   ├── searchCommands.ts    # Search & quick search
│   ├── statsCommands.ts     # Playlist stats & library overview
│   ├── exportCommands.ts    # Export, import, backup, restore
│   ├── ruleCommands.ts      # Rule wizard, toggle, run, delete, history
│   └── index.ts             # Barrel export
├── utils/                   # Shared utilities
│   ├── config.ts            # Validated environment config
│   ├── db.ts                # SQLite database (better-sqlite3)
│   ├── logger.ts            # Winston logging (console + file)
│   ├── format.ts            # CLI formatting helpers (tables, bars, stars)
│   ├── spinner.ts           # ora spinner wrapper
│   └── sleep.ts             # Async delay helper
├── cli.ts                   # Interactive CLI (inquirer menus)
└── index.ts                 # Entry point — CLI / Bot / Direct command router

---

⚙️ Configuration

All config lives in .env:

Variable	Description	Default
SPOTIFY_CLIENT_ID	Your Spotify app Client ID	required
SPOTIFY_CLIENT_SECRET	Your Spotify app Client Secret	required
SPOTIFY_REDIRECT_URI	OAuth callback URL	http://localhost:8888/callback
DRY_RUN	Preview mode — no Spotify writes	false
LOG_LEVEL	Logging verbosity (debug / info / warn / error)	info
DB_PATH	SQLite database file path	./data/spotify-bot.db
CRON_SCHEDULE	Bot execution schedule (cron syntax)	0 * * * * (hourly)

---

📖 Example Rule Setups

Add liked songs from the last week

1. CLI → Add rule → Add liked songs
2. Select target playlist, set days: 7
3. Run it manually or let the bot handle it on schedule

Keep Playlist B in sync with Playlist A

1. CLI → Add rule → Sync playlists
2. Source: Playlist A → Target: Playlist B → Mode: Mirror
3. Enable the bot: npm run dev -- --bot

Archive Discover Weekly every Monday

1. CLI → Add rule → Clone Discover Weekly
2. Set CRON_SCHEDULE=0 9 * * 1 in .env
3. Run: npm run dev -- --bot

Auto-generate a "My Top Tracks" playlist

1. CLI → Add rule → Top tracks
2. Select time range and target playlist
3. The bot updates it on every run

---

🛡️ Safety & Robustness

• Dry-run mode — preview all changes before committing
• Duplicate detection — tracks already in a playlist are never re-added
• Rate-limit handling — automatic exponential backoff on Spotify 429s (capped at 10 retries)
• Retry logic — handles 401, 5xx, and network errors with exponential backoff
• Token auto-refresh — never worry about expired tokens
• Graceful shutdown — SIGINT handler cleanly closes the database
• Audit trail — every rule run is logged with status, summary, and timestamp
• Error recovery — corrupted rule configs are handled gracefully (fallback defaults)

---

🔧 Scripts

Command	Description
npm run dev	Start interactive CLI (with ts-node)
npm run dev -- --bot	Start cron-based bot
npm run dev -- --once	Run all rules once and exit
npm run dev -- list	List playlists (direct)
npm run dev -- search "query"	Search tracks (direct)
npm run dev -- stats	Library overview (direct)
npm run dev -- backup	Backup all playlists (direct)
npm run dev -- export <id>	Export playlist (direct)
npm run build	Compile TypeScript to dist/
npm start	Run compiled JS from dist/
npm run lint	Run ESLint

---

🧰 Tech Stack

Component	Technology
Runtime	Node.js 20+ / TypeScript 5.9
API	Spotify Web API (Authorization Code Flow)
Database	SQLite via better-sqlite3
CLI	Inquirer.js + Chalk + ora spinners
Scheduling	node-cron
HTTP	Axios with retry interceptors
Logging	Winston (console + file)
Linting	ESLint 9 (flat config) + typescript-eslint

---

📄 License

MIT