@lucaperret/tidal-cli 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luca Perret
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# tidal-cli
+
+<p align="center">
+  <a href="https://tidal-cli.lucaperret.ch">
+    <img src="https://tidal-cli.lucaperret.ch/banner" alt="tidal-cli — Control Tidal from your terminal" width="100%" />
+  </a>
+</p>
+
+[![npm](https://img.shields.io/npm/v/@lucaperret/tidal-cli)](https://www.npmjs.com/package/@lucaperret/tidal-cli)
+[![CI](https://img.shields.io/github/actions/workflow/status/lucaperret/tidal-cli/ci.yml?label=tests)](https://github.com/lucaperret/tidal-cli/actions)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-green.svg)](https://nodejs.org)
+
+## About
+
+tidal-cli wraps the [Tidal API v2](https://developer.tidal.com) 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](https://openclaw.ai).
+
+## 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 (My Mix, Discovery, New Arrivals)
+- **History** — recently added tracks, albums, artists
+- **JSON output** on every command for scripting and agent use
+
+## Installation
+
+```bash
+npm install -g @lucaperret/tidal-cli
+```
+
+### Requirements
+
+- Node.js >= 20
+- A [Tidal](https://tidal.com) account
+
+## Quick Start
+
+```bash
+# 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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+tidal-cli recommend
+tidal-cli history tracks
+tidal-cli history albums
+tidal-cli history artists
+tidal-cli user profile
+```
+
+### Playback
+
+```bash
+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:
+
+```bash
+tidal-cli --json search track "Around the World"
+tidal-cli --json playlist list
+tidal-cli --json artist similar 8992
+```
+
+## Agent Automation
+
+tidal-cli is available as an [OpenClaw](https://openclaw.ai) skill on [ClawHub](https://clawhub.ai/lucaperret/tidal-cli). Install it for your AI agent:
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+git clone https://github.com/lucaperret/tidal-cli.git
+cd tidal-cli
+npm install
+npm run build
+npm test
+```
+
+### Running Tests
+
+```bash
+npm test           # run once
+npm run test:watch # watch mode
+```
+
+111 tests covering search, playlists, artists, tracks, albums, library, auth, and session.
+
+## License
+
+tidal-cli is licensed under the MIT License. See the [`LICENSE`](LICENSE) file for details.

package/dist/album.d.ts

@@ -0,0 +1,2 @@
+export declare function getAlbumInfo(albumId: string, json: boolean): Promise<void>;
+export declare function getAlbumByBarcode(barcode: string, json: boolean): Promise<void>;

package/dist/album.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAlbumInfo = getAlbumInfo;
+exports.getAlbumByBarcode = getAlbumByBarcode;
+const auth_1 = require("./auth");
+function formatDuration(isoDuration) {
+    if (!isoDuration)
+        return '';
+    const match = isoDuration.match(/PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?/);
+    if (!match)
+        return isoDuration;
+    const h = match[1] ? `${match[1]}:` : '';
+    const m = (match[2] ?? '0').padStart(h ? 2 : 1, '0');
+    const s = (match[3] ?? '0').padStart(2, '0');
+    return `${h}${m}:${s}`;
+}
+async function getAlbumInfo(albumId, json) {
+    const client = await (0, auth_1.getApiClient)();
+    const { data, error } = await client.GET('/albums/{id}', {
+        params: {
+            path: { id: albumId },
+            query: {
+                countryCode: await (0, auth_1.getCountryCode)(),
+                include: ['artists', 'coverArt'],
+            },
+        },
+    });
+    if (error || !data) {
+        console.error(`Error: Failed to get album info — ${JSON.stringify(error)}`);
+        process.exit(1);
+    }
+    const attrs = data.data?.attributes ?? {};
+    const included = data.included ?? [];
+    const artists = included
+        .filter((item) => item.type === 'artists')
+        .map((item) => item.attributes?.name ?? item.id);
+    // Get cover art from included artworks
+    const artwork = included.find((item) => item.type === 'artworks');
+    const files = artwork?.attributes?.files ?? [];
+    const preferred = files.find((f) => f.meta?.width === 640) ?? files[0];
+    const coverUrl = preferred?.href;
+    const result = {
+        id: albumId,
+        title: attrs.title ?? 'Unknown',
+        artists,
+        albumType: attrs.albumType,
+        releaseDate: attrs.releaseDate,
+        numberOfItems: attrs.numberOfItems,
+        duration: formatDuration(attrs.duration),
+        popularity: attrs.popularity,
+        explicit: attrs.explicit,
+        barcodeId: attrs.barcodeId,
+        coverUrl,
+    };
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`\nAlbum: [${result.id}] ${result.title}`);
+    if (result.artists.length > 0)
+        console.log(`  Artists: ${result.artists.join(', ')}`);
+    if (result.albumType)
+        console.log(`  Type: ${result.albumType}`);
+    if (result.releaseDate)
+        console.log(`  Release Date: ${result.releaseDate}`);
+    if (result.numberOfItems !== undefined)
+        console.log(`  Tracks: ${result.numberOfItems}`);
+    if (result.duration)
+        console.log(`  Duration: ${result.duration}`);
+    if (result.popularity !== undefined)
+        console.log(`  Popularity: ${result.popularity}`);
+    if (result.explicit !== undefined)
+        console.log(`  Explicit: ${result.explicit}`);
+    if (result.barcodeId)
+        console.log(`  Barcode: ${result.barcodeId}`);
+    if (result.coverUrl)
+        console.log(`  Cover: ${result.coverUrl}`);
+    console.log();
+}
+async function getAlbumByBarcode(barcode, json) {
+    const client = await (0, auth_1.getApiClient)();
+    const { data, error } = await client.GET('/albums', {
+        params: {
+            query: {
+                countryCode: await (0, auth_1.getCountryCode)(),
+                'filter[barcodeId]': [barcode],
+            },
+        },
+    });
+    if (error || !data) {
+        console.error(`Error: Failed to get album by barcode — ${JSON.stringify(error)}`);
+        process.exit(1);
+    }
+    const items = data.data ?? [];
+    const albums = items.map((item) => {
+        const attrs = item.attributes;
+        return {
+            id: item.id,
+            title: attrs?.title ?? 'Unknown',
+            albumType: attrs?.albumType,
+            releaseDate: attrs?.releaseDate,
+            numberOfItems: attrs?.numberOfItems,
+            duration: formatDuration(attrs?.duration),
+            barcodeId: attrs?.barcodeId,
+        };
+    });
+    if (json) {
+        console.log(JSON.stringify(albums, null, 2));
+        return;
+    }
+    if (albums.length === 0) {
+        console.log(`No albums found for barcode ${barcode}.`);
+        return;
+    }
+    console.log(`\nAlbums matching barcode ${barcode}:\n`);
+    for (const a of albums) {
+        const extras = [a.albumType, a.releaseDate, a.numberOfItems !== undefined ? `${a.numberOfItems} tracks` : undefined]
+            .filter(Boolean)
+            .join(', ');
+        console.log(`  [${a.id}] ${a.title}${extras ? ` (${extras})` : ''}`);
+    }
+    console.log();
+}
+//# sourceMappingURL=album.js.map

package/dist/artist.d.ts

@@ -0,0 +1,5 @@
+export declare function getArtistInfo(artistId: string, json: boolean): Promise<void>;
+export declare function getArtistRadio(artistId: string, json: boolean): Promise<void>;
+export declare function getArtistTracks(artistId: string, json: boolean): Promise<void>;
+export declare function getArtistAlbums(artistId: string, json: boolean): Promise<void>;
+export declare function getSimilarArtists(artistId: string, json: boolean): Promise<void>;

package/dist/artist.js

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getArtistInfo = getArtistInfo;
+exports.getArtistRadio = getArtistRadio;
+exports.getArtistTracks = getArtistTracks;
+exports.getArtistAlbums = getArtistAlbums;
+exports.getSimilarArtists = getSimilarArtists;
+const auth_1 = require("./auth");
+function formatDuration(isoDuration) {
+    if (!isoDuration)
+        return '';
+    const match = isoDuration.match(/PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?/);
+    if (!match)
+        return isoDuration;
+    const h = match[1] ? `${match[1]}:` : '';
+    const m = (match[2] ?? '0').padStart(h ? 2 : 1, '0');
+    const s = (match[3] ?? '0').padStart(2, '0');
+    return `${h}${m}:${s}`;
+}
+async function getArtistInfo(artistId, json) {
+    const client = await (0, auth_1.getApiClient)();
+    const { data, error } = await client.GET('/artists/{id}', {
+        params: {
+            path: { id: artistId },
+            query: {
+                countryCode: await (0, auth_1.getCountryCode)(),
+                include: ['biography'],
+            },
+        },
+    });
+    if (error || !data) {
+        console.error(`Error: Failed to get artist info — ${JSON.stringify(error)}`);
+        process.exit(1);
+    }
+    const attrs = data.data?.attributes ?? {};
+    const included = data.included ?? [];
+    const biographyItem = included.find((item) => item.type === 'artistBiographies');
+    const biographyText = biographyItem?.attributes?.text ?? attrs.biography?.text ?? attrs.biography;
+    const result = {
+        id: artistId,
+        name: attrs.name ?? 'Unknown',
+        popularity: attrs.popularity,
+        handle: attrs.handle,
+        biography: biographyText,
+    };
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`\nArtist: [${result.id}] ${result.name}`);
+    if (result.handle)
+        console.log(`  Handle: ${result.handle}`);
+    if (result.popularity !== undefined)
+        console.log(`  Popularity: ${result.popularity}`);
+    if (result.biography)
+        console.log(`  Biography: ${result.biography}`);
+    console.log();
+}
+async function getArtistRadio(artistId, json) {
+    const client = await (0, auth_1.getApiClient)();
+    const { data, error } = await client.GET('/artists/{id}/relationships/radio', {
+        params: {
+            path: { id: artistId },
+            query: {
+                countryCode: await (0, auth_1.getCountryCode)(),
+                include: ['radio'],
+            },
+        },
+    });
+    if (error || !data) {
+        console.error(`Error: Failed to get artist radio — ${JSON.stringify(error)}`);
+        process.exit(1);
+    }
+    // Radio returns playlists (mix playlists), not individual tracks
+    const radioData = data.data ?? [];
+    const included = data.included ?? [];
+    const playlists = radioData.map((item) => {
+        const incl = included.find((i) => i.id === item.id && i.type === 'playlists');
+        const attrs = incl?.attributes ?? {};
+        return {
+            id: item.id,
+            type: item.type,
+            name: attrs.name,
+            numberOfItems: attrs.numberOfItems,
+            description: attrs.description,
+        };
+    });
+    if (json) {
+        console.log(JSON.stringify(playlists, null, 2));
+        return;
+    }
+    if (playlists.length === 0) {
+        console.log(`No radio found for artist ${artistId}.`);
+        return;
+    }
+    console.log(`\nRadio for artist ${artistId}:\n`);
+    for (const p of playlists) {
+        console.log(`  [${p.id}] ${p.name ?? 'Radio Mix'}${p.numberOfItems ? ` (${p.numberOfItems} tracks)` : ''}`);
+    }
+    console.log();
+}
+async function getArtistTracks(artistId, json) {
+    const client = await (0, auth_1.getApiClient)();
+    const { data, error } = await client.GET('/artists/{id}/relationships/tracks', {
+        params: {
+            path: { id: artistId },
+            query: {
+                countryCode: await (0, auth_1.getCountryCode)(),
+                'collapseBy': 'FINGERPRINT',
+                include: ['tracks'],
+            },
+        },
+    });
+    if (error || !data) {
+        console.error(`Error: Failed to get artist tracks — ${JSON.stringify(error)}`);
+        process.exit(1);
+    }
+    const included = data.included ?? [];
+    const tracks = included
+        .filter((item) => item.type === 'tracks')
+        .map((item) => {
+        const attrs = item.attributes;
+        return {
+            id: item.id,
+            title: attrs?.title ?? 'Unknown',
+            duration: attrs?.duration,
+            isrc: attrs?.isrc,
+            popularity: attrs?.popularity,
+        };
+    });
+    if (json) {
+        console.log(JSON.stringify(tracks, null, 2));
+        return;
+    }
+    if (tracks.length === 0) {
+        console.log(`No tracks found for artist ${artistId}.`);
+        return;
+    }
+    console.log(`\nTracks for artist ${artistId}:\n`);
+    for (const t of tracks) {
+        console.log(`  [${t.id}] ${t.title}${t.popularity !== undefined ? ` (popularity: ${t.popularity})` : ''}`);
+    }
+    console.log();
+}
+async function getArtistAlbums(artistId, json) {
+    const client = await (0, auth_1.getApiClient)();
+    const { data, error } = await client.GET('/artists/{id}/relationships/albums', {
+        params: {
+            path: { id: artistId },
+            query: {
+                countryCode: await (0, auth_1.getCountryCode)(),
+                include: ['albums'],
+            },
+        },
+    });
+    if (error || !data) {
+        console.error(`Error: Failed to get artist albums — ${JSON.stringify(error)}`);
+        process.exit(1);
+    }
+    const included = data.included ?? [];
+    const albums = included
+        .filter((item) => item.type === 'albums')
+        .map((item) => {
+        const attrs = item.attributes;
+        return {
+            id: item.id,
+            title: attrs?.title ?? 'Unknown',
+            albumType: attrs?.albumType,
+            releaseDate: attrs?.releaseDate,
+            numberOfItems: attrs?.numberOfItems,
+        };
+    });
+    if (json) {
+        console.log(JSON.stringify(albums, null, 2));
+        return;
+    }
+    if (albums.length === 0) {
+        console.log(`No albums found for artist ${artistId}.`);
+        return;
+    }
+    console.log(`\nAlbums for artist ${artistId}:\n`);
+    for (const a of albums) {
+        const extras = [a.albumType, a.releaseDate, a.numberOfItems !== undefined ? `${a.numberOfItems} tracks` : undefined]
+            .filter(Boolean)
+            .join(', ');
+        console.log(`  [${a.id}] ${a.title}${extras ? ` (${extras})` : ''}`);
+    }
+    console.log();
+}
+async function getSimilarArtists(artistId, json) {
+    const client = await (0, auth_1.getApiClient)();
+    const { data, error } = await client.GET('/artists/{id}/relationships/similarArtists', {
+        params: {
+            path: { id: artistId },
+            query: {
+                countryCode: await (0, auth_1.getCountryCode)(),
+                include: ['similarArtists'],
+            },
+        },
+    });
+    if (error || !data) {
+        console.error(`Error: Failed to get similar artists — ${JSON.stringify(error)}`);
+        process.exit(1);
+    }
+    const included = data.included ?? [];
+    const artists = included
+        .filter((item) => item.type === 'artists')
+        .map((item) => {
+        const attrs = item.attributes;
+        return {
+            id: item.id,
+            name: attrs?.name ?? 'Unknown',
+            popularity: attrs?.popularity,
+        };
+    });
+    if (json) {
+        console.log(JSON.stringify(artists, null, 2));
+        return;
+    }
+    if (artists.length === 0) {
+        console.log(`No similar artists found for artist ${artistId}.`);
+        return;
+    }
+    console.log(`\nSimilar artists to ${artistId}:\n`);
+    for (const a of artists) {
+        console.log(`  [${a.id}] ${a.name}${a.popularity !== undefined ? ` (popularity: ${a.popularity})` : ''}`);
+    }
+    console.log();
+}
+//# sourceMappingURL=artist.js.map

package/dist/auth.d.ts

@@ -0,0 +1,5 @@
+export declare function ensureInit(): Promise<void>;
+export declare function authenticate(): Promise<void>;
+export declare function getApiClient(): Promise<any>;
+export declare function getCountryCode(): Promise<string>;
+export declare function doLogout(): Promise<void>;