tidal-cli

About

tidal-cli wraps the Tidal API v2 into a single command-line tool. Search the catalog, manage playlists, explore artists, play tracks, and handle your library — all without opening a browser. Every command supports --json output, making it the backbone for LLM agent automation through OpenClaw.

Features

• Search artists, albums, tracks, videos, playlists, and autocomplete suggestions
• Artists — info, top tracks, discography, similar artists, radio
• Albums — details, barcode lookup
• Tracks — info, similar tracks, ISRC lookup, radio
• Playlists — full CRUD, add/remove tracks, reorder, add entire albums
• Library — favorites for artists, albums, tracks, videos, playlists
• Playback — stream info, direct URLs, local playback via DASH
• Recommendations — personalized mixes (Daily, Discovery, New Release, Offline) with drill-down into mix items
• History — recently added tracks, albums, artists; search history (list, delete, clear)
• Save for Later — bookmark items in a separate queue from your main library
• Sharing — generate public share links for tracks and albums
• JSON output on every command for scripting and agent use

Installation

npm install -g @lucaperret/tidal-cli

Requirements

• Node.js >= 20
• A Tidal account

Quick Start

# Sign in once — opens your browser
tidal-cli auth

# Search for a track
tidal-cli search track "Around the World"

# Get artist details
tidal-cli artist info 8992

# Play a track
tidal-cli playback play 5756235

Usage

Search

tidal-cli search artist "Gorillaz"
tidal-cli search album "Mezzanine"
tidal-cli search track "Teardrop"
tidal-cli search video "Stylo"
tidal-cli search playlist "Electronic"
tidal-cli search suggest "daft punk"
tidal-cli search editorial "indie rock"

Artist

tidal-cli artist info <id>
tidal-cli artist tracks <id>
tidal-cli artist albums <id>
tidal-cli artist similar <id>
tidal-cli artist radio <id>

Album & Track

tidal-cli album info <id>
tidal-cli album barcode <ean>
tidal-cli track info <id>
tidal-cli track similar <id>
tidal-cli track isrc <isrc>
tidal-cli track radio <id>

Playlists

tidal-cli playlist list
tidal-cli playlist create --name "Late Night Electronic"
tidal-cli playlist add-track --playlist-id <id> --track-id <id>
tidal-cli playlist add-album --playlist-id <id> --album-id <id>
tidal-cli playlist remove-track --playlist-id <id> --track-id <id>
tidal-cli playlist move-track --playlist-id <id> --track-id <id> --before <itemId>
tidal-cli playlist rename --playlist-id <id> --name "New Name"
tidal-cli playlist set-description --playlist-id <id> --desc "Updated description"
tidal-cli playlist delete --playlist-id <id>

Library

tidal-cli library add --track-id <id>
tidal-cli library add --artist-id <id>
tidal-cli library add --album-id <id>
tidal-cli library add --video-id <id>
tidal-cli library remove --track-id <id>
tidal-cli library favorite-playlists
tidal-cli library add-playlist --playlist-id <id>
tidal-cli library remove-playlist --playlist-id <id>

Discovery & History

tidal-cli recommend                              # all mix categories
tidal-cli recommend --type daily                 # daily | discovery | new-release | offline
tidal-cli mix items <mix-id> --type daily        # tracks inside a specific mix
tidal-cli history tracks
tidal-cli history albums
tidal-cli history artists
tidal-cli search history                         # your recent searches
tidal-cli search history-delete <entry-id>
tidal-cli search history-clear
tidal-cli user profile

Save for Later & Sharing

tidal-cli saved list
tidal-cli saved add --type tracks --id <id>      # tracks | albums | artists | playlists | videos
tidal-cli saved remove --type albums --id <id>
tidal-cli share track <id>                       # creates a public share link
tidal-cli share album <id>

Playback

tidal-cli playback play <id>
tidal-cli playback play <id> --quality LOSSLESS
tidal-cli playback info <id>
tidal-cli playback url <id>

Quality options: LOW, HIGH, LOSSLESS, HI_RES.

JSON Output

Add --json before any subcommand:

tidal-cli --json search track "Around the World"
tidal-cli --json playlist list
tidal-cli --json artist similar 8992

MCP Server (Claude Integration)

tidal-cli is available as a remote MCP server for Claude Desktop, Smithery, and any MCP-compatible client.

Connect in Claude Desktop:

1. Settings → Connectors → Add custom connector
2. Enter: https://tidal-cli.lucaperret.ch/api/mcp
3. Click "Connect" → log in to Tidal → done

40 tools with OAuth authentication, safety annotations, and 3 prompt templates.

Agent Automation

tidal-cli is also available as an OpenClaw skill on ClawHub. Install it for your AI agent:

clawhub install tidal-cli

After tidal-cli auth, agents can run commands non-interactively with auto-refreshing tokens.

Example prompts for your AI agent

• "Create a playlist with the best tracks from Daft Punk's Discovery album"
• "Find artists similar to Massive Attack and add their top tracks to my library"
• "What are my playlists? Add the new LCD Soundsystem album to the first one"
• "Play me something by Boards of Canada"
• "Build a 2000s indie rock playlist with The Strokes, Arctic Monkeys, and Interpol"

Scripting patterns

# Search then act
TRACK=$(tidal-cli --json search track "Around the World" | jq -r '.[0].id')
tidal-cli playlist add-track --playlist-id <id> --track-id "$TRACK"

# Discovery: artist → similar → top tracks → playlist
ARTIST=$(tidal-cli --json search artist "Boards of Canada" | jq -r '.[0].id')
SIMILAR=$(tidal-cli --json artist similar "$ARTIST" | jq -r '.[0].id')
TRACK=$(tidal-cli --json artist tracks "$SIMILAR" | jq -r '.[0].id')
tidal-cli playlist add-track --playlist-id <id> --track-id "$TRACK"

Development

git clone https://github.com/lucaperret/tidal-cli.git
cd tidal-cli
npm install
npm run build
npm test

Running Tests

npm test           # run once
npm run test:watch # watch mode

143 tests covering search, playlists, artists, tracks, albums, library, recommendations, mixes, save-for-later, sharing, search history, auth, and session.

License

tidal-cli is licensed under the MIT License. See the LICENSE file for details.