feat(spotify): add Spotify playback adapter

README.md

@@ -121,6 +121,7 @@ git clone git@github.com:jackwener/opencli.git && cd opencli && npm install && n
 | **bilibili** | `hot` `search` `history` `feed` `ranking` `download` `comments` `dynamic` `favorite` `following` `me` `subtitle` `user-videos` |
 | **twitter** | `trending` `search` `timeline` `bookmarks` `post` `download` `profile` `article` `like` `likes` `notifications` `reply` `reply-dm` `thread` `follow` `unfollow` `followers` `following` `block` `unblock` `bookmark` `unbookmark` `delete` `hide-reply` `accept` |
 | **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `user` `user-posts` `user-comments` `read` `save` `saved` `subscribe` `upvote` `upvoted` `comment` |
+| **spotify** | `auth` `status` `play` `pause` `next` `prev` `volume` `search` `queue` `shuffle` `repeat` |
 
 65+ adapters in total — **[→ see all supported sites & commands](./docs/adapters/index.md)**
 

README.zh-CN.md

@@ -173,6 +173,7 @@ npm install -g @jackwener/opencli@latest
 | **douban** | `search` `top250` `subject` `photos` `download` `marks` `reviews` `movie-hot` `book-hot` | 浏览器 |
 | **facebook** | `feed` `profile` `search` `friends` `groups` `events` `notifications` `memories` `add-friend` `join-group` | 浏览器 |
 | **google** | `news` `search` `suggest` `trends` | 公开 |
+| **spotify** | `auth` `status` `play` `pause` `next` `prev` `volume` `search` `queue` `shuffle` `repeat` | OAuth API |
 | **36kr** | `news` `hot` `search` `article` | 公开 / 浏览器 |
 | **imdb** | `search` `title` `top` `trending` `person` `reviews` | 公开 |
 | **producthunt** | `posts` `today` `hot` `browse` | 公开 / 浏览器 |

docs/.vitepress/config.mts

@@ -104,6 +104,7 @@ export default defineConfig({
                 { text: 'Barchart', link: '/adapters/browser/barchart' },
                 { text: 'Hugging Face', link: '/adapters/browser/hf' },
                 { text: 'Sina Finance', link: '/adapters/browser/sinafinance' },
+                { text: 'Spotify', link: '/adapters/browser/spotify' },
                 { text: 'Stack Overflow', link: '/adapters/browser/stackoverflow' },
                 { text: 'Wikipedia', link: '/adapters/browser/wikipedia' },
                 { text: 'Lobsters', link: '/adapters/browser/lobsters' },

docs/adapters/browser/spotify.md

@@ -0,0 +1,62 @@
+# Spotify
+
+**Mode**: 🔑 OAuth API · **Domains**: `accounts.spotify.com`, `api.spotify.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli spotify auth` | Authenticate with Spotify and store tokens locally |
+| `opencli spotify status` | Show current playback status |
+| `opencli spotify play [query]` | Resume playback or search-and-play a track |
+| `opencli spotify pause` | Pause playback |
+| `opencli spotify next` | Skip to the next track |
+| `opencli spotify prev` | Skip to the previous track |
+| `opencli spotify volume <0-100>` | Set playback volume |
+| `opencli spotify search <query>` | Search Spotify tracks |
+| `opencli spotify queue <query>` | Add a track to the playback queue |
+| `opencli spotify shuffle <on|off>` | Toggle shuffle |
+| `opencli spotify repeat <off|track|context>` | Set repeat mode |
+
+## Usage Examples
+
+```bash
+# First-time setup
+opencli spotify auth
+
+# What is playing right now?
+opencli spotify status
+
+# Resume playback
+opencli spotify play
+
+# Search and immediately play a track
+opencli spotify play "Numb Linkin Park"
+
+# Search without playing
+opencli spotify search "Daft Punk" --limit 5 -f json
+
+# Queue a track
+opencli spotify queue "Get Lucky"
+
+# Playback controls
+opencli spotify pause
+opencli spotify next
+opencli spotify prev
+opencli spotify volume 35
+opencli spotify shuffle on
+opencli spotify repeat track
+```
+
+## Setup
+
+1. Create a Spotify app at <https://developer.spotify.com/dashboard>
+2. Add `http://127.0.0.1:8888/callback` to the app's Redirect URIs
+3. Fill in `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` in `~/.opencli/spotify.env`
+4. Run `opencli spotify auth`
+
+## Notes
+
+- Browser Bridge is not required.
+- Tokens are stored locally at `~/.opencli/spotify-tokens.json`.
+- Playback commands work best when you already have an active Spotify device/session.

docs/adapters/index.md

@@ -62,6 +62,7 @@ Run `opencli list` for the live registry.
 | **[barchart](/adapters/browser/barchart)** | `quote` `options` `greeks` `flow` | 🌐 Public |
 | **[hf](/adapters/browser/hf)** | `top` | 🌐 Public |
 | **[sinafinance](/adapters/browser/sinafinance)** | `news` | 🌐 Public |
+| **[spotify](/adapters/browser/spotify)** | `auth` `status` `play` `pause` `next` `prev` `volume` `search` `queue` `shuffle` `repeat` | 🔑 OAuth API |
 | **[stackoverflow](/adapters/browser/stackoverflow)** | `hot` `search` `bounties` `unanswered` | 🌐 Public |
 | **[wikipedia](/adapters/browser/wikipedia)** | `search` `summary` `random` `trending` | 🌐 Public |
 | **[lobsters](/adapters/browser/lobsters)** | `hot` `newest` `active` `tag` | 🌐 Public |

scripts/postinstall.js

@@ -196,6 +196,22 @@ function main() {
     }
   }
 
+  // ── Spotify credentials template ────────────────────────────────────
+  const opencliDir = join(home, '.opencli');
+  const spotifyEnvFile = join(opencliDir, 'spotify.env');
+  ensureDir(opencliDir);
+  if (!existsSync(spotifyEnvFile)) {
+    writeFileSync(spotifyEnvFile,
+      `# Spotify credentials — get them at https://developer.spotify.com/dashboard\n` +
+      `# Add http://127.0.0.1:8888/callback as a Redirect URI in your Spotify app\n` +
+      `SPOTIFY_CLIENT_ID=\n` +
+      `SPOTIFY_CLIENT_SECRET=\n`,
+      'utf8'
+    );
+    console.log(`✓ Spotify credentials template created at ${spotifyEnvFile}`);
+    console.log(`  Fill in your Client ID and Secret, then run: opencli spotify auth`);
+  }
+
   // ── Browser Bridge setup hint ───────────────────────────────────────
   console.log('');
   console.log('  \x1b[1mNext step — Browser Bridge setup\x1b[0m');