A headless CLI wrapper for the Tidal music streaming API, designed to be operated by an LLM agent (e.g. Claude). It exposes search, playlist management, and library operations as simple shell commands with structured output.
- Search artists, albums, and tracks in the Tidal catalog
- Playlist management — create, list, rename, delete playlists
- Playlist content — add albums/tracks, remove tracks
- Library (favorites) — add/remove artists, albums, tracks
- Dual output — human-readable text (default) or structured JSON (
--json) - Transparent token refresh — expired sessions are refreshed automatically
- Clean stdout — all errors go to stderr, no parasitic logs
- Python 3.10+
- A Tidal account with an active subscription
pip install -e .This installs the tidal-cli command globally.
Authentication uses the OAuth Device Code Flow and must be performed once by a human:
tidal-cli auth
# Open the displayed URL in your browser and authorize the application.
# A .tidal_session.json file is created with restricted permissions (mode 600).After this one-time setup, all subsequent commands can be run by an LLM agent without human intervention. Tokens are refreshed automatically when they expire.
The --json flag outputs structured JSON instead of text. It must be placed before the subcommand:
tidal-cli --json search artist "Daft Punk"# Search for an artist
tidal-cli search artist "Daft Punk"
# ID: 7804 Name: Daft Punk
# Search for an album
tidal-cli search album "Discovery"
# ID: 1234 Artist: Daft Punk Year: 2001 Name: Discovery
# Search for a track
tidal-cli search track "Around the World"
# ID: 56789 Artist: Daft Punk Name: Around the World# List playlists
tidal-cli playlist list
# Create a playlist
tidal-cli playlist create --name "AI Mix" --desc "Generated by Claude"
# Rename a playlist
tidal-cli playlist rename --playlist-id <ID> --name "New Name"
# Delete a playlist
tidal-cli playlist delete --playlist-id <ID># Add all tracks from an album
tidal-cli playlist add-album --playlist-id <PLAYLIST_ID> --album-id <ALBUM_ID>
# Add a single track
tidal-cli playlist add-track --playlist-id <PLAYLIST_ID> --track-id <TRACK_ID>
# Remove a track
tidal-cli playlist remove-track --playlist-id <PLAYLIST_ID> --track-id <TRACK_ID># Add to library (exactly one of --artist-id, --album-id, --track-id)
tidal-cli library add --artist-id 7804
tidal-cli library add --album-id 1234
tidal-cli library add --track-id 56789
# Remove from library
tidal-cli library remove --artist-id 7804This project ships four Claude Code skills that let you control Tidal directly from a conversation, without typing raw CLI commands.
Skills are located in skills/ and registered via .claude/skills → skills/.
| Skill | Trigger | Description |
|---|---|---|
/tidal-auth |
Log in, authentication error | Launch OAuth flow and save session |
/tidal-search |
Find music, search | Search artists, albums, or tracks |
/tidal-playlist |
Playlist operations | List, create, rename, delete, add/remove content |
/tidal-library |
Save/remove favorites | Add or remove artists, albums, tracks from library |
/tidal-auth
Starts the OAuth Device Code Flow. Displays a URL to open in your browser. After authorization, the session is saved automatically.
/tidal-search <artist|album|track> <query>
Returns a formatted markdown table of results.
/tidal-search artist Daft Punk
/tidal-search album Discovery
/tidal-search track Around the World
/tidal-playlist <list|create|rename|delete|add-album|add-track|remove-track> [options]
Examples:
/tidal-playlist list
/tidal-playlist create My Mix
/tidal-playlist rename --playlist-id <ID> --name "New Name"
/tidal-playlist delete --playlist-id <ID>
/tidal-playlist add-album --playlist-id <ID> --album-id <ID>
/tidal-playlist add-track --playlist-id <ID> --track-id <ID>
/tidal-playlist remove-track --playlist-id <ID> --track-id <ID>
/tidal-library <add|remove> <--artist-id|--album-id|--track-id> <id>
Examples:
/tidal-library add --artist-id 7804
/tidal-library add --album-id 1234
/tidal-library remove --track-id 56789
# 1. Search for an artist
tidal-cli --json search artist "Daft Punk"
# 2. Search for an album
tidal-cli --json search album "Discovery"
# 3. Create a playlist
tidal-cli --json playlist create --name "Electronic Classics"
# 4. Add the album to the playlist
tidal-cli playlist add-album --playlist-id <PLAYLIST_ID> --album-id <ALBUM_ID>- All errors are written to stderr with an
Error:prefix. - Results go to stdout only.
- Exit codes:
0= success,1= error,2= missing argument. - Expired access tokens are refreshed transparently. If the refresh token itself has expired, the CLI prompts for re-authentication.
Private project.