Related Pages

Related topics: System Architecture, Getting Started

Project Overview

tidal-cli is an open-source command-line interface tool that enables programmatic interaction with the Tidal music streaming service directly from the terminal. The project provides both a traditional CLI tool and an MCP (Model Context Protocol) server integration for AI agents.

Purpose and Scope

tidal-cli serves two primary use cases:

Sources: site/app/privacy/page.tsx:41-45

The tool is designed for personal use and LLM agent automation, allowing users to search tracks, manage playlists, control playback, discover new music, and interact with their music library without a web browser or desktop application.

High-Level Architecture

graph TD
    A[User / AI Agent] --> B[tidal-cli]
    B --> C{Mode}
    C -->|CLI Mode| D[Local Execution]
    C -->|MCP Mode| E[Remote Server]
    D --> F[Tidal API]
    E --> F
    F --> G[Tidal Servers]
    
    D -.-> H[~/.tidal-cli/session.json]
    E -.-> I[Upstash Redis - Encrypted]
    
    style F fill:#4a90d9
    style G fill:#ff6b6b

Sources: site/app/privacy/page.tsx:41-52

CLI Mode

When used as a command-line tool, tidal-cli communicates directly between your device and Tidal's API servers. No data passes through any intermediary server. Authentication tokens are stored locally on your device.

MCP Server Mode

When used as an MCP connector (e.g., through Claude Desktop or claude.ai), authentication tokens are stored server-side in an encrypted Redis database hosted on Upstash via Vercel.

Installation

Prerequisites

• Node.js environment
• Tidal account

Installation Commands

npm install -g @lucaperret/tidal-cli

# Sign in with your Tidal account
tidal-cli auth
Opening browser for Tidal authorization...
Authenticated successfully! User ID: 123456789

# Start exploring
tidal-cli search track "Teardrop"

Sources: site/app/page.tsx:101-115

Core Features

40 Available Tools

tidal-cli provides comprehensive coverage of Tidal's functionality across multiple domains:

Sources: site/app/page.tsx:17-21

Discovery & History Commands

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

Sources: README.md:1-10

Playback Commands

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

Sources: README.md:29-32

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>

Sources: README.md:22-26

JSON Output

All commands support structured JSON output by adding --json before any subcommand:

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

Sources: README.md:35-38

MCP Server Integration

AI Agent Support

tidal-cli is available as a remote MCP server for Claude Desktop and other MCP-compatible AI agents. This enables natural language control of Tidal through AI assistants.

graph LR
    A[User Prompt] --> B[Claude AI]
    B --> C[MCP Server]
    C --> D[tidal-cli]
    D --> E[Tidal API]

Setup for Claude Desktop

1. Add the connector URL: https://tidal-cli.lucaperret.ch/api/mcp
2. Connect your Tidal account through OAuth
3. Begin natural language interactions

Example AI Agent Prompts

Sources: site/app/page.tsx:67-78

Data Storage & Privacy

Local Storage (CLI Mode)

Authentication tokens are stored locally at:

~/.tidal-cli/session.json

Server Storage (MCP Mode)

For MCP server usage, authentication tokens are stored in:

• Database: Encrypted Redis database
• Provider: Upstash (via Vercel)

Data Flow

graph TD
    subgraph CLI_Mode["CLI Mode"]
        A1[Local Device] --> A2[~/.tidal-cli/session.json]
        A2 --> A3[Tidal API]
    end
    
    subgraph MCP_Mode["MCP Mode"]
        B1[Claude Desktop] --> B2[tidal-cli.lucaperret.ch]
        B2 --> B3[Upstash Redis]
        B3 --> B4[Tidal API]
    end

Third-Party Services

tidal-cli interacts with the following external services:

Sources: site/app/privacy/page.tsx:75-85

Legal & Licensing

• License: MIT License
• Disclaimer: tidal-cli is provided "as is" without warranty of any kind
• Affiliation: Not affiliated with TIDAL

Sources: site/app/terms/page.tsx:85-100

Key Source Files

Summary

tidal-cli bridges the gap between the Tidal music streaming service and terminal-based workflows or AI agents. With 40 available tools covering search, playlists, playback, discovery, and library management, it provides a comprehensive command-line interface for power users and enables sophisticated automation through MCP integration. The project is fully open source, allowing users to verify its behavior and contribute improvements.

Related Pages

Related topics: Project Overview, Authentication System, MCP Server Integration

System Architecture

Overview

tidal-cli is an open-source command-line interface tool that enables programmatic interaction with the Tidal music streaming service. The system architecture encompasses three primary components: a CLI client for terminal-based interactions, an MCP (Model Context Protocol) server for AI agent integration, and a Next.js web application for documentation and marketing.

The architecture is designed to support direct user interactions through the CLI, automated interactions through AI agents, and provides a web presence for onboarding and documentation. All components share core authentication and Tidal API integration logic.

Sources: README.md

High-Level Architecture

graph TD
    subgraph "Client Layer"
        CLI[tidal-cli CLI]
        MCP[MCP Server]
        WebApp[Next.js Web App]
    end

    subgraph "Integration Layer"
        AuthService[Authentication Service]
        APIClient[Tidal API Client]
    end

    subgraph "External Services"
        TidalAPI[Tidal API<br/>openapi.tidal.com]
        TidalAuth[Tidal Auth<br/>login.tidal.com<br/>auth.tidal.com]
    end

    subgraph "Data Storage"
        LocalStorage[~/.tidal-cli/session.json]
        Redis[(Redis/Upstash)]
    end

    CLI --> AuthService
    MCP --> AuthService
    AuthService --> TidalAuth
    APIClient --> TidalAPI
    CLI --> APIClient
    MCP --> APIClient
    CLI --> LocalStorage
    MCP --> Redis
    WebApp --> MCP

Sources: src/auth.ts, src/session.ts

Component Architecture

CLI Client

The CLI client (src/index.ts) is the primary interface for end users. It provides a command-based interface with subcommands for various operations.

Sources: README.md

MCP Server

The MCP server provides integration with AI agents, particularly Claude Desktop and claude.ai. It exposes the same functionality as the CLI through the Model Context Protocol.

graph LR
    A[Claude Desktop<br/>claude.ai] -->|MCP Protocol| B[tidal-cli MCP Server]
    B -->|API Requests| C[Tidal API]
    B -->|Auth Token| D[Redis/Upstash]

The MCP connector URL is available at https://tidal-cli.lucaperret.ch/api/mcp for remote server configuration.

Sources: site/app/page.tsx

Web Application

The Next.js web application (site/) serves multiple purposes:

Sources: site/app/layout.tsx

Authentication System

Authentication Flow

sequenceDiagram
    participant User
    participant CLI
    participant TidalAuth
    participant TidalAPI
    participant LocalStorage

    User->>CLI: tidal-cli auth
    CLI->>TidalAuth: Initiate OAuth
    TidalAuth->>User: Open browser
    User->>TidalAuth: Login credentials
    TidalAuth->>CLI: Authorization code
    CLI->>TidalAuth: Exchange for tokens
    TidalAuth->>CLI: Access token + Refresh token
    CLI->>LocalStorage: Store tokens (~/.tidal-cli/session.json)
    CLI->>TidalAPI: Authenticated requests

Token Storage

The system handles token storage differently based on the deployment mode:

Sources: src/auth.ts, site/app/privacy/page.tsx

Token Refresh

The authentication system includes automatic token refresh functionality:

• Access tokens have limited validity
• Refresh tokens are used to obtain new access tokens
• The CLI automatically handles token refresh before expiration
• MCP server manages token lifecycle server-side

Sources: src/session.ts

Data Flow

CLI Command Execution Flow

graph TD
    A[tidal-cli command] --> B[Parse arguments]
    B --> C[Load session/Authenticate]
    C --> D[Build API request]
    D --> E[Execute request to Tidal API]
    E --> F{JSON flag?}
    F -->|Yes| G[Format JSON output]
    F -->|No| H[Format human-readable output]
    G --> I[Return result]
    H --> I

Search Operation Flow

graph LR
    A[User input] -->|search track| B[CLI]
    B --> C[Tidal API<br/>openapi.tidal.com]
    C --> D[Parse response]
    D --> E[Display results]

Sources: README.md

External Dependencies

Tidal API Integration

Sources: site/app/privacy/page.tsx

NPM Dependencies (CLI Core)

Sources: src/package.json

Web Application Dependencies

Sources: site/package.json

CLI Command Structure

Command Hierarchy

tidal-cli
├── auth                    # OAuth authentication
├── search                  # Search operations
│   ├── artist
│   ├── album
│   ├── track
│   ├── video
│   ├── playlist
│   ├── suggest
│   ├── editorial
│   └── history
├── artist                  # Artist operations
│   ├── info
│   ├── tracks
│   ├── albums
│   ├── similar
│   └── radio
├── album                   # Album operations
│   ├── info
│   └── barcode
├── track                   # Track operations
│   ├── info
│   ├── similar
│   ├── isrc
│   └── radio
├── playlist                # Playlist operations
│   ├── list
│   ├── create
│   ├── add-track
│   ├── add-album
│   └── remove
├── playback                # Playback operations
│   ├── play
│   ├── info
│   └── url
├── library                 # Library operations
│   ├── add
│   └── favorite-playlists
├── saved                   # Save for later
│   ├── list
│   ├── add
│   └── remove
├── recommend               # Discovery
├── history                 # Listening history
├── user                    # User profile
├── share                   # Sharing
└── --json                  # Global JSON output flag

Sources: README.md

Quality Options

The system supports multiple audio quality settings for playback:

Sources: README.md

Project Structure

tidal-cli/
├── src/
│   ├── index.ts           # CLI entry point
│   ├── auth.ts            # Authentication logic
│   ├── session.ts         # Session management
│   └── ...
├── site/
│   ├── app/
│   │   ├── page.tsx       # Landing page
│   │   ├── layout.tsx     # Root layout
│   │   ├── terms/         # Terms page
│   │   ├── privacy/       # Privacy page
│   │   ├── api/           # API routes (MCP)
│   │   └── components/    # Reusable components
│   └── package.json
├── README.md
├── CLAUDE.md              # Developer documentation
└── package.json

Sources: CLAUDE.md

Security Considerations

Local CLI Usage

• Authentication tokens stored in ~/.tidal-cli/session.json
• Tokens never transmitted to external servers
• Direct communication with Tidal API

MCP Server Usage

• Tokens stored in encrypted Redis database (Upstash)
• Server-side token management
• Encrypted communication via HTTPS

Sources: site/app/privacy/page.tsx

Deployment Architecture

graph TD
    subgraph "Development"
        DevCLI[Local CLI]
        DevMCP[Local MCP Server]
    end

    subgraph "Production"
        ProdMCP[MCP Server<br/>Vercel]
        ProdWeb[Web App<br/>Vercel]
        Upstash[(Redis<br/>Upstash)]
    end

    subgraph "External"
        Tidal[Tidal API]
        Claude[Claude Desktop<br/>claude.ai]
    end

    DevCLI -->|OAuth| Tidal
    DevMCP -->|API| Tidal
    ProdMCP -->|Encrypted| Upstash
    ProdMCP -->|API| Tidal
    ProdWeb -->|MCP| ProdMCP
    Claude -->|MCP| ProdMCP

Summary

The tidal-cli system architecture provides three distinct interfaces to the Tidal music streaming service:

1. CLI Client: Direct terminal access with comprehensive command coverage
2. MCP Server: AI agent integration for automated workflows
3. Web Application: Documentation, marketing, and API endpoint hosting

The architecture prioritizes security through proper token management, offers flexibility through JSON output, and maintains compatibility with modern AI agent workflows through MCP protocol support.

Related Pages

Related topics: Project Overview, Authentication System

Getting Started

This guide covers everything you need to install, configure, and start using tidal-cli effectively.

Overview

tidal-cli is an open-source command-line tool that enables interaction with your Tidal music streaming account directly from the terminal. It supports searching the catalog, managing playlists, browsing your library, and controlling playback.

Sources: README.md

Prerequisites

Before installing tidal-cli, ensure your environment meets the following requirements:

Sources: site/app/page.tsx

Installation

Global npm Installation

The recommended installation method uses npm globally:

npm install -g @lucaperret/tidal-cli

Sources: site/app/page.tsx

Verify Installation

After installation, verify tidal-cli is properly installed:

tidal-cli --version

Initial Authentication

After installation, you must authenticate with your Tidal account:

tidal-cli auth

This command opens your default browser for OAuth authorization with Tidal. Once authenticated, your session tokens are stored locally.

Sources: README.md

Usage Flow

graph TD
    A[Install via npm] --> B[Run tidal-cli auth]
    B --> C[Browser Opens for OAuth]
    C --> D[Tidal Login]
    D --> E[Authorize Access]
    E --> F[Tokens Stored Locally]
    F --> G[Ready to Use]
    G --> H[Search, Playlists, Playback]

Quick Start Commands

After authentication, you can immediately start using tidal-cli:

Search

tidal-cli search track "Around the World"
tidal-cli search artist "Gorillaz"
tidal-cli search album "Mezzanine"
tidal-cli search video "Stylo"
tidal-cli search playlist "Electronic"

Get Information

tidal-cli artist info <id>
tidal-cli album info <id>
tidal-cli track info <id>
tidal-cli user profile

Playback

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

Sources: README.md

Quality Options

When playing tracks, you can specify audio quality:

JSON Output

All commands support JSON output for scripting and automation:

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

Session Storage

When using tidal-cli as a CLI tool, authentication tokens are stored locally:

~/.tidal-cli/session.json

Sources: site/app/privacy/page.tsx

Next Steps

Once you're comfortable with the basics, explore these advanced features:

• Playlists: Create and manage playlists with playlist create, playlist add-track
• Library: Browse and manage your library with library tracks, library favorite-artists
• Discovery: Get personalized recommendations with recommend and explore history tracks
• MCP Integration: Connect to Claude Desktop or AI agents for automated workflows

Troubleshooting

Installation Issues

If npm install fails, try:

npm install -g @lucaperret/tidal-cli --registry https://registry.npmjs.org/

Authentication Issues

If tidal-cli auth doesn't open a browser, ensure your default browser is configured correctly.

Data Deletion

To remove all locally stored data:

rm -rf ~/.tidal-cli

Sources: site/app/privacy/page.tsx

Related Pages

Related topics: CLI Commands - Search & Discovery, CLI Commands - Library & Playlist Management, CLI Commands - Playback System

CLI Commands - Core Modules

Overview

The tidal-cli project provides a comprehensive command-line interface for interacting with the Tidal music streaming service. The Core Modules encompass the essential functionality for searching, browsing, and managing music content including artists, albums, tracks, playlists, and playback control.

Architecture Overview

graph TD
    A[User CLI Input] --> B[tidal-cli CLI Engine]
    B --> C[Core Modules]
    C --> D[Search Module]
    C --> E[Artist Module]
    C --> F[Album Module]
    C --> G[Track Module]
    C --> H[Playlist Module]
    C --> I[Playback Module]
    C --> J[Library Module]
    D --> K[Tidal API]
    E --> K
    F --> K
    G --> K
    H --> K
    I --> K
    J --> K

Command Categories

The CLI organizes commands into functional modules as documented in the README:

Search Module

The search module provides comprehensive catalog searching capabilities.

Supported Search Types

tidal-cli search artist "<query>"           # Artist search
tidal-cli search album "<query>"           # Album search
tidal-cli search track "<query>"           # Track search
tidal-cli search video "<query>"           # Video search
tidal-cli search playlist "<query>"        # Playlist search
tidal-cli search suggest "<query>"         # Autocomplete suggestions
tidal-cli search editorial "<query>"       # Editorial content search

Search History Management

tidal-cli search history                   # View recent searches
tidal-cli search history-delete <entry-id> # Delete specific entry
tidal-cli search history-clear             # Clear all search history

Sources: README.md

Artist Module

Provides artist information and related content discovery.

Available Commands

Sources: README.md

Album & Track Modules

Album Commands

tidal-cli album info <id>        # Get album details
tidal-cli album barcode <ean>    # Lookup album by barcode/EAN

Track Commands

tidal-cli track info <id>        # Get track information
tidal-cli track similar <id>     # Find similar tracks
tidal-cli track isrc <isrc>      # Lookup track by ISRC
tidal-cli track radio <id>       # Generate track radio stream

Playlist Module

Full playlist management capabilities.

Core Operations

tidal-cli playlist list                                    # List all playlists
tidal-cli playlist create --name "<playlist-name>"         # Create new playlist
tidal-cli playlist add-track --playlist-id <id> --track-id <id>  # Add single track
tidal-cli playlist add-album --playlist-id <id>            # Add entire album

Sources: README.md

Playback Module

Handles track playback and stream URL retrieval.

Playback Commands

tidal-cli playback play <id>                     # Play track
tidal-cli playback play <id> --quality LOSSLESS  # Play with specific quality
tidal-cli playback info <id>                    # Get playback information
tidal-cli playback url <id>                     # Get stream URL

Quality Options

Discovery & History Module

Recommendations

tidal-cli recommend                              # All mix categories
tidal-cli recommend --type daily                 # Daily mixes
tidal-cli recommend --type discovery              # Discovery mixes
tidal-cli recommend --type new-release           # New releases
tidal-cli recommend --type offline                # Offline mixes
tidal-cli mix items <mix-id> --type daily        # Get tracks from specific mix

Listening History

tidal-cli history tracks   # View track listening history
tidal-cli history albums    # View album listening history
tidal-cli history artists   # View artist listening history

User Profile

tidal-cli user profile      # Display user profile information

Library Module

Manages user's personal library and saved content.

Saved Items

tidal-cli saved list                              # List saved items
tidal-cli saved add --type <type> --id <id>       # Add item to library
tidal-cli saved remove --type <type> --id <id>    # Remove from library

Supported Item Types

Favorites & Sharing

tidal-cli library add --track-id <id>            # Add track to library
tidal-cli library favorite-playlists             # List favorite playlists
tidal-cli share track <id>                        # Create public share link
tidal-cli share album <id>                        # Share album link

JSON Output

All commands support JSON output for programmatic use:

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

This enables integration with scripts and LLM agents for automation workflows.

CLI Options

Global Flags

Integration with MCP Server

The CLI supports MCP (Model Context Protocol) integration for AI agent use:

https://tidal-cli.lucaperret.ch/api/mcp

This enables Claude Desktop and other AI assistants to control Tidal programmatically.

Quick Start Commands

Based on the website documentation, the essential commands to get started are:

npm install -g @lucaperret/tidal-cli    # Installation
tidal-cli auth                           # OAuth authentication
tidal-cli search track "Teardrop"        # First search
tidal-cli artist info 8992               # Artist lookup (Daft Punk example)
tidal-cli playback play 5756235         # Playback

Requirements

• Node.js >= 20
• Valid Tidal account (Free, HiFi, or HiFi Plus)

Sources: site/app/page.tsx

Related Pages

Related topics: CLI Commands - Core Modules, CLI Commands - Library & Playlist Management

CLI Commands - Search & Discovery

The Search & Discovery module in tidal-cli provides comprehensive commands for exploring the Tidal music catalog, finding similar content, accessing personalized recommendations, and managing search history. This module forms the core navigation layer for users discovering music through the command-line interface.

Overview

The Search & Discovery functionality encompasses four primary areas:

These commands support JSON output via the --json flag for programmatic consumption, making tidal-cli suitable for LLM agent integration through the MCP server.

Catalog Search

The search command provides type-specific queries against the Tidal API, enabling precise discovery of artists, albums, tracks, videos, playlists, editorial content, and search suggestions.

Supported Search Types

tidal-cli search artist <query>
tidal-cli search album <query>
tidal-cli search track <query>
tidal-cli search video <query>
tidal-cli search playlist <query>
tidal-cli search suggest <query>
tidal-cli search editorial <query>

Search Type Reference

JSON Output

All search commands support structured JSON output:

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

This enables piping results to other tools or processing in automation scripts.

Discovery & Recommendations

The discovery system provides personalized content based on user listening patterns and algorithmic recommendations.

Mix Types

The recommend command accesses personalized mixes in various categories:

tidal-cli recommend                              # all mix categories
tidal-cli recommend --type daily                 # daily mix
tidal-cli recommend --type discovery             # discovery mix
tidal-cli recommend --type new-release           # new releases
tidal-cli recommend --type offline               # offline-ready tracks

Mix Reference Table

Exploring Mix Content

Each mix contains tracks that can be explored individually:

tidal-cli mix items <mix-id> --type daily

This command retrieves all tracks within a specific mix, allowing users to add individual tracks to playlists or play them directly.

Listening History

tidal-cli tracks your listening activity across different content types, enabling you to revisit recently played music.

History Commands

tidal-cli history tracks
tidal-cli history albums
tidal-cli history artists

History Flow Diagram

graph TD
    A[User plays content] --> B[Tidal API records play]
    B --> C[tidal-cli history command]
    C --> D{Content Type?}
    D -->|Tracks| E[Display recent tracks]
    D -->|Albums| F[Display recent albums]
    D -->|Artists| G[Display recent artists]
    E --> H[User can re-play or explore]
    F --> H
    G --> H

Search History Management

tidal-cli maintains a local search history that allows you to quickly access previous queries and clear them when needed.

Search History Commands

tidal-cli search history                         # display search history
tidal-cli search history-delete <entry-id>      # remove specific entry
tidal-cli search history-clear                   # clear all history

Search History Data Model

User Profile Integration

The user profile command provides context about your Tidal account, which influences search results and recommendations:

tidal-cli user profile

This command returns account information including subscription tier, preferred audio quality, and personalization settings that affect recommendation quality.

MCP Server Integration

The Search & Discovery functionality is exposed through the MCP (Model Context Protocol) server, enabling AI agents like Claude to perform music discovery tasks autonomously.

Available MCP Tools

The MCP server exposes the following discovery-related tools:

• search_artist - Search for artists
• search_track - Search for tracks
• search_album - Search for albums
• get_recommendations - Fetch personalized recommendations
• get_listening_history - Retrieve play history
• get_similar_artists - Find similar artists

Integration Example

User: "Find artists similar to Massive Attack and add their top tracks to my library"
Agent: Uses search_artist → similar_artist lookup → track lookup → library_add

Architecture Overview

graph TD
    subgraph "CLI Layer"
        A[User Command] --> B[Command Parser]
    end
    
    subgraph "Service Layer"
        B --> C[Search Service]
        B --> D[Recommend Service]
        B --> E[History Service]
    end
    
    subgraph "API Layer"
        C --> F[Tidal Search API]
        D --> G[Tidal Personalization API]
        E --> H[Tidal User History API]
    end
    
    subgraph "Output Layer"
        F --> I[Formatted Output]
        G --> I
        H --> I
        I --> J[JSON/Terminal]
    end

Best Practices

Efficient Searching

1. Use specific types: Prefer search track over broad searches when you know what you're looking for
2. Leverage JSON output: Use --json for scripting and automation
3. Build on history: Review your listening history to discover patterns

Recommendation Optimization

1. Regular usage improves recommendations: The system learns from your play history
2. Explore different mix types: Each mix type surfaces different content
3. Use discovery mix: The discovery type shows new content you haven't heard

Search History Management

1. Clear periodically: Use search history-clear to reset if results become biased
2. Delete specific entries: Remove individual entries with search history-delete <entry-id>

Error Handling

Common issues and resolutions:

Related Commands

• Playback Commands - Play discovered content
• Library Commands - Save and manage favorites
• Playlist Commands - Organize discovered music

References

• Search implementation: src/search.ts
• Recommendations: src/recommend.ts
• Mix functionality: src/mix.ts
• Search history: src/search-history.ts
• Usage examples: README.md

Related Pages

Related topics: CLI Commands - Core Modules, CLI Commands - Playback System

CLI Commands - Library & Playlist Management

Overview

The Library & Playlist Management commands in tidal-cli provide comprehensive tools for organizing your Tidal music library, managing playlists, tracking listening history, and sharing content. These commands enable users to interact programmatically with their personal Tidal account through a command-line interface designed for both manual use and LLM agent automation.

tidal-cli offers JSON output on every command, making it suitable for scripting and integration with other tools. The library management features allow adding or removing artists, albums, tracks, and videos from your favorites, while playlist commands support full CRUD operations including adding tracks and entire albums.

Architecture Overview

graph TD
    A[User / LLM Agent] --> B[tidal-cli CLI]
    B --> C{Library & Playlist Commands}
    
    C --> D[library]
    C --> E[playlist]
    C --> F[saved]
    C --> G[history]
    C --> H[share]
    
    D --> I[Tidal API]
    E --> I
    F --> I
    G --> I
    H --> I
    
    I --> J[User Library Data]
    I --> K[Playlist Data]
    I --> L[Share Links]

Library Commands

The library command group manages your personal Tidal library, including favorites for artists, albums, tracks, and videos.

Available Commands

Usage Examples

# Add a track to your library
tidal-cli library add --track-id 5756235

# Add an album to your library
tidal-cli library add --album-id 12345678

# Add an artist to your library
tidal-cli library add --artist-id 8992

# Remove a track from your library
tidal-cli library remove --type tracks --id 5756235

# List your favorite playlists
tidal-cli library favorite-playlists

JSON Output

All library commands support JSON output for programmatic use:

tidal-cli --json library add --track-id 5756235

Sources: README.md

Playlist Commands

The playlist command group provides complete playlist management capabilities including creation, modification, and deletion.

Available Commands

Usage Examples

# List all playlists
tidal-cli playlist list

# Create a new playlist
tidal-cli playlist create --name "Late Night Electronic"

# Add a track to a playlist
tidal-cli playlist add-track --playlist-id <playlist-id> --track-id <track-id>

# Add an entire album to a playlist
tidal-cli playlist add-album --playlist-id <playlist-id>

Playlist Workflow

graph LR
    A[Create Playlist] --> B[Get Playlist ID]
    B --> C[Add Tracks]
    C --> D[Add Albums]
    D --> E[Organize & Share]
    
    F[List Playlists] -.-> B
    G[Search Content] -.-> C

Sources: README.md Sources: site/app/page.tsx

Save for Later Commands

The saved command group manages your "Save for Later" queue, allowing you to bookmark content for future listening.

Available Commands

Supported Types

Usage Examples

# List all saved items
tidal-cli saved list

# Save a track for later
tidal-cli saved add --type tracks --id 5756235

# Save an album for later
tidal-cli saved add --type albums --id 12345678

# Remove a saved item
tidal-cli saved remove --type albums --id 12345678

Sources: README.md

History Commands

The history command group provides access to your listening history and search history.

Listening History

Search History

Usage Examples

# View your recent track history
tidal-cli history tracks

# View your recent album history
tidal-cli history albums

# View your recent artist history
tidal-cli history artists

# View search history
tidal-cli search history

# Delete a specific search entry
tidal-cli search history-delete <entry-id>

# Clear all search history
tidal-cli search history-clear

User Profile

tidal-cli user profile

This command displays your user profile information including subscription status and account details.

Sources: README.md

Share Commands

The share command group creates public share links for Tidal content.

Available Commands

Usage Examples

# Share a track
tidal-cli share track 5756235

# Share an album
tidal-cli share album 12345678

These commands generate public URLs that can be shared with others, allowing them to access the same content on Tidal.

Sources: README.md

Discovery & Recommendations

While not strictly library management, these commands help expand and organize your library through discovery.

Recommendation Commands

Similar Artists & Tracks

Usage Examples

# Get all recommendation categories
tidal-cli recommend

# Get daily mixes
tidal-cli recommend --type daily

# Get tracks from a specific mix
tidal-cli mix items <mix-id> --type daily

# Find similar artists
tidal-cli artist similar 8992

# Get artist radio station
tidal-cli artist radio 8992

Sources: README.md Sources: site/app/page.tsx

Command Reference Summary

Library Management

Playlist Management

Saved & History

Authentication Requirement

All Library & Playlist Management commands require authentication with your Tidal account. Run the following once to authenticate:

tidal-cli auth

This opens your browser for Tidal authorization. After initial authentication, all commands run non-interactively with auto-refreshing tokens.

Sources: site/app/page.tsx

Requirements

• Node.js >= 20
• A valid Tidal account (Free, HiFi, or HiFi Plus subscription)

See Also

• Search Commands - Finding content to add to your library
• Playback Commands - Playing tracks from your library
• Artist & Album Commands - Exploring the catalog

Related Pages

Related topics: CLI Commands - Core Modules, Authentication System

CLI Commands - Playback System

The Playback System is a core module in tidal-cli that enables programmatic control of Tidal audio playback from the command line. It provides commands to play tracks locally, retrieve stream URLs, and inspect playback quality information. This system is designed for both direct CLI usage and LLM agent automation workflows.

Architecture Overview

The Playback System integrates with Tidal's streaming infrastructure through the Tidal API, handling audio quality selection, stream URL generation, and local playback execution.

graph TD
    A["User Command<br>tidal-cli playback play <id>"] --> B["playback.ts<br>Command Handler"]
    B --> C["Tidal API<br>Audio Stream Endpoint"]
    C --> D["Stream URL<br>with Quality Parameters"]
    D --> E["Local Audio Player<br>System Default"]
    
    F["tidal-cli playback url <id>"] --> B
    G["tidal-cli playback info <id>"] --> B
    H["tidal-cli playback play <id> --quality LOSSLESS"] --> B

Playback Commands

playback play

Plays a track locally using the system's default audio player.

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

Parameters:

Supported Quality Levels:

Sources: README.md

playback url

Retrieves the direct stream URL for a track without playing it. This is useful for integration with external audio players or custom playback solutions.

tidal-cli playback url <id>

Sources: site/app/page.tsx

playback info

Returns detailed playback metadata for a track, including available quality options, codec information, and stream characteristics.

tidal-cli playback info <id>

Sources: site/app/page.tsx

JSON Output

All playback commands support structured JSON output for programmatic consumption:

tidal-cli playback play 5756235 --json
tidal-cli playback url 5756235 --json
tidal-cli playback info 5756235 --json

Sources: README.md

Integration with MCP Server

The playback system is exposed through the MCP (Model Context Protocol) connector, enabling AI agents like Claude to control Tidal playback:

https://tidal-cli.lucaperret.ch/api/mcp

This allows prompts such as:

"Play me something by Boards of Canada"

The AI agent interprets the request, searches for appropriate tracks, and executes the playback command programmatically.

Sources: site/app/page.tsx

Command Structure

The playback commands follow the standard tidal-cli architecture:

graph LR
    A["tidal-cli"] --> B["playback"]
    B --> C["play"]
    B --> D["url"]
    B --> E["info"]
    C --> F["Track ID"]
    C --> G["--quality flag"]

Typical Workflow Example

# 1. Search for a track
tidal-cli search track "Teardrop"

# 2. Get track details
tidal-cli track info 5756235

# 3. Play with default quality
tidal-cli playback play 5756235

# 4. Play with lossless quality
tidal-cli playback play 5756235 --quality LOSSLESS

# 5. Get stream URL for external player
tidal-cli playback url 5756235 --json

Quality Selection

The quality parameter allows explicit control over audio streaming quality:

# Play in highest available quality
tidal-cli playback play 5756235 --quality HI_RES

# Play lossless quality
tidal-cli playback play 5756235 --quality LOSSLESS

If no quality is specified, tidal-cli uses a sensible default based on your Tidal subscription level.

Error Handling

When a track ID is invalid or the track is unavailable, the CLI returns a structured error message:

{
  "error": "track_not_found",
  "message": "Track with ID 5756235 not found"
}

Source Files

Related Commands

Related Pages

Related topics: System Architecture, MCP Server Integration, Data Flow & Session Management

Authentication System

Overview

The tidal-cli project implements a dual-mode authentication system that supports both command-line interface (CLI) usage and Model Context Protocol (MCP) server integration with Claude Desktop. The authentication architecture is designed to securely handle OAuth tokens while maintaining flexibility for different deployment scenarios.

The system leverages Tidal's OAuth 2.0 flow for secure authentication, ensuring that user credentials are never stored or transmitted through tidal-cli's infrastructure. Instead, authentication tokens are exchanged between the user's browser and Tidal's auth servers, with only the resulting tokens being stored locally or server-side depending on the usage mode.

Architecture Overview

graph TD
    subgraph "CLI Mode"
        A1[User] -->|tidal-cli auth| B1[Local OAuth Flow]
        B1 --> C1[Tidal Login Page]
        C1 --> D1[Callback Server :25654]
        D1 --> E1[~/.tidal-cli/session.json]
    end
    
    subgraph "MCP Server Mode"
        A2[User] -->|Connect via MCP| B2[Remote OAuth Flow]
        B2 --> C2[Tidal Login Page]
        C2 --> D2[tidal-cli.lucaperret.ch /api/mcp]
        D2 --> E2[Upstash Redis Encrypted]
    end
    
    subgraph "API Access"
        E1 --> F1[Tidal API Client]
        E2 --> F2[Tidal API Client]
    end

Authentication Modes

CLI Mode

In CLI mode, tidal-cli performs a complete OAuth 2.0 authorization code flow with PKCE (Proof Key for Code Exchange) support. The process involves:

1. Starting a local HTTP server on port 25654 to receive the OAuth callback
2. Opening the user's default browser to Tidal's authorization page
3. Waiting for the user to authenticate with their Tidal credentials
4. Exchanging the authorization code for access and refresh tokens
5. Persisting tokens to the local session file

Token Storage Location: ~/.tidal-cli/session.json

Source: README.md | site/app/privacy/page.tsx

MCP Server Mode

When used as a remote MCP connector for Claude Desktop or claude.ai, the authentication flow differs in that tokens are stored server-side rather than locally. This enables seamless authentication across multiple devices without requiring local token management.

Token Storage Location: Upstash Redis (encrypted, 30-day TTL)

Source: site/app/privacy/page.tsx

Authentication Flow (CLI)

sequenceDiagram
    participant User
    participant CLI as tidal-cli CLI
    participant Browser as User's Browser
    participant Tidal as Tidal Auth Server
    participant Callback as Local Server :25654
    
    User->>CLI: tidal-cli auth
    CLI->>CLI: Generate PKCE verifier/challenge
    CLI->>Callback: Start local server
    CLI->>Browser: Open Tidal authorization URL
    User->>Browser: Enter Tidal credentials
    Browser->>Tidal: Authorization request with PKCE
    Tidal->>Browser: Authorization code
    Browser->>Callback: Redirect with code
    Callback->>CLI: Receive authorization code
    CLI->>Tidal: Exchange code for tokens
    Tidal->>CLI: Access token + Refresh token
    CLI->>CLI: Store tokens in session.json
    CLI->>User: "Authenticated successfully!"

Core Authentication Module

src/auth.ts

The primary authentication module provides several key functions for managing the authentication lifecycle:

#### Functions

#### getApiClient Implementation

export async function getApiClient(): Promise<any> {
  await ensureInit();

  // Verify we have valid credentials
  const creds = await credentialsProvider.getCredentials();
  if (!creds.token) {
    console.error('Error: Not authenticated. Run `tidal-cli auth` first.');
    process.exit(1);
  }

  return createAPIClient(credentialsProvider);
}

The getApiClient() function serves as the central entry point for all authenticated API operations. It first ensures the authentication subsystem is initialized, then verifies that valid credentials exist before constructing and returning an API client instance.

Source: src/auth.ts

#### getCountryCode Caching

let cachedCountryCode: string | null = null;

export async function getCountryCode(): Promise<string> {
  if (cachedCountryCode) return cachedCountryCode;

  try {
    const client = await getApiClient();
    const { data } = await client.GET('/users/{id}' as any, {
      // ... implementation
    });
    // ...
  }
}

The country code is retrieved from the user's profile and cached in memory to avoid repeated API calls for the same information.

Source: src/auth.ts

MCP Authentication Tools

User Profile Tool

The MCP server exposes authentication-related tools for Claude integration:

server.tool('tidal_user_profile', 'Get your Tidal user profile', {},
{ readOnlyHint: true, destructiveHint: false, openWorldHint: false, title: 'User Profile' },
async (_args, extra) => {
  const { client } = await getClientAndCountry(extractToken(extra));
  return text(await getUserProfileData(client));
});

Source: site/app/mcp-lib/tools.ts

Token Extraction

The MCP server extracts authentication tokens from incoming requests to establish authenticated sessions for Claude Desktop users. This allows the MCP server to associate API calls with the correct authenticated user.

Data Storage Comparison

Source: site/app/privacy/page.tsx

Security Considerations

Credential Handling

The authentication system implements several security measures:

1. PKCE Support: The OAuth flow uses Proof Key for Code Exchange to prevent authorization code interception attacks
2. Local-Only Storage (CLI): Authentication tokens never leave the user's device in CLI mode
3. Encrypted Storage (MCP): Server-side tokens are encrypted in Upstash Redis
4. No Password Storage: Username and password are never seen or stored by tidal-cli—authentication occurs directly with Tidal

Source: site/app/privacy/page.tsx

Data Deletion

Users can remove all locally stored authentication data by deleting the session directory:

rm -rf ~/.tidal-cli

For MCP mode, tokens expire automatically after 30 days and can be revoked from the user's Tidal account settings.

Source: site/app/privacy/page.tsx

Usage Examples

CLI Authentication

# Initiate authentication
tidal-cli auth
# Output: Opening browser for Tidal authorization...
# Output: Authenticated successfully! User ID: 123456789

# Verify authentication by querying profile
tidal-cli user profile

Source: README.md

MCP Server Setup

# MCP connector URL for Claude Desktop
https://tidal-cli.lucaperret.ch/api/mcp

Users configure this URL in Claude Desktop's Settings → Connectors → Add custom connector.

Source: site/app/page.tsx

Dependencies and Configuration

Required Environment

• Node.js: >= 20
• Tidal Account: Free, HiFi, or HiFi Plus subscription

Configuration Files

Related Documentation

• Privacy Policy - Detailed data handling practices
• Terms of Service - Usage terms and acceptable use
• GitHub Repository - Source code and issue tracking

Related Pages

Related topics: Authentication System, System Architecture

Data Flow & Session Management

tidal-cli operates in two distinct modes—CLI mode for direct command-line interaction and MCP mode for integration with AI agents like Claude Desktop. Each mode implements a different session management strategy tailored to its use case.

Architecture Overview

The system handles authentication differently depending on how users interact with tidal-cli:

Sources: site/app/privacy/page.tsx

graph TD
    subgraph CLI_Mode["CLI Mode"]
        A1[User Device] -->|OAuth| TIDAL_AUTH[Tidal Auth<br/>login.tidal.com]
        A1 -->|API Calls| TIDAL_API[Tidal API<br/>openapi.tidal.com]
        A1 -->|session.json| LOCAL[~/.tidal-cli/]
    end
    
    subgraph MCP_Mode["MCP Mode"]
        A2[Claude Desktop<br/>claude.ai] -->|MCP Protocol| MCP_ENDPOINT[https://tidal-cli.lucaperret.ch/api/mcp]
        MCP_ENDPOINT -->|Encrypted| REDIS[Upstash Redis<br/>Vercel]
        MCP_ENDPOINT -->|API Calls| TIDAL_API2[Tidal API<br/>openapi.tidal.com]
        A2 -->|OAuth| TIDAL_AUTH2[Tidal Auth<br/>login.tidal.com]
    end

CLI Mode Session Management

When using tidal-cli as a command-line tool, authentication tokens are stored locally on the user's device.

Storage Location

~/.tidal-cli/session.json

Sources: site/app/privacy/page.tsx

Session Data Flow

sequenceDiagram
    participant User as User Device
    participant CLI as tidal-cli CLI
    participant TIDAL as Tidal Auth API
    participant LOCAL as Local Storage<br/>~/.tidal-cli/

    User->>CLI: tidal-cli auth
    CLI->>TIDAL: Initiate OAuth flow
    TIDAL->>User: Open browser for login
    User->>TIDAL: Authenticate
    TIDAL-->>CLI: Authorization code
    CLI->>TIDAL: Exchange for tokens
    TIDAL-->>CLI: Access + Refresh tokens
    CLI->>LOCAL: Store in session.json
    Note over CLI,LOCAL: Tokens stored locally

Data Privacy in CLI Mode

• Direct communication: All API calls go directly from the user's device to Tidal's servers
• No intermediary: No data passes through any third-party server
• Local-only storage: Authentication tokens remain on the local filesystem
• User control: Users have full control over their session data

Sources: site/app/privacy/page.tsx

MCP Mode Session Management

When using tidal-cli as an MCP (Model Context Protocol) connector for AI agents, session management differs significantly due to the distributed nature of AI agent interactions.

MCP Endpoint Architecture

https://tidal-cli.lucaperret.ch/api/mcp

Sources: site/app/page.tsx

Session Data Flow

sequenceDiagram
    participant User as User/Claude Desktop
    participant Claude as Claude AI Agent
    participant Vercel as Vercel Edge<br/>MCP Server
    participant Redis as Upstash Redis<br/>Encrypted Storage
    participant TIDAL as Tidal API

    User->>Claude: Request music action
    Claude->>Vercel: MCP tool call
    Vercel->>Redis: Fetch/Store session
    Redis-->>Vercel: Encrypted tokens
    Vercel->>TIDAL: API request with token
    TIDAL-->>Vercel: Music data
    Vercel-->>Claude: MCP response
    Claude-->>User: Natural language response

Server-Side Token Storage

Sources: site/app/privacy/page.tsx

MCP Configuration Steps

Sources: site/app/page.tsx

Token Lifecycle

Token Refresh Mechanism

Both CLI and MCP modes implement automatic token refresh to maintain continuous access:

• CLI Mode: Token refresh handled locally by the CLI application
• MCP Mode: Token refresh managed server-side by the Vercel edge functions

Available Quality Options for Playback

Sources: README.md

Data Deletion

CLI Mode Deletion

To remove all locally stored data:

rm -rf ~/.tidal-cli

Sources: site/app/privacy/page.tsx

This command removes:

• session.json containing OAuth tokens
• Any cached session data

MCP Mode Revocation

For MCP mode, users can revoke tidal-cli's access directly from their Tidal account settings. This invalidates the server-stored tokens.

Additional Options

Sources: site/app/privacy/page.tsx

External Service Dependencies

Tidal Services

Third-Party Integrations

Sources: site/app/privacy/page.tsx

Security Considerations

CLI Mode

• Tokens stored in user-controlled filesystem
• Direct API communication without intermediaries
• User responsible for filesystem security

MCP Mode

• Tokens encrypted at rest in Upstash Redis
• Vercel edge infrastructure provides additional security layers
• Server-side token management reduces client-side exposure

Summary

tidal-cli implements a dual-mode session management strategy:

1. CLI Mode: Local token storage with direct Tidal API communication
2. MCP Mode: Server-side encrypted token storage for AI agent integration

The architecture prioritizes user privacy in CLI mode while enabling seamless AI agent interactions in MCP mode. All token management includes automatic refresh capabilities, and users retain full control over data deletion through local file removal or Tidal account settings revocation.

Related Pages

Related topics: Authentication System

MCP Server Integration

Overview

The MCP (Model Context Protocol) Server Integration enables tidal-cli to function as a remote MCP server, allowing AI assistants like Claude to interact with Tidal music accounts through a standardized protocol. This integration provides 40 tools for searching, playlist management, library access, recommendations, and playback control.

Architecture

graph TD
    subgraph "Client Side"
        Claude[Claude Desktop / claude.ai]
    end
    
    subgraph "tidal-cli Infrastructure"
        MCP_Endpoint["https://tidal-cli.lucaperret.ch/api/mcp"]
        Auth_Endpoint["https://tidal-cli.lucaperret.ch/api/authorize"]
        Callback["https://tidal-cli.lucaperret.ch/api/callback"]
        Token_API["https://tidal-cli.lucaperret.ch/api/token"]
    end
    
    subgraph "External Services"
        Tidal_API["Tidal API<br/>openapi.tidal.com"]
        Tidal_Auth["Tidal Auth<br/>login.tidal.com"]
        Redis[(Upstash Redis<br/>Token Storage)]
    end
    
    Claude -->|"MCP Protocol"| MCP_Endpoint
    MCP_Endpoint -->|OAuth Flow| Auth_Endpoint
    Auth_Endpoint -->|"Redirect"| Tidal_Auth
    Tidal_Auth -->|"Callback"| Callback
    Callback -->|Token Exchange| Token_API
    Token_API -->|Store/Retrieve| Redis
    MCP_Endpoint -->|API Requests| Tidal_API
    
    style Redis fill:#f9f,stroke:#333,stroke-width:2px
    style Tidal_API fill:#bbf,stroke:#333,stroke-width:2px
    style Tidal_Auth fill:#bbf,stroke:#333,stroke-width:2px

MCP Server Endpoint

The MCP endpoint is implemented as a Next.js route handler at site/app/api/mcp/route.ts. It handles the MCP protocol communication between clients and the Tidal API.

Connection URL

https://tidal-cli.lucaperret.ch/api/mcp

Supported Clients

Allowed Redirect URIs

The server validates incoming OAuth redirect URIs against an allowlist to prevent unauthorized callback origins:

const isAllowed =
    url.hostname.endsWith('.claude.ai') ||
    url.hostname === 'claude.ai' ||
    url.hostname.endsWith('.smithery.ai') ||
    url.hostname === 'smithery.run' ||
    url.hostname.endsWith('.smithery.run') ||
    url.hostname === 'localhost' ||
    url.hostname === '127.0.0.1';

Sources: site/app/api/authorize/route.ts

OAuth Authentication Flow

The MCP server uses OAuth Authorization Code with PKCE (Proof Key for Code Exchange) for secure authentication without exposing client secrets.

Authentication Sequence

sequenceDiagram
    participant Client as MCP Client
    participant Server as tidal-cli Server
    participant Tidal as Tidal Auth
    
    Client->>Server: GET /api/authorize?redirect_uri=...
    Server->>Server: Generate PKCE (code_verifier, code_challenge)
    Server->>Server: Generate session_id
    Server->>Redis: Store OAuth session with PKCE data
    Server->>Client: Redirect to Tidal login
    Client->>Tidal: User authenticates
    Tidal->>Server: Callback with auth code
    Server->>Tidal: Exchange code for tokens
    Server->>Redis: Store encrypted tokens (30-day TTL)
    Server->>Client: Redirect to original client

Session Storage

Privacy Note: No analytics, telemetry, or cookies are used. Tokens are encrypted at rest. Sources: site/app/privacy/page.tsx

API Endpoints

Authorization Endpoint

Route: GET/POST /api/authorize

Initiates the OAuth flow by redirecting users to Tidal's login page.

Query Parameters:

Process:

1. Validates redirect_uri against allowed origins
2. Generates PKCE code verifier and challenge
3. Creates session ID for state management
4. Stores session data in Redis
5. Redirects to Tidal authorization URL

Sources: site/app/api/authorize/route.ts

Callback Endpoint

Route: /api/callback

Handles the OAuth callback from Tidal after user authentication.

Process:

1. Receives authorization code from Tidal
2. Validates state parameter against stored session
3. Exchanges code for access/refresh tokens
4. Stores tokens in Redis with session data
5. Redirects user back to MCP client

Token Endpoint

Route: POST /api/token

Manages token operations including retrieval and refresh.

Operations:

MCP Tools (40 Total)

The MCP server exposes 40 tools organized into functional categories. Each tool includes safety annotations for AI assistants.

Sources: site/app/mcp-lib/tools.ts

Tool Categories

Tool Schema Example

Tools are defined using Zod schemas with safety annotations:

server.tool(
    'tidal_album_info',
    'Get album details including artists and cover art',
    {
        albumId: z.string().describe('Tidal album ID'),
    },
    {
        readOnlyHint: true,
        destructiveHint: false,
        openWorldHint: true,
        title: 'Album Info'
    },
    async ({ albumId }, extra) => {
        const { client, countryCode } = await getClientAndCountry(extractToken(extra));
        return text(await getAlbumInfoData(albumId, client, countryCode));
    }
);

Safety Annotations

Setup Instructions

Claude Desktop

`` https://tidal-cli.lucaperret.ch/api/mcp ``

1. Open Claude Desktop settings
2. Navigate to Connectors → Add custom connector
3. Enter the connector URL:
4. Click Connect and authenticate with Tidal

Sources: site/app/page.tsx

Smithery

Access via: https://smithery.ai/servers/lucaperret/tidal

Smithery automatically re-scans tools and prompts after deployment.

Data Flow

graph LR
    subgraph "Request Flow"
        A[MCP Request] --> B{Auth Check}
        B -->|Valid Token| C[Extract Token]
        B -->|Invalid/Missing| D[OAuth Flow]
        C --> E[Get Client & Country]
        E --> F[Call Tidal API]
        F --> G[Format Response]
        G --> H[MCP Response]
    end
    
    subgraph "Tool Categories"
        I[Search Tools]
        J[Playlist Tools]
        K[Library Tools]
        L[Playback Tools]
    end
    
    F --> I
    F --> J
    F --> K
    F --> L

Distribution Channels

Configuration Options

Environment Variables

Session Management

• Storage Location: Upstash Redis (encrypted)
• TTL: 30 days
• Encryption: AES-256 at rest
• Token Refresh: Automatic via credentials provider

Security Considerations

1. PKCE Required: All OAuth flows use Proof Key for Code Exchange
2. Redirect Validation: Strict allowlist for callback URIs
3. Token Encryption: OAuth tokens encrypted in Redis
4. No Client Secret: Uses public OAuth pattern
5. State Parameter: CSRF protection on all OAuth flows

Comparison: CLI vs MCP

Troubleshooting

Common Issues

Deployment Notes

After updating MCP tools or prompts:

1. Deploy changes to Vercel
2. Wait for auto-deploy completion
3. Smithery will automatically re-scan (if using Smithery)

Sources: CLAUDE.md

Doramagic Pitfall Log

Doramagic extracted 7 source-linked risk signals. Review them before installing or handing real data to the project.

1. Configuration risk: Configuration risk needs validation

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Configuration risk needs validation. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.host_targets | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | host_targets=mcp_host, claude

2. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | README/documentation is current enough for a first validation pass.

3. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | last_activity_observed missing

4. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium

5. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium

6. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | issue_or_pr_quality=unknown

7. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using tidal-cli with real data or production workflows.

• Configuration risk needs validation - GitHub / issue