{
"canonical_name": "lucaperret/tidal-cli",
"compilation_id": "pack_fd562f6b58584313ba1f95bb06be8096",
"created_at": "2026-05-19T06:23:58.808711+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npm install -g @lucaperret/tidal-cli` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npm install -g @lucaperret/tidal-cli",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_a016e44b36754805b88be903f4409b31"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_4a5ad214e747d2fa707cd8d0383b6cac",
"canonical_name": "lucaperret/tidal-cli",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/lucaperret/tidal-cli",
"slug": "tidal-cli",
"source_packet_id": "phit_2aa07bb71656456c80ea55ebfb6a9339",
"source_validation_id": "dval_96e5a3a8426245738a3d6af1675d094b"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 1,
"github_stars": 3,
"one_liner_en": "Control Tidal from your terminal — search, playlists, playback, library, and recommendations via the Tidal API v2. Ships as a CLI, a remote MCP server for Claude Desktop/Smithery, and an OpenClaw skill. Built for scripting, LLM agent automation, and AI workflows. TypeScript, MIT.",
"one_liner_zh": "Control Tidal from your terminal — search, playlists, playback, library, and recommendations via the Tidal API v2. Ships as a CLI, a remote MCP server for Claude Desktop/Smithery, and an OpenClaw skill. Built for scripting, LLM agent automation, and AI workflows. TypeScript, MIT.",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, api, server"
},
"target_user": "使用 mcp_host, claude 等宿主 AI 的用户",
"title_en": "tidal-cli",
"title_zh": "tidal-cli 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Natural-language Web Actions",
"label_zh": "自然语言网页操作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-natural-language-web-actions",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_2aa07bb71656456c80ea55ebfb6a9339",
"page_model": {
"artifacts": {
"artifact_slug": "tidal-cli",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npm install -g @lucaperret/tidal-cli",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/lucaperret/tidal-cli#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"节点式流程编排",
"评测体系"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Control Tidal from your terminal — search, playlists, playback, library, and recommendations via the Tidal API v2. Ships as a CLI, a remote MCP server for Claude Desktop/Smithery, and an OpenClaw skill. Built for scripting, LLM agent automation, and AI workflows. TypeScript, MIT."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | host_targets=mcp_host, claude"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 1,
"forks": 1,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 3
},
"source_url": "https://github.com/lucaperret/tidal-cli",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Control Tidal from your terminal — search, playlists, playback, library, and recommendations via the Tidal API v2. Ships as a CLI, a remote MCP server for Claude Desktop/Smithery, and an OpenClaw skill. Built for scripting, LLM agent automation, and AI workflows. TypeScript, MIT.",
"title": "tidal-cli 能力包",
"trial_prompt": "# tidal-cli - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for lucaperret/tidal-cli.\n\nProject:\n- Name: tidal-cli\n- Repository: https://github.com/lucaperret/tidal-cli\n- Summary: Control Tidal from your terminal — search, playlists, playback, library, and recommendations via the Tidal API v2. Ships as a CLI, a remote MCP server for Claude Desktop/Smithery, and an OpenClaw skill. Built for scripting, LLM agent automation, and AI workflows. TypeScript, MIT.\n- Host target: mcp_host, claude\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Control Tidal from your terminal — search, playlists, playback, library, and recommendations via the Tidal API v2. Ships as a CLI, a remote MCP server for Claude Desktop/Smithery, and an OpenClaw skill. Built for scripting, LLM agent automation, and AI workflows. TypeScript, MIT.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-project-overview: Project Overview. Produce one small intermediate artifact and wait for confirmation.\n2. page-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. page-getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n4. page-cli-commands: CLI Commands - Core Modules. Produce one small intermediate artifact and wait for confirmation.\n5. page-cli-commands-search: CLI Commands - Search & Discovery. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/lucaperret/tidal-cli\n- https://github.com/lucaperret/tidal-cli#readme\n- skills/tidal-cli/SKILL.md\n- README.md\n- CLAUDE.md\n- package.json\n- src/index.ts\n- src/session.ts\n- site/app/layout.tsx\n- site/package.json\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。",
"items": [],
"status": "待发现 Agent 补证",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "Control Tidal from your terminal — search, playlists, playback, library, and recommendations via the Tidal API v2. Ships as a CLI, a remote MCP server for Claude Desktop/Smithery, and an OpenClaw skill. Built for scripting, LLM agent automation, and AI workflows. TypeScript, MIT.",
"effort": "安装已验证",
"forks": 1,
"icon": "link",
"name": "tidal-cli 能力包",
"risk": "需复核",
"slug": "tidal-cli",
"stars": 3,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"节点式流程编排",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/lucaperret/tidal-cli 项目说明书\n\n生成时间：2026-05-16 11:20:21 UTC\n\n## 目录\n\n- [Project Overview](#page-project-overview)\n- [System Architecture](#page-architecture)\n- [Getting Started](#page-getting-started)\n- [CLI Commands - Core Modules](#page-cli-commands)\n- [CLI Commands - Search & Discovery](#page-cli-commands-search)\n- [CLI Commands - Library & Playlist Management](#page-cli-commands-library)\n- [CLI Commands - Playback System](#page-cli-commands-playback)\n- [Authentication System](#page-authentication)\n- [Data Flow & Session Management](#page-data-flow)\n- [MCP Server Integration](#page-mcp-server)\n\n\n\n## Project Overview\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Getting Started](#page-getting-started)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n- [site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx)\n- [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n \n\n# Project Overview\n\ntidal-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.\n\n## Purpose and Scope\n\ntidal-cli serves two primary use cases:\n\n| Use Case | Description |\n|----------|-------------|\n| **CLI Tool** | Direct terminal interaction with Tidal for personal music management |\n| **MCP Server** | AI agent integration for Claude Desktop and other MCP-compatible clients |\n\n资料来源：[site/app/privacy/page.tsx:41-45]()\n\nThe 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.\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n A[User / AI Agent] --> B[tidal-cli]\n B --> C{Mode}\n C -->|CLI Mode| D[Local Execution]\n C -->|MCP Mode| E[Remote Server]\n D --> F[Tidal API]\n E --> F\n F --> G[Tidal Servers]\n \n D -.-> H[~/.tidal-cli/session.json]\n E -.-> I[Upstash Redis - Encrypted]\n \n style F fill:#4a90d9\n style G fill:#ff6b6b\n```\n\n资料来源：[site/app/privacy/page.tsx:41-52]()\n\n### CLI Mode\n\nWhen 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.\n\n### MCP Server Mode\n\nWhen 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.\n\n## Installation\n\n### Prerequisites\n\n- Node.js environment\n- Tidal account\n\n### Installation Commands\n\n```bash\nnpm install -g @lucaperret/tidal-cli\n\n# Sign in with your Tidal account\ntidal-cli auth\nOpening browser for Tidal authorization...\nAuthenticated successfully! User ID: 123456789\n\n# Start exploring\ntidal-cli search track \"Teardrop\"\n```\n\n资料来源：[site/app/page.tsx:101-115]()\n\n## Core Features\n\n### 40 Available Tools\n\ntidal-cli provides comprehensive coverage of Tidal's functionality across multiple domains:\n\n| Category | Capabilities |\n|----------|-------------|\n| **Search** | Search tracks, albums, artists, playlists, videos |\n| **Playlists** | Create, rename, delete playlists; add/remove tracks and albums |\n| **Playback** | Play tracks locally, get stream URLs, inspect playback quality |\n| **Library** | Manage favorites, add/remove artists, albums, tracks, videos |\n| **Discovery** | Find similar artists/tracks, personalized recommendations |\n| **History** | View listening history, search history, recent tracks |\n| **Saved** | Save-for-later functionality, sharing via public links |\n\n资料来源：[site/app/page.tsx:17-21]()\n\n### Discovery & History Commands\n\n```bash\ntidal-cli recommend # all mix categories\ntidal-cli recommend --type daily # daily | discovery | new-release | offline\ntidal-cli mix items --type daily # tracks inside a specific mix\ntidal-cli history tracks\ntidal-cli history albums\ntidal-cli history artists\ntidal-cli search history # your recent searches\ntidal-cli search history-delete \ntidal-cli search history-clear\ntidal-cli user profile\n```\n\n资料来源：[README.md:1-10]()\n\n### Playback Commands\n\n```bash\ntidal-cli playback play \ntidal-cli playback play --quality LOSSLESS\ntidal-cli playback info \ntidal-cli playback url \n```\n\n**Quality Options:** `LOW`, `HIGH`, `LOSSLESS`, `HI_RES`\n\n资料来源：[README.md:29-32]()\n\n### Save for Later & Sharing\n\n```bash\ntidal-cli saved list\ntidal-cli saved add --type tracks --id # tracks | albums | artists | playlists | videos\ntidal-cli saved remove --type albums --id \ntidal-cli share track # creates a public share link\ntidal-cli share album \n```\n\n资料来源：[README.md:22-26]()\n\n## JSON Output\n\nAll commands support structured JSON output by adding `--json` before any subcommand:\n\n```bash\ntidal-cli --json search track \"Around the World\"\ntidal-cli --json playlist list\ntidal-cli --json artist similar 8992\n```\n\n资料来源：[README.md:35-38]()\n\n## MCP Server Integration\n\n### AI Agent Support\n\ntidal-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.\n\n```mermaid\ngraph LR\n A[User Prompt] --> B[Claude AI]\n B --> C[MCP Server]\n C --> D[tidal-cli]\n D --> E[Tidal API]\n```\n\n### Setup for Claude Desktop\n\n1. Add the connector URL: `https://tidal-cli.lucaperret.ch/api/mcp`\n2. Connect your Tidal account through OAuth\n3. Begin natural language interactions\n\n### Example AI Agent Prompts\n\n| Prompt | Action |\n|--------|--------|\n| \"Create a playlist with the best tracks from Daft Punk's Discovery album\" | Searches, creates playlist, adds tracks |\n| \"Find artists similar to Massive Attack and add their top tracks to my library\" | Discovers similar artists, adds to favorites |\n| \"What are my playlists? Add the new LCD Soundsystem album to the first one\" | Lists playlists, searches album, adds tracks |\n| \"Play me something by Boards of Canada\" | Searches, picks a track, plays it |\n| \"Build a 2000s indie rock playlist with The Strokes, Arctic Monkeys, and Interpol\" | Multi-step: create, search, add tracks |\n\n资料来源：[site/app/page.tsx:67-78]()\n\n## Data Storage & Privacy\n\n### Local Storage (CLI Mode)\n\nAuthentication tokens are stored locally at:\n\n```\n~/.tidal-cli/session.json\n```\n\n### Server Storage (MCP Mode)\n\nFor MCP server usage, authentication tokens are stored in:\n\n- **Database:** Encrypted Redis database\n- **Provider:** Upstash (via Vercel)\n\n### Data Flow\n\n```mermaid\ngraph TD\n subgraph CLI_Mode[\"CLI Mode\"]\n A1[Local Device] --> A2[~/.tidal-cli/session.json]\n A2 --> A3[Tidal API]\n end\n \n subgraph MCP_Mode[\"MCP Mode\"]\n B1[Claude Desktop] --> B2[tidal-cli.lucaperret.ch]\n B2 --> B3[Upstash Redis]\n B3 --> B4[Tidal API]\n end\n```\n\n## Third-Party Services\n\ntidal-cli interacts with the following external services:\n\n| Service | Purpose |\n|---------|---------|\n| **Tidal API** (openapi.tidal.com) | Music library, playlists, and catalog access |\n| **Tidal Auth** (login.tidal.com, auth.tidal.com) | OAuth authentication |\n\n资料来源：[site/app/privacy/page.tsx:75-85]()\n\n## Legal & Licensing\n\n- **License:** MIT License\n- **Disclaimer:** tidal-cli is provided \"as is\" without warranty of any kind\n- **Affiliation:** Not affiliated with TIDAL\n\n资料来源：[site/app/terms/page.tsx:85-100]()\n\n## Key Source Files\n\n| File | Purpose |\n|------|---------|\n| `src/auth.ts` | Authentication handling |\n| `site/app/page.tsx` | Landing page with feature documentation |\n| `site/app/privacy/page.tsx` | Privacy policy and data handling |\n| `site/app/terms/page.tsx` | Terms of service |\n| `README.md` | Command reference and quick start |\n\n## Summary\n\ntidal-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.\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Project Overview](#page-project-overview), [Authentication System](#page-authentication), [MCP Server Integration](#page-mcp-server)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CLAUDE.md](https://github.com/lucaperret/tidal-cli/blob/main/CLAUDE.md)\n- [src/index.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/index.ts)\n- [src/session.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/session.ts)\n- [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n- [site/app/layout.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/layout.tsx)\n- [site/package.json](https://github.com/lucaperret/tidal-cli/blob/main/site/package.json)\n \n\n# System Architecture\n\n## Overview\n\ntidal-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.\n\nThe 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.\n\n**资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)**\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n CLI[tidal-cli CLI]\n MCP[MCP Server]\n WebApp[Next.js Web App]\n end\n\n subgraph \"Integration Layer\"\n AuthService[Authentication Service]\n APIClient[Tidal API Client]\n end\n\n subgraph \"External Services\"\n TidalAPI[Tidal API
openapi.tidal.com]\n TidalAuth[Tidal Auth
login.tidal.com
auth.tidal.com]\n end\n\n subgraph \"Data Storage\"\n LocalStorage[~/.tidal-cli/session.json]\n Redis[(Redis/Upstash)]\n end\n\n CLI --> AuthService\n MCP --> AuthService\n AuthService --> TidalAuth\n APIClient --> TidalAPI\n CLI --> APIClient\n MCP --> APIClient\n CLI --> LocalStorage\n MCP --> Redis\n WebApp --> MCP\n```\n\n**资料来源：[src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts), [src/session.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/session.ts)**\n\n## Component Architecture\n\n### CLI Client\n\nThe CLI client (`src/index.ts`) is the primary interface for end users. It provides a command-based interface with subcommands for various operations.\n\n| Command Category | Description | Example |\n|-----------------|-------------|---------|\n| `search` | Search artists, albums, tracks, videos, playlists | `tidal-cli search track \"Teardrop\"` |\n| `artist` | Artist information and related content | `tidal-cli artist info 8992` |\n| `album` | Album details and metadata | `tidal-cli album info ` |\n| `track` | Track information and similar tracks | `tidal-cli track info ` |\n| `playlist` | Playlist management | `tidal-cli playlist list` |\n| `playback` | Playback control and stream URLs | `tidal-cli playback play 5756235` |\n| `library` | User library management | `tidal-cli library add --track-id ` |\n| `saved` | Save for later functionality | `tidal-cli saved list` |\n| `recommend` | Recommendations and discovery | `tidal-cli recommend` |\n| `history` | User listening history | `tidal-cli history tracks` |\n| `user` | User profile information | `tidal-cli user profile` |\n\n**资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)**\n\n### MCP Server\n\nThe 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.\n\n```mermaid\ngraph LR\n A[Claude Desktop
claude.ai] -->|MCP Protocol| B[tidal-cli MCP Server]\n B -->|API Requests| C[Tidal API]\n B -->|Auth Token| D[Redis/Upstash]\n```\n\nThe MCP connector URL is available at `https://tidal-cli.lucaperret.ch/api/mcp` for remote server configuration.\n\n**资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)**\n\n### Web Application\n\nThe Next.js web application (`site/`) serves multiple purposes:\n\n| Route | Purpose |\n|-------|---------|\n| `/` | Landing page with features, installation, and AI agent setup |\n| `/terms` | Terms of Service documentation |\n| `/privacy` | Privacy Policy documentation |\n| `/api/mcp` | MCP server endpoint |\n| `/og-banner` | Open Graph banner generation |\n| `/banner` | Social sharing banner |\n\n**资料来源：[site/app/layout.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/layout.tsx)**\n\n## Authentication System\n\n### Authentication Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant TidalAuth\n participant TidalAPI\n participant LocalStorage\n\n User->>CLI: tidal-cli auth\n CLI->>TidalAuth: Initiate OAuth\n TidalAuth->>User: Open browser\n User->>TidalAuth: Login credentials\n TidalAuth->>CLI: Authorization code\n CLI->>TidalAuth: Exchange for tokens\n TidalAuth->>CLI: Access token + Refresh token\n CLI->>LocalStorage: Store tokens (~/.tidal-cli/session.json)\n CLI->>TidalAPI: Authenticated requests\n```\n\n### Token Storage\n\nThe system handles token storage differently based on the deployment mode:\n\n| Deployment Mode | Storage Location | Description |\n|----------------|------------------|-------------|\n| CLI (local) | `~/.tidal-cli/session.json` | Local file storage on user's device |\n| MCP Server | Redis (Upstash) | Server-side encrypted storage |\n\n**资料来源：[src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts), [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)**\n\n### Token Refresh\n\nThe authentication system includes automatic token refresh functionality:\n\n- Access tokens have limited validity\n- Refresh tokens are used to obtain new access tokens\n- The CLI automatically handles token refresh before expiration\n- MCP server manages token lifecycle server-side\n\n**资料来源：[src/session.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/session.ts)**\n\n## Data Flow\n\n### CLI Command Execution Flow\n\n```mermaid\ngraph TD\n A[tidal-cli command] --> B[Parse arguments]\n B --> C[Load session/Authenticate]\n C --> D[Build API request]\n D --> E[Execute request to Tidal API]\n E --> F{JSON flag?}\n F -->|Yes| G[Format JSON output]\n F -->|No| H[Format human-readable output]\n G --> I[Return result]\n H --> I\n```\n\n### Search Operation Flow\n\n```mermaid\ngraph LR\n A[User input] -->|search track| B[CLI]\n B --> C[Tidal API
openapi.tidal.com]\n C --> D[Parse response]\n D --> E[Display results]\n```\n\n**资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)**\n\n## External Dependencies\n\n### Tidal API Integration\n\n| Endpoint | Purpose | Reference |\n|----------|---------|-----------|\n| `openapi.tidal.com` | Music catalog API | Search, metadata, playback |\n| `login.tidal.com` | Login interface | OAuth initiation |\n| `auth.tidal.com` | Token exchange | OAuth flow |\n\n**资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)**\n\n### NPM Dependencies (CLI Core)\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `tidal-api` | Latest | Tidal API client |\n| `commander` | Latest | CLI argument parsing |\n| `open` | Latest | Browser opening for auth |\n\n**资料来源：[src/package.json](https://github.com/lucaperret/tidal-cli/blob/main/package.json)**\n\n### Web Application Dependencies\n\n| Package | Purpose |\n|---------|---------|\n| `next` | React framework |\n| `react` | UI components |\n| `framer-motion` | Animations |\n| `@radix-ui` | UI primitives |\n\n**资料来源：[site/package.json](https://github.com/lucaperret/tidal-cli/blob/main/site/package.json)**\n\n## CLI Command Structure\n\n### Command Hierarchy\n\n```\ntidal-cli\n├── auth # OAuth authentication\n├── search # Search operations\n│ ├── artist\n│ ├── album\n│ ├── track\n│ ├── video\n│ ├── playlist\n│ ├── suggest\n│ ├── editorial\n│ └── history\n├── artist # Artist operations\n│ ├── info\n│ ├── tracks\n│ ├── albums\n│ ├── similar\n│ └── radio\n├── album # Album operations\n│ ├── info\n│ └── barcode\n├── track # Track operations\n│ ├── info\n│ ├── similar\n│ ├── isrc\n│ └── radio\n├── playlist # Playlist operations\n│ ├── list\n│ ├── create\n│ ├── add-track\n│ ├── add-album\n│ └── remove\n├── playback # Playback operations\n│ ├── play\n│ ├── info\n│ └── url\n├── library # Library operations\n│ ├── add\n│ └── favorite-playlists\n├── saved # Save for later\n│ ├── list\n│ ├── add\n│ └── remove\n├── recommend # Discovery\n├── history # Listening history\n├── user # User profile\n├── share # Sharing\n└── --json # Global JSON output flag\n```\n\n**资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)**\n\n## Quality Options\n\nThe system supports multiple audio quality settings for playback:\n\n| Quality | Description |\n|---------|-------------|\n| `LOW` | Lowest quality streaming |\n| `HIGH` | High quality streaming |\n| `LOSSLESS` | Lossless audio (FLAC) |\n| `HI_RES` | High resolution audio |\n\n**资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)**\n\n## Project Structure\n\n```\ntidal-cli/\n├── src/\n│ ├── index.ts # CLI entry point\n│ ├── auth.ts # Authentication logic\n│ ├── session.ts # Session management\n│ └── ...\n├── site/\n│ ├── app/\n│ │ ├── page.tsx # Landing page\n│ │ ├── layout.tsx # Root layout\n│ │ ├── terms/ # Terms page\n│ │ ├── privacy/ # Privacy page\n│ │ ├── api/ # API routes (MCP)\n│ │ └── components/ # Reusable components\n│ └── package.json\n├── README.md\n├── CLAUDE.md # Developer documentation\n└── package.json\n```\n\n**资料来源：[CLAUDE.md](https://github.com/lucaperret/tidal-cli/blob/main/CLAUDE.md)**\n\n## Security Considerations\n\n### Local CLI Usage\n\n- Authentication tokens stored in `~/.tidal-cli/session.json`\n- Tokens never transmitted to external servers\n- Direct communication with Tidal API\n\n### MCP Server Usage\n\n- Tokens stored in encrypted Redis database (Upstash)\n- Server-side token management\n- Encrypted communication via HTTPS\n\n**资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)**\n\n## Deployment Architecture\n\n```mermaid\ngraph TD\n subgraph \"Development\"\n DevCLI[Local CLI]\n DevMCP[Local MCP Server]\n end\n\n subgraph \"Production\"\n ProdMCP[MCP Server
Vercel]\n ProdWeb[Web App
Vercel]\n Upstash[(Redis
Upstash)]\n end\n\n subgraph \"External\"\n Tidal[Tidal API]\n Claude[Claude Desktop
claude.ai]\n end\n\n DevCLI -->|OAuth| Tidal\n DevMCP -->|API| Tidal\n ProdMCP -->|Encrypted| Upstash\n ProdMCP -->|API| Tidal\n ProdWeb -->|MCP| ProdMCP\n Claude -->|MCP| ProdMCP\n```\n\n## Summary\n\nThe tidal-cli system architecture provides three distinct interfaces to the Tidal music streaming service:\n\n1. **CLI Client**: Direct terminal access with comprehensive command coverage\n2. **MCP Server**: AI agent integration for automated workflows\n3. **Web Application**: Documentation, marketing, and API endpoint hosting\n\nThe architecture prioritizes security through proper token management, offers flexibility through JSON output, and maintains compatibility with modern AI agent workflows through MCP protocol support.\n\n---\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[Project Overview](#page-project-overview), [Authentication System](#page-authentication)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n \n\n# Getting Started\n\nThis guide covers everything you need to install, configure, and start using tidal-cli effectively.\n\n## Overview\n\ntidal-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.\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Prerequisites\n\nBefore installing tidal-cli, ensure your environment meets the following requirements:\n\n| Requirement | Minimum Version | Description |\n|-------------|-----------------|-------------|\n| Node.js | >= 20 | JavaScript runtime required to execute the CLI |\n| npm | Latest | Node package manager (bundled with Node.js) |\n| Tidal Account | Any tier | Free, HiFi, or HiFi Plus subscription |\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## Installation\n\n### Global npm Installation\n\nThe recommended installation method uses npm globally:\n\n```bash\nnpm install -g @lucaperret/tidal-cli\n```\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n### Verify Installation\n\nAfter installation, verify tidal-cli is properly installed:\n\n```bash\ntidal-cli --version\n```\n\n## Initial Authentication\n\nAfter installation, you must authenticate with your Tidal account:\n\n```bash\ntidal-cli auth\n```\n\nThis command opens your default browser for OAuth authorization with Tidal. Once authenticated, your session tokens are stored locally.\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Usage Flow\n\n```mermaid\ngraph TD\n A[Install via npm] --> B[Run tidal-cli auth]\n B --> C[Browser Opens for OAuth]\n C --> D[Tidal Login]\n D --> E[Authorize Access]\n E --> F[Tokens Stored Locally]\n F --> G[Ready to Use]\n G --> H[Search, Playlists, Playback]\n```\n\n## Quick Start Commands\n\nAfter authentication, you can immediately start using tidal-cli:\n\n### Search\n\n```bash\ntidal-cli search track \"Around the World\"\ntidal-cli search artist \"Gorillaz\"\ntidal-cli search album \"Mezzanine\"\ntidal-cli search video \"Stylo\"\ntidal-cli search playlist \"Electronic\"\n```\n\n### Get Information\n\n```bash\ntidal-cli artist info \ntidal-cli album info \ntidal-cli track info \ntidal-cli user profile\n```\n\n### Playback\n\n```bash\ntidal-cli playback play \ntidal-cli playback play --quality LOSSLESS\ntidal-cli playback info \n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Quality Options\n\nWhen playing tracks, you can specify audio quality:\n\n| Quality | Description |\n|---------|-------------|\n| `LOW` | Standard quality |\n| `HIGH` | High quality |\n| `LOSSLESS` | Lossless/CD quality |\n| `HI_RES` | Hi-Res audio |\n\n## JSON Output\n\nAll commands support JSON output for scripting and automation:\n\n```bash\ntidal-cli --json search track \"Around the World\"\ntidal-cli --json playlist list\ntidal-cli --json artist similar 8992\n```\n\n## Session Storage\n\nWhen using tidal-cli as a CLI tool, authentication tokens are stored locally:\n\n```\n~/.tidal-cli/session.json\n```\n\n资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n## Next Steps\n\nOnce you're comfortable with the basics, explore these advanced features:\n\n- **Playlists**: Create and manage playlists with `playlist create`, `playlist add-track`\n- **Library**: Browse and manage your library with `library tracks`, `library favorite-artists`\n- **Discovery**: Get personalized recommendations with `recommend` and explore `history tracks`\n- **MCP Integration**: Connect to Claude Desktop or AI agents for automated workflows\n\n## Troubleshooting\n\n### Installation Issues\n\nIf npm install fails, try:\n```bash\nnpm install -g @lucaperret/tidal-cli --registry https://registry.npmjs.org/\n```\n\n### Authentication Issues\n\nIf `tidal-cli auth` doesn't open a browser, ensure your default browser is configured correctly.\n\n### Data Deletion\n\nTo remove all locally stored data:\n```bash\nrm -rf ~/.tidal-cli\n```\n\n资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n---\n\n\n\n## CLI Commands - Core Modules\n\n### 相关页面\n\n相关主题：[CLI Commands - Search & Discovery](#page-cli-commands-search), [CLI Commands - Library & Playlist Management](#page-cli-commands-library), [CLI Commands - Playback System](#page-cli-commands-playback)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) - CLI命令文档和用法说明\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx) - 网站首页，展示CLI功能\n \n\n# CLI Commands - Core Modules\n\n## Overview\n\nThe 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.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[User CLI Input] --> B[tidal-cli CLI Engine]\n B --> C[Core Modules]\n C --> D[Search Module]\n C --> E[Artist Module]\n C --> F[Album Module]\n C --> G[Track Module]\n C --> H[Playlist Module]\n C --> I[Playback Module]\n C --> J[Library Module]\n D --> K[Tidal API]\n E --> K\n F --> K\n G --> K\n H --> K\n I --> K\n J --> K\n```\n\n## Command Categories\n\nThe CLI organizes commands into functional modules as documented in the README:\n\n| Category | Primary Module | Key Capabilities |\n|----------|----------------|-------------------|\n| Search | `search` | Track, album, artist, video, playlist, suggestions |\n| Artists | `artist` | Info, tracks, albums, similar artists, radio |\n| Albums | `album` | Info, barcode lookup |\n| Tracks | `track` | Info, similar tracks, ISRC lookup, radio |\n| Playlists | `playlist` | List, create, add/remove tracks, add albums |\n| Playback | `playback` | Play, info, URL retrieval, quality control |\n| Library | `library` | Favorites management, history tracking |\n| Discovery | `recommend`, `history` | Personalized recommendations, listening history |\n\n## Search Module\n\nThe search module provides comprehensive catalog searching capabilities.\n\n### Supported Search Types\n\n```bash\ntidal-cli search artist \"\" # Artist search\ntidal-cli search album \"\" # Album search\ntidal-cli search track \"\" # Track search\ntidal-cli search video \"\" # Video search\ntidal-cli search playlist \"\" # Playlist search\ntidal-cli search suggest \"\" # Autocomplete suggestions\ntidal-cli search editorial \"\" # Editorial content search\n```\n\n### Search History Management\n\n```bash\ntidal-cli search history # View recent searches\ntidal-cli search history-delete # Delete specific entry\ntidal-cli search history-clear # Clear all search history\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Artist Module\n\nProvides artist information and related content discovery.\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `tidal-cli artist info ` | Get detailed artist information |\n| `tidal-cli artist tracks ` | List artist's tracks |\n| `tidal-cli artist albums ` | List artist's albums |\n| `tidal-cli artist similar ` | Find similar artists |\n| `tidal-cli artist radio ` | Generate artist radio stream |\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Album & Track Modules\n\n### Album Commands\n\n```bash\ntidal-cli album info # Get album details\ntidal-cli album barcode # Lookup album by barcode/EAN\n```\n\n### Track Commands\n\n```bash\ntidal-cli track info # Get track information\ntidal-cli track similar # Find similar tracks\ntidal-cli track isrc # Lookup track by ISRC\ntidal-cli track radio # Generate track radio stream\n```\n\n## Playlist Module\n\nFull playlist management capabilities.\n\n### Core Operations\n\n```bash\ntidal-cli playlist list # List all playlists\ntidal-cli playlist create --name \"\" # Create new playlist\ntidal-cli playlist add-track --playlist-id --track-id # Add single track\ntidal-cli playlist add-album --playlist-id # Add entire album\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Playback Module\n\nHandles track playback and stream URL retrieval.\n\n### Playback Commands\n\n```bash\ntidal-cli playback play # Play track\ntidal-cli playback play --quality LOSSLESS # Play with specific quality\ntidal-cli playback info # Get playback information\ntidal-cli playback url # Get stream URL\n```\n\n### Quality Options\n\n| Quality | Description |\n|---------|-------------|\n| `LOW` | Standard quality streaming |\n| `HIGH` | High quality streaming |\n| `LOSSLESS` | Lossless audio (FLAC) |\n| `HI_RES` | Hi-Res audio quality |\n\n## Discovery & History Module\n\n### Recommendations\n\n```bash\ntidal-cli recommend # All mix categories\ntidal-cli recommend --type daily # Daily mixes\ntidal-cli recommend --type discovery # Discovery mixes\ntidal-cli recommend --type new-release # New releases\ntidal-cli recommend --type offline # Offline mixes\ntidal-cli mix items --type daily # Get tracks from specific mix\n```\n\n### Listening History\n\n```bash\ntidal-cli history tracks # View track listening history\ntidal-cli history albums # View album listening history\ntidal-cli history artists # View artist listening history\n```\n\n### User Profile\n\n```bash\ntidal-cli user profile # Display user profile information\n```\n\n## Library Module\n\nManages user's personal library and saved content.\n\n### Saved Items\n\n```bash\ntidal-cli saved list # List saved items\ntidal-cli saved add --type --id # Add item to library\ntidal-cli saved remove --type --id # Remove from library\n```\n\n### Supported Item Types\n\n| Type | Description |\n|------|-------------|\n| `tracks` | Saved tracks |\n| `albums` | Saved albums |\n| `artists` | Favorite artists |\n| `playlists` | Saved playlists |\n| `videos` | Saved videos |\n\n### Favorites & Sharing\n\n```bash\ntidal-cli library add --track-id # Add track to library\ntidal-cli library favorite-playlists # List favorite playlists\ntidal-cli share track # Create public share link\ntidal-cli share album # Share album link\n```\n\n## JSON Output\n\nAll commands support JSON output for programmatic use:\n\n```bash\ntidal-cli --json search track \"Around the World\"\ntidal-cli --json playlist list\ntidal-cli --json artist similar 8992\n```\n\nThis enables integration with scripts and LLM agents for automation workflows.\n\n## CLI Options\n\n### Global Flags\n\n| Flag | Description |\n|------|-------------|\n| `--json` | Output results as JSON |\n| `--help` | Display command help |\n| `--version` | Show CLI version |\n\n## Integration with MCP Server\n\nThe CLI supports MCP (Model Context Protocol) integration for AI agent use:\n\n```\nhttps://tidal-cli.lucaperret.ch/api/mcp\n```\n\nThis enables Claude Desktop and other AI assistants to control Tidal programmatically.\n\n## Quick Start Commands\n\nBased on the website documentation, the essential commands to get started are:\n\n```bash\nnpm install -g @lucaperret/tidal-cli # Installation\ntidal-cli auth # OAuth authentication\ntidal-cli search track \"Teardrop\" # First search\ntidal-cli artist info 8992 # Artist lookup (Daft Punk example)\ntidal-cli playback play 5756235 # Playback\n```\n\n## Requirements\n\n- Node.js >= 20\n- Valid Tidal account (Free, HiFi, or HiFi Plus)\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n---\n\n\n\n## CLI Commands - Search & Discovery\n\n### 相关页面\n\n相关主题：[CLI Commands - Core Modules](#page-cli-commands), [CLI Commands - Library & Playlist Management](#page-cli-commands-library)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [src/search.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/search.ts)\n- [src/recommend.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/recommend.ts)\n- [src/mix.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/mix.ts)\n- [src/search-history.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/search-history.ts)\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n \n\n# CLI Commands - Search & Discovery\n\nThe 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.\n\n## Overview\n\nThe Search & Discovery functionality encompasses four primary areas:\n\n| Category | Purpose | Entry Point |\n|----------|---------|-------------|\n| **Catalog Search** | Query Tidal's music database by type | `tidal-cli search` |\n| **Discovery** | Access personalized mixes and recommendations | `tidal-cli recommend` |\n| **Listening History** | View recently played content | `tidal-cli history` |\n| **Search History** | Manage personal search activity | `tidal-cli search history` |\n\nThese commands support JSON output via the `--json` flag for programmatic consumption, making tidal-cli suitable for LLM agent integration through the MCP server.\n\n## Catalog Search\n\nThe `search` command provides type-specific queries against the Tidal API, enabling precise discovery of artists, albums, tracks, videos, playlists, editorial content, and search suggestions.\n\n### Supported Search Types\n\n```bash\ntidal-cli search artist \ntidal-cli search album \ntidal-cli search track \ntidal-cli search video \ntidal-cli search playlist \ntidal-cli search suggest \ntidal-cli search editorial \n```\n\n### Search Type Reference\n\n| Type | Description | Use Case |\n|------|-------------|----------|\n| `artist` | Find artists by name | \"Who is the best artist for this sound?\" |\n| `album` | Locate albums by title | \"Find all albums by this artist\" |\n| `track` | Search individual songs | \"Play me something similar\" |\n| `video` | Find music videos | \"Watch the official video\" |\n| `playlist` | Discover user playlists | \"Find playlists for parties\" |\n| `suggest` | Get search suggestions | Autocomplete functionality |\n| `editorial` | Browse curated editorial lists | \"What's trending in indie rock?\" |\n\n### JSON Output\n\nAll search commands support structured JSON output:\n\n```bash\ntidal-cli --json search track \"Around the World\"\ntidal-cli --json artist similar 8992\n```\n\nThis enables piping results to other tools or processing in automation scripts.\n\n## Discovery & Recommendations\n\nThe discovery system provides personalized content based on user listening patterns and algorithmic recommendations.\n\n### Mix Types\n\nThe `recommend` command accesses personalized mixes in various categories:\n\n```bash\ntidal-cli recommend # all mix categories\ntidal-cli recommend --type daily # daily mix\ntidal-cli recommend --type discovery # discovery mix\ntidal-cli recommend --type new-release # new releases\ntidal-cli recommend --type offline # offline-ready tracks\n```\n\n### Mix Reference Table\n\n| Type | Description | Refresh Frequency |\n|------|-------------|-------------------|\n| `daily` | Your daily personalized mix | Daily |\n| `discovery` | Tracks you've never listened to but might like | Weekly |\n| `new-release` | Recent releases matching your taste | Daily |\n| `offline` | Tracks optimized for offline playback | Dynamic |\n\n### Exploring Mix Content\n\nEach mix contains tracks that can be explored individually:\n\n```bash\ntidal-cli mix items --type daily\n```\n\nThis command retrieves all tracks within a specific mix, allowing users to add individual tracks to playlists or play them directly.\n\n## Listening History\n\ntidal-cli tracks your listening activity across different content types, enabling you to revisit recently played music.\n\n### History Commands\n\n```bash\ntidal-cli history tracks\ntidal-cli history albums\ntidal-cli history artists\n```\n\n### History Flow Diagram\n\n```mermaid\ngraph TD\n A[User plays content] --> B[Tidal API records play]\n B --> C[tidal-cli history command]\n C --> D{Content Type?}\n D -->|Tracks| E[Display recent tracks]\n D -->|Albums| F[Display recent albums]\n D -->|Artists| G[Display recent artists]\n E --> H[User can re-play or explore]\n F --> H\n G --> H\n```\n\n## Search History Management\n\ntidal-cli maintains a local search history that allows you to quickly access previous queries and clear them when needed.\n\n### Search History Commands\n\n```bash\ntidal-cli search history # display search history\ntidal-cli search history-delete # remove specific entry\ntidal-cli search history-clear # clear all history\n```\n\n### Search History Data Model\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `entry-id` | string | Unique identifier for the search entry |\n| `query` | string | The search term used |\n| `timestamp` | datetime | When the search was performed |\n| `result-count` | number | Number of results returned |\n\n## User Profile Integration\n\nThe `user profile` command provides context about your Tidal account, which influences search results and recommendations:\n\n```bash\ntidal-cli user profile\n```\n\nThis command returns account information including subscription tier, preferred audio quality, and personalization settings that affect recommendation quality.\n\n## MCP Server Integration\n\nThe Search & Discovery functionality is exposed through the MCP (Model Context Protocol) server, enabling AI agents like Claude to perform music discovery tasks autonomously.\n\n### Available MCP Tools\n\nThe MCP server exposes the following discovery-related tools:\n\n- `search_artist` - Search for artists\n- `search_track` - Search for tracks\n- `search_album` - Search for albums\n- `get_recommendations` - Fetch personalized recommendations\n- `get_listening_history` - Retrieve play history\n- `get_similar_artists` - Find similar artists\n\n### Integration Example\n\n```\nUser: \"Find artists similar to Massive Attack and add their top tracks to my library\"\nAgent: Uses search_artist → similar_artist lookup → track lookup → library_add\n```\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n subgraph \"CLI Layer\"\n A[User Command] --> B[Command Parser]\n end\n \n subgraph \"Service Layer\"\n B --> C[Search Service]\n B --> D[Recommend Service]\n B --> E[History Service]\n end\n \n subgraph \"API Layer\"\n C --> F[Tidal Search API]\n D --> G[Tidal Personalization API]\n E --> H[Tidal User History API]\n end\n \n subgraph \"Output Layer\"\n F --> I[Formatted Output]\n G --> I\n H --> I\n I --> J[JSON/Terminal]\n end\n```\n\n## Best Practices\n\n### Efficient Searching\n\n1. **Use specific types**: Prefer `search track` over broad searches when you know what you're looking for\n2. **Leverage JSON output**: Use `--json` for scripting and automation\n3. **Build on history**: Review your listening history to discover patterns\n\n### Recommendation Optimization\n\n1. **Regular usage improves recommendations**: The system learns from your play history\n2. **Explore different mix types**: Each mix type surfaces different content\n3. **Use discovery mix**: The `discovery` type shows new content you haven't heard\n\n### Search History Management\n\n1. **Clear periodically**: Use `search history-clear` to reset if results become biased\n2. **Delete specific entries**: Remove individual entries with `search history-delete `\n\n## Error Handling\n\nCommon issues and resolutions:\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| No search results | Query too specific or misspelled | Try broader terms or check spelling |\n| Empty history | No plays recorded yet | Start playing content through tidal-cli |\n| Stale recommendations | New account or low activity | Use the service more to improve personalization |\n| Rate limiting | Too many rapid requests | Add delays between commands |\n\n## Related Commands\n\n- [Playback Commands](playback.md) - Play discovered content\n- [Library Commands](library.md) - Save and manage favorites\n- [Playlist Commands](playlists.md) - Organize discovered music\n\n## References\n\n- Search implementation: `src/search.ts`\n- Recommendations: `src/recommend.ts`\n- Mix functionality: `src/mix.ts`\n- Search history: `src/search-history.ts`\n- Usage examples: `README.md`\n\n---\n\n\n\n## CLI Commands - Library & Playlist Management\n\n### 相关页面\n\n相关主题：[CLI Commands - Core Modules](#page-cli-commands), [CLI Commands - Playback System](#page-cli-commands-playback)\n\n\nRelated Source Files
\n\nThe following source files were used to generate this documentation page. Note: The core implementation files (`src/playlist.ts`, `src/library.ts`, `src/saved.ts`, `src/history.ts`, `src/share.ts`) were not available in the provided repository context. This page is generated based on README.md and the site landing page content.\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) — Primary CLI command documentation\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx) — Feature overview and command examples\n \n\n# CLI Commands - Library & Playlist Management\n\n## Overview\n\nThe 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.\n\ntidal-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.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[User / LLM Agent] --> B[tidal-cli CLI]\n B --> C{Library & Playlist Commands}\n \n C --> D[library]\n C --> E[playlist]\n C --> F[saved]\n C --> G[history]\n C --> H[share]\n \n D --> I[Tidal API]\n E --> I\n F --> I\n G --> I\n H --> I\n \n I --> J[User Library Data]\n I --> K[Playlist Data]\n I --> L[Share Links]\n```\n\n## Library Commands\n\nThe `library` command group manages your personal Tidal library, including favorites for artists, albums, tracks, and videos.\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `library add --track-id ` | Add a track to your library |\n| `library add --album-id ` | Add an album to your library |\n| `library add --artist-id ` | Add an artist to your library |\n| `library favorite-playlists` | List your favorite playlists |\n| `library remove --type --id ` | Remove an item from your library |\n\n### Usage Examples\n\n```bash\n# Add a track to your library\ntidal-cli library add --track-id 5756235\n\n# Add an album to your library\ntidal-cli library add --album-id 12345678\n\n# Add an artist to your library\ntidal-cli library add --artist-id 8992\n\n# Remove a track from your library\ntidal-cli library remove --type tracks --id 5756235\n\n# List your favorite playlists\ntidal-cli library favorite-playlists\n```\n\n### JSON Output\n\nAll library commands support JSON output for programmatic use:\n\n```bash\ntidal-cli --json library add --track-id 5756235\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Playlist Commands\n\nThe `playlist` command group provides complete playlist management capabilities including creation, modification, and deletion.\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `playlist list` | List all your playlists |\n| `playlist create --name ` | Create a new playlist |\n| `playlist add-track --playlist-id --track-id ` | Add a track to a playlist |\n| `playlist add-album --playlist-id ` | Add all tracks from an album |\n| `playlist rename --playlist-id --name ` | Rename a playlist |\n| `playlist delete --playlist-id ` | Delete a playlist |\n| `playlist remove-track --playlist-id --track-id ` | Remove a track |\n\n### Usage Examples\n\n```bash\n# List all playlists\ntidal-cli playlist list\n\n# Create a new playlist\ntidal-cli playlist create --name \"Late Night Electronic\"\n\n# Add a track to a playlist\ntidal-cli playlist add-track --playlist-id --track-id \n\n# Add an entire album to a playlist\ntidal-cli playlist add-album --playlist-id \n```\n\n### Playlist Workflow\n\n```mermaid\ngraph LR\n A[Create Playlist] --> B[Get Playlist ID]\n B --> C[Add Tracks]\n C --> D[Add Albums]\n D --> E[Organize & Share]\n \n F[List Playlists] -.-> B\n G[Search Content] -.-> C\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## Save for Later Commands\n\nThe `saved` command group manages your \"Save for Later\" queue, allowing you to bookmark content for future listening.\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `saved list` | List all saved items |\n| `saved add --type --id ` | Add an item to saved |\n| `saved remove --type --id ` | Remove an item from saved |\n\n### Supported Types\n\n| Type | Description |\n|------|-------------|\n| `tracks` | Individual tracks |\n| `albums` | Full albums |\n| `artists` | Artist profiles |\n| `playlists` | Other users' playlists |\n| `videos` | Music videos |\n\n### Usage Examples\n\n```bash\n# List all saved items\ntidal-cli saved list\n\n# Save a track for later\ntidal-cli saved add --type tracks --id 5756235\n\n# Save an album for later\ntidal-cli saved add --type albums --id 12345678\n\n# Remove a saved item\ntidal-cli saved remove --type albums --id 12345678\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## History Commands\n\nThe `history` command group provides access to your listening history and search history.\n\n### Listening History\n\n| Command | Description |\n|---------|-------------|\n| `history tracks` | View your recently played tracks |\n| `history albums` | View your recently played albums |\n| `history artists` | View your recently played artists |\n\n### Search History\n\n| Command | Description |\n|---------|-------------|\n| `search history` | View your recent searches |\n| `search history-delete ` | Delete a specific search entry |\n| `search history-clear` | Clear all search history |\n\n### Usage Examples\n\n```bash\n# View your recent track history\ntidal-cli history tracks\n\n# View your recent album history\ntidal-cli history albums\n\n# View your recent artist history\ntidal-cli history artists\n\n# View search history\ntidal-cli search history\n\n# Delete a specific search entry\ntidal-cli search history-delete \n\n# Clear all search history\ntidal-cli search history-clear\n```\n\n### User Profile\n\n```bash\ntidal-cli user profile\n```\n\nThis command displays your user profile information including subscription status and account details.\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Share Commands\n\nThe `share` command group creates public share links for Tidal content.\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `share track ` | Create a public share link for a track |\n| `share album ` | Create a public share link for an album |\n\n### Usage Examples\n\n```bash\n# Share a track\ntidal-cli share track 5756235\n\n# Share an album\ntidal-cli share album 12345678\n```\n\nThese commands generate public URLs that can be shared with others, allowing them to access the same content on Tidal.\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Discovery & Recommendations\n\nWhile not strictly library management, these commands help expand and organize your library through discovery.\n\n### Recommendation Commands\n\n| Command | Description |\n|---------|-------------|\n| `recommend` | Get all mix categories |\n| `recommend --type daily` | Get daily mixes |\n| `recommend --type discovery` | Get discovery mixes |\n| `recommend --type new-release` | Get new release mixes |\n| `recommend --type offline` | Get offline mixes |\n| `mix items --type ` | Get tracks from a specific mix |\n\n### Similar Artists & Tracks\n\n| Command | Description |\n|---------|-------------|\n| `artist similar ` | Find similar artists |\n| `track similar ` | Find similar tracks |\n| `artist radio ` | Get artist radio |\n| `track radio ` | Get track radio |\n\n### Usage Examples\n\n```bash\n# Get all recommendation categories\ntidal-cli recommend\n\n# Get daily mixes\ntidal-cli recommend --type daily\n\n# Get tracks from a specific mix\ntidal-cli mix items --type daily\n\n# Find similar artists\ntidal-cli artist similar 8992\n\n# Get artist radio station\ntidal-cli artist radio 8992\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## Command Reference Summary\n\n### Library Management\n\n| Command | Type | Key Options |\n|---------|------|-------------|\n| `library add` | Add | `--track-id`, `--album-id`, `--artist-id` |\n| `library remove` | Remove | `--type`, `--id` |\n| `library favorite-playlists` | Query | - |\n\n### Playlist Management\n\n| Command | Type | Key Options |\n|---------|------|-------------|\n| `playlist list` | Query | - |\n| `playlist create` | Create | `--name` |\n| `playlist add-track` | Modify | `--playlist-id`, `--track-id` |\n| `playlist add-album` | Modify | `--playlist-id` |\n| `playlist rename` | Modify | `--playlist-id`, `--name` |\n| `playlist delete` | Delete | `--playlist-id` |\n\n### Saved & History\n\n| Command | Category | Key Options |\n|---------|----------|-------------|\n| `saved list` | Saved | - |\n| `saved add` | Saved | `--type`, `--id` |\n| `history tracks` | History | - |\n| `search history` | History | - |\n\n## Authentication Requirement\n\nAll Library & Playlist Management commands require authentication with your Tidal account. Run the following once to authenticate:\n\n```bash\ntidal-cli auth\n```\n\nThis opens your browser for Tidal authorization. After initial authentication, all commands run non-interactively with auto-refreshing tokens.\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## Requirements\n\n- Node.js >= 20\n- A valid Tidal account (Free, HiFi, or HiFi Plus subscription)\n\n## See Also\n\n- [Search Commands](search-commands.md) - Finding content to add to your library\n- [Playback Commands](playback-commands.md) - Playing tracks from your library\n- [Artist & Album Commands](artist-album-commands.md) - Exploring the catalog\n\n---\n\n\n\n## CLI Commands - Playback System\n\n### 相关页面\n\n相关主题：[CLI Commands - Core Modules](#page-cli-commands), [Authentication System](#page-authentication)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/playback.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/playback.ts)\n- [src/user.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/user.ts)\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n \n\n# CLI Commands - Playback System\n\nThe 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.\n\n## Architecture Overview\n\nThe Playback System integrates with Tidal's streaming infrastructure through the Tidal API, handling audio quality selection, stream URL generation, and local playback execution.\n\n```mermaid\ngraph TD\n A[\"User Command
tidal-cli playback play \"] --> B[\"playback.ts
Command Handler\"]\n B --> C[\"Tidal API
Audio Stream Endpoint\"]\n C --> D[\"Stream URL
with Quality Parameters\"]\n D --> E[\"Local Audio Player
System Default\"]\n \n F[\"tidal-cli playback url \"] --> B\n G[\"tidal-cli playback info \"] --> B\n H[\"tidal-cli playback play --quality LOSSLESS\"] --> B\n```\n\n## Playback Commands\n\n### playback play\n\nPlays a track locally using the system's default audio player.\n\n```bash\ntidal-cli playback play \ntidal-cli playback play --quality LOSSLESS\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `` | string | Yes | Tidal track ID to play |\n| `--quality` | string | No | Audio quality level |\n\n**Supported Quality Levels:**\n\n| Quality | Description |\n|---------|-------------|\n| `LOW` | Low quality audio stream |\n| `HIGH` | High quality audio stream |\n| `LOSSLESS` | Lossless CD-quality audio (FLAC) |\n| `HI_RES` | High resolution audio |\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n### playback url\n\nRetrieves the direct stream URL for a track without playing it. This is useful for integration with external audio players or custom playback solutions.\n\n```bash\ntidal-cli playback url \n```\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n### playback info\n\nReturns detailed playback metadata for a track, including available quality options, codec information, and stream characteristics.\n\n```bash\ntidal-cli playback info \n```\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## JSON Output\n\nAll playback commands support structured JSON output for programmatic consumption:\n\n```bash\ntidal-cli playback play 5756235 --json\ntidal-cli playback url 5756235 --json\ntidal-cli playback info 5756235 --json\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Integration with MCP Server\n\nThe playback system is exposed through the MCP (Model Context Protocol) connector, enabling AI agents like Claude to control Tidal playback:\n\n```bash\nhttps://tidal-cli.lucaperret.ch/api/mcp\n```\n\nThis allows prompts such as:\n\n> \"Play me something by Boards of Canada\"\n\nThe AI agent interprets the request, searches for appropriate tracks, and executes the playback command programmatically.\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## Command Structure\n\nThe playback commands follow the standard tidal-cli architecture:\n\n```mermaid\ngraph LR\n A[\"tidal-cli\"] --> B[\"playback\"]\n B --> C[\"play\"]\n B --> D[\"url\"]\n B --> E[\"info\"]\n C --> F[\"Track ID\"]\n C --> G[\"--quality flag\"]\n```\n\n## Typical Workflow Example\n\n```bash\n# 1. Search for a track\ntidal-cli search track \"Teardrop\"\n\n# 2. Get track details\ntidal-cli track info 5756235\n\n# 3. Play with default quality\ntidal-cli playback play 5756235\n\n# 4. Play with lossless quality\ntidal-cli playback play 5756235 --quality LOSSLESS\n\n# 5. Get stream URL for external player\ntidal-cli playback url 5756235 --json\n```\n\n## Quality Selection\n\nThe quality parameter allows explicit control over audio streaming quality:\n\n```bash\n# Play in highest available quality\ntidal-cli playback play 5756235 --quality HI_RES\n\n# Play lossless quality\ntidal-cli playback play 5756235 --quality LOSSLESS\n```\n\nIf no quality is specified, tidal-cli uses a sensible default based on your Tidal subscription level.\n\n## Error Handling\n\nWhen a track ID is invalid or the track is unavailable, the CLI returns a structured error message:\n\n```json\n{\n \"error\": \"track_not_found\",\n \"message\": \"Track with ID 5756235 not found\"\n}\n```\n\n## Source Files\n\n| File | Purpose |\n|------|---------|\n| `src/playback.ts` | Main playback command implementation |\n| `src/user.ts` | User preferences and quality settings |\n\n## Related Commands\n\n| Command | Description |\n|---------|-------------|\n| `tidal-cli search track` | Find tracks by name |\n| `tidal-cli track info` | Get detailed track metadata |\n| `tidal-cli track radio` | Generate a radio stream based on a track |\n\n---\n\n\n\n## Authentication System\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [MCP Server Integration](#page-mcp-server), [Data Flow & Session Management](#page-data-flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n- [src/session.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/session.ts) *(referenced in docs)*\n- [site/app/mcp-lib/constants.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/constants.ts) *(referenced in docs)*\n- [site/app/mcp-lib/tidal-oauth.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tidal-oauth.ts) *(referenced in docs)*\n- [site/app/mcp-lib/tools.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tools.ts)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n \n\n# Authentication System\n\n## Overview\n\nThe 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.\n\nThe 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.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n subgraph \"CLI Mode\"\n A1[User] -->|tidal-cli auth| B1[Local OAuth Flow]\n B1 --> C1[Tidal Login Page]\n C1 --> D1[Callback Server :25654]\n D1 --> E1[~/.tidal-cli/session.json]\n end\n \n subgraph \"MCP Server Mode\"\n A2[User] -->|Connect via MCP| B2[Remote OAuth Flow]\n B2 --> C2[Tidal Login Page]\n C2 --> D2[tidal-cli.lucaperret.ch /api/mcp]\n D2 --> E2[Upstash Redis Encrypted]\n end\n \n subgraph \"API Access\"\n E1 --> F1[Tidal API Client]\n E2 --> F2[Tidal API Client]\n end\n```\n\n## Authentication Modes\n\n### CLI Mode\n\nIn CLI mode, tidal-cli performs a complete OAuth 2.0 authorization code flow with PKCE (Proof Key for Code Exchange) support. The process involves:\n\n1. Starting a local HTTP server on port 25654 to receive the OAuth callback\n2. Opening the user's default browser to Tidal's authorization page\n3. Waiting for the user to authenticate with their Tidal credentials\n4. Exchanging the authorization code for access and refresh tokens\n5. Persisting tokens to the local session file\n\n**Token Storage Location**: `~/.tidal-cli/session.json`\n\n**Source**: [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) | [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n### MCP Server Mode\n\nWhen 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.\n\n**Token Storage Location**: Upstash Redis (encrypted, 30-day TTL)\n\n**Source**: [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n## Authentication Flow (CLI)\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI as tidal-cli CLI\n participant Browser as User's Browser\n participant Tidal as Tidal Auth Server\n participant Callback as Local Server :25654\n \n User->>CLI: tidal-cli auth\n CLI->>CLI: Generate PKCE verifier/challenge\n CLI->>Callback: Start local server\n CLI->>Browser: Open Tidal authorization URL\n User->>Browser: Enter Tidal credentials\n Browser->>Tidal: Authorization request with PKCE\n Tidal->>Browser: Authorization code\n Browser->>Callback: Redirect with code\n Callback->>CLI: Receive authorization code\n CLI->>Tidal: Exchange code for tokens\n Tidal->>CLI: Access token + Refresh token\n CLI->>CLI: Store tokens in session.json\n CLI->>User: \"Authenticated successfully!\"\n```\n\n## Core Authentication Module\n\n### src/auth.ts\n\nThe primary authentication module provides several key functions for managing the authentication lifecycle:\n\n#### Functions\n\n| Function | Purpose | Return Type |\n|----------|--------|-------------|\n| `authenticate()` | Initiates the OAuth flow with browser-based login | `Promise` |\n| `getApiClient()` | Returns an authenticated API client instance | `Promise` |\n| `getCountryCode()` | Retrieves and caches the user's country code | `Promise` |\n\n#### getApiClient Implementation\n\n```typescript\nexport async function getApiClient(): Promise {\n await ensureInit();\n\n // Verify we have valid credentials\n const creds = await credentialsProvider.getCredentials();\n if (!creds.token) {\n console.error('Error: Not authenticated. Run `tidal-cli auth` first.');\n process.exit(1);\n }\n\n return createAPIClient(credentialsProvider);\n}\n```\n\nThe `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.\n\n**Source**: [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n\n#### getCountryCode Caching\n\n```typescript\nlet cachedCountryCode: string | null = null;\n\nexport async function getCountryCode(): Promise {\n if (cachedCountryCode) return cachedCountryCode;\n\n try {\n const client = await getApiClient();\n const { data } = await client.GET('/users/{id}' as any, {\n // ... implementation\n });\n // ...\n }\n}\n```\n\nThe country code is retrieved from the user's profile and cached in memory to avoid repeated API calls for the same information.\n\n**Source**: [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n\n## MCP Authentication Tools\n\n### User Profile Tool\n\nThe MCP server exposes authentication-related tools for Claude integration:\n\n```typescript\nserver.tool('tidal_user_profile', 'Get your Tidal user profile', {},\n{ readOnlyHint: true, destructiveHint: false, openWorldHint: false, title: 'User Profile' },\nasync (_args, extra) => {\n const { client } = await getClientAndCountry(extractToken(extra));\n return text(await getUserProfileData(client));\n});\n```\n\n**Source**: [site/app/mcp-lib/tools.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tools.ts)\n\n### Token Extraction\n\nThe 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.\n\n## Data Storage Comparison\n\n| Aspect | CLI Mode | MCP Server Mode |\n|--------|----------|-----------------|\n| **Storage Location** | `~/.tidal-cli/session.json` | Upstash Redis (server-side) |\n| **Encryption** | File system permissions | Encrypted at rest |\n| **Token TTL** | Until revoked | 30-day TTL |\n| **Access** | Local only | Remote via MCP |\n| **User ID Retrieval** | `creds.userId` from session | Via `tidal_user_profile` tool |\n\n**Source**: [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n## Security Considerations\n\n### Credential Handling\n\nThe authentication system implements several security measures:\n\n1. **PKCE Support**: The OAuth flow uses Proof Key for Code Exchange to prevent authorization code interception attacks\n2. **Local-Only Storage (CLI)**: Authentication tokens never leave the user's device in CLI mode\n3. **Encrypted Storage (MCP)**: Server-side tokens are encrypted in Upstash Redis\n4. **No Password Storage**: Username and password are never seen or stored by tidal-cli—authentication occurs directly with Tidal\n\n**Source**: [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n### Data Deletion\n\nUsers can remove all locally stored authentication data by deleting the session directory:\n\n```bash\nrm -rf ~/.tidal-cli\n```\n\nFor MCP mode, tokens expire automatically after 30 days and can be revoked from the user's Tidal account settings.\n\n**Source**: [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n## Usage Examples\n\n### CLI Authentication\n\n```bash\n# Initiate authentication\ntidal-cli auth\n# Output: Opening browser for Tidal authorization...\n# Output: Authenticated successfully! User ID: 123456789\n\n# Verify authentication by querying profile\ntidal-cli user profile\n```\n\n**Source**: [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n### MCP Server Setup\n\n```bash\n# MCP connector URL for Claude Desktop\nhttps://tidal-cli.lucaperret.ch/api/mcp\n```\n\nUsers configure this URL in Claude Desktop's Settings → Connectors → Add custom connector.\n\n**Source**: [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## Dependencies and Configuration\n\n### Required Environment\n\n- **Node.js**: >= 20\n- **Tidal Account**: Free, HiFi, or HiFi Plus subscription\n\n### Configuration Files\n\n| File | Purpose | Location |\n|------|---------|----------|\n| `session.json` | OAuth tokens and user session | `~/.tidal-cli/` |\n| `credentials` | Token provider configuration | Internal to auth module |\n\n## Related Documentation\n\n- [Privacy Policy](/privacy) - Detailed data handling practices\n- [Terms of Service](/terms) - Usage terms and acceptable use\n- [GitHub Repository](https://github.com/lucaperret/tidal-cli) - Source code and issue tracking\n\n---\n\n\n\n## Data Flow & Session Management\n\n### 相关页面\n\n相关主题：[Authentication System](#page-authentication), [System Architecture](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/session.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/session.ts)\n- [site/lib/cli/session.js](https://github.com/lucaperret/tidal-cli/blob/main/site/lib/cli/session.js)\n- [site/app/mcp-lib/redis.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/redis.ts)\n- [site/app/api/token/route.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/api/token/route.ts)\n \n\n# Data Flow & Session Management\n\ntidal-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.\n\n## Architecture Overview\n\nThe system handles authentication differently depending on how users interact with tidal-cli:\n\n| Mode | Token Storage | Location | Data Flow |\n|------|--------------|----------|-----------|\n| CLI | Local filesystem | `~/.tidal-cli/session.json` | Device → Tidal API (direct) |\n| MCP | Encrypted Redis | Upstash (via Vercel) | Device → Vercel → Tidal API |\n\n资料来源：[site/app/privacy/page.tsx]()\n\n```mermaid\ngraph TD\n subgraph CLI_Mode[\"CLI Mode\"]\n A1[User Device] -->|OAuth| TIDAL_AUTH[Tidal Auth
login.tidal.com]\n A1 -->|API Calls| TIDAL_API[Tidal API
openapi.tidal.com]\n A1 -->|session.json| LOCAL[~/.tidal-cli/]\n end\n \n subgraph MCP_Mode[\"MCP Mode\"]\n A2[Claude Desktop
claude.ai] -->|MCP Protocol| MCP_ENDPOINT[https://tidal-cli.lucaperret.ch/api/mcp]\n MCP_ENDPOINT -->|Encrypted| REDIS[Upstash Redis
Vercel]\n MCP_ENDPOINT -->|API Calls| TIDAL_API2[Tidal API
openapi.tidal.com]\n A2 -->|OAuth| TIDAL_AUTH2[Tidal Auth
login.tidal.com]\n end\n```\n\n## CLI Mode Session Management\n\nWhen using tidal-cli as a command-line tool, authentication tokens are stored locally on the user's device.\n\n### Storage Location\n\n```\n~/.tidal-cli/session.json\n```\n\n资料来源：[site/app/privacy/page.tsx]()\n\n### Session Data Flow\n\n```mermaid\nsequenceDiagram\n participant User as User Device\n participant CLI as tidal-cli CLI\n participant TIDAL as Tidal Auth API\n participant LOCAL as Local Storage
~/.tidal-cli/\n\n User->>CLI: tidal-cli auth\n CLI->>TIDAL: Initiate OAuth flow\n TIDAL->>User: Open browser for login\n User->>TIDAL: Authenticate\n TIDAL-->>CLI: Authorization code\n CLI->>TIDAL: Exchange for tokens\n TIDAL-->>CLI: Access + Refresh tokens\n CLI->>LOCAL: Store in session.json\n Note over CLI,LOCAL: Tokens stored locally\n```\n\n### Data Privacy in CLI Mode\n\n- **Direct communication**: All API calls go directly from the user's device to Tidal's servers\n- **No intermediary**: No data passes through any third-party server\n- **Local-only storage**: Authentication tokens remain on the local filesystem\n- **User control**: Users have full control over their session data\n\n资料来源：[site/app/privacy/page.tsx]()\n\n## MCP Mode Session Management\n\nWhen 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.\n\n### MCP Endpoint Architecture\n\n```\nhttps://tidal-cli.lucaperret.ch/api/mcp\n```\n\n资料来源：[site/app/page.tsx]()\n\n### Session Data Flow\n\n```mermaid\nsequenceDiagram\n participant User as User/Claude Desktop\n participant Claude as Claude AI Agent\n participant Vercel as Vercel Edge
MCP Server\n participant Redis as Upstash Redis
Encrypted Storage\n participant TIDAL as Tidal API\n\n User->>Claude: Request music action\n Claude->>Vercel: MCP tool call\n Vercel->>Redis: Fetch/Store session\n Redis-->>Vercel: Encrypted tokens\n Vercel->>TIDAL: API request with token\n TIDAL-->>Vercel: Music data\n Vercel-->>Claude: MCP response\n Claude-->>User: Natural language response\n```\n\n### Server-Side Token Storage\n\n| Aspect | Description |\n|--------|-------------|\n| Storage Provider | Upstash (Redis) |\n| Hosting Platform | Vercel |\n| Encryption | Encrypted at rest |\n| Token Type | OAuth access + refresh tokens |\n\n资料来源：[site/app/privacy/page.tsx]()\n\n### MCP Configuration Steps\n\n| Step | Action | Description |\n|------|--------|-------------|\n| 1 | Open Claude Desktop Settings | Settings → Connectors → Add custom connector |\n| 2 | Add connector URL | `https://tidal-cli.lucaperret.ch/api/mcp` |\n| 3 | Authenticate | Complete OAuth flow in browser |\n| 4 | Token storage | Tokens stored in encrypted Redis |\n\n资料来源：[site/app/page.tsx]()\n\n## Token Lifecycle\n\n### Token Refresh Mechanism\n\nBoth CLI and MCP modes implement automatic token refresh to maintain continuous access:\n\n- **CLI Mode**: Token refresh handled locally by the CLI application\n- **MCP Mode**: Token refresh managed server-side by the Vercel edge functions\n\n### Available Quality Options for Playback\n\n| Quality | Description |\n|---------|-------------|\n| `LOW` | Standard quality stream |\n| `HIGH` | High quality stream |\n| `LOSSLESS` | Lossless audio quality |\n| `HI_RES` | High resolution audio |\n\n资料来源：[README.md]()\n\n## Data Deletion\n\n### CLI Mode Deletion\n\nTo remove all locally stored data:\n\n```bash\nrm -rf ~/.tidal-cli\n```\n\n资料来源：[site/app/privacy/page.tsx]()\n\nThis command removes:\n- `session.json` containing OAuth tokens\n- Any cached session data\n\n### MCP Mode Revocation\n\nFor MCP mode, users can revoke tidal-cli's access directly from their Tidal account settings. This invalidates the server-stored tokens.\n\n### Additional Options\n\n| Method | Scope | Action |\n|--------|-------|--------|\n| `rm -rf ~/.tidal-cli` | Local CLI data | Deletes session file |\n| Tidal Account Settings | MCP server data | Revokes OAuth application |\n| GitHub Issues | Support | Contact maintainer for data removal |\n\n资料来源：[site/app/privacy/page.tsx]()\n\n## External Service Dependencies\n\n### Tidal Services\n\n| Service | Endpoint | Purpose |\n|---------|----------|---------|\n| Tidal Auth | `login.tidal.com`, `auth.tidal.com` | OAuth authentication |\n| Tidal API | `openapi.tidal.com` | Music library, playlists, catalog access |\n\n### Third-Party Integrations\n\n| Provider | Service | Usage |\n|----------|---------|-------|\n| Vercel | Edge hosting | MCP server deployment |\n| Upstash | Redis database | Encrypted token storage |\n| Smithery | MCP registry | MCP connector discovery |\n\n资料来源：[site/app/privacy/page.tsx]()\n\n## Security Considerations\n\n### CLI Mode\n\n- Tokens stored in user-controlled filesystem\n- Direct API communication without intermediaries\n- User responsible for filesystem security\n\n### MCP Mode\n\n- Tokens encrypted at rest in Upstash Redis\n- Vercel edge infrastructure provides additional security layers\n- Server-side token management reduces client-side exposure\n\n## Summary\n\ntidal-cli implements a dual-mode session management strategy:\n\n1. **CLI Mode**: Local token storage with direct Tidal API communication\n2. **MCP Mode**: Server-side encrypted token storage for AI agent integration\n\nThe 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.\n\n---\n\n\n\n## MCP Server Integration\n\n### 相关页面\n\n相关主题：[Authentication System](#page-authentication)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [site/app/api/mcp/route.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/api/mcp/route.ts)\n- [site/app/api/authorize/route.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/api/authorize/route.ts)\n- [site/app/api/callback/route.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/api/callback/route.ts)\n- [site/app/api/token/route.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/api/token/route.ts)\n- [site/app/mcp-lib/tools.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tools.ts)\n \n\n# MCP Server Integration\n\n## Overview\n\nThe 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.\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Side\"\n Claude[Claude Desktop / claude.ai]\n end\n \n subgraph \"tidal-cli Infrastructure\"\n MCP_Endpoint[\"https://tidal-cli.lucaperret.ch/api/mcp\"]\n Auth_Endpoint[\"https://tidal-cli.lucaperret.ch/api/authorize\"]\n Callback[\"https://tidal-cli.lucaperret.ch/api/callback\"]\n Token_API[\"https://tidal-cli.lucaperret.ch/api/token\"]\n end\n \n subgraph \"External Services\"\n Tidal_API[\"Tidal API
openapi.tidal.com\"]\n Tidal_Auth[\"Tidal Auth
login.tidal.com\"]\n Redis[(Upstash Redis
Token Storage)]\n end\n \n Claude -->|\"MCP Protocol\"| MCP_Endpoint\n MCP_Endpoint -->|OAuth Flow| Auth_Endpoint\n Auth_Endpoint -->|\"Redirect\"| Tidal_Auth\n Tidal_Auth -->|\"Callback\"| Callback\n Callback -->|Token Exchange| Token_API\n Token_API -->|Store/Retrieve| Redis\n MCP_Endpoint -->|API Requests| Tidal_API\n \n style Redis fill:#f9f,stroke:#333,stroke-width:2px\n style Tidal_API fill:#bbf,stroke:#333,stroke-width:2px\n style Tidal_Auth fill:#bbf,stroke:#333,stroke-width:2px\n```\n\n## MCP Server Endpoint\n\nThe 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.\n\n### Connection URL\n\n```\nhttps://tidal-cli.lucaperret.ch/api/mcp\n```\n\n### Supported Clients\n\n| Client | URL Pattern | Status |\n|--------|-------------|--------|\n| Claude Desktop | `*.claude.ai` | ✅ Supported |\n| Smithery | `*.smithery.ai`, `smithery.run`, `*.smithery.run` | ✅ Supported |\n| Local Development | `localhost`, `127.0.0.1` | ✅ Supported |\n\n### Allowed Redirect URIs\n\nThe server validates incoming OAuth redirect URIs against an allowlist to prevent unauthorized callback origins:\n\n```typescript\nconst isAllowed =\n url.hostname.endsWith('.claude.ai') ||\n url.hostname === 'claude.ai' ||\n url.hostname.endsWith('.smithery.ai') ||\n url.hostname === 'smithery.run' ||\n url.hostname.endsWith('.smithery.run') ||\n url.hostname === 'localhost' ||\n url.hostname === '127.0.0.1';\n```\n\n资料来源：[site/app/api/authorize/route.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/api/authorize/route.ts)\n\n## OAuth Authentication Flow\n\nThe MCP server uses OAuth Authorization Code with PKCE (Proof Key for Code Exchange) for secure authentication without exposing client secrets.\n\n### Authentication Sequence\n\n```mermaid\nsequenceDiagram\n participant Client as MCP Client\n participant Server as tidal-cli Server\n participant Tidal as Tidal Auth\n \n Client->>Server: GET /api/authorize?redirect_uri=...\n Server->>Server: Generate PKCE (code_verifier, code_challenge)\n Server->>Server: Generate session_id\n Server->>Redis: Store OAuth session with PKCE data\n Server->>Client: Redirect to Tidal login\n Client->>Tidal: User authenticates\n Tidal->>Server: Callback with auth code\n Server->>Tidal: Exchange code for tokens\n Server->>Redis: Store encrypted tokens (30-day TTL)\n Server->>Client: Redirect to original client\n```\n\n### Session Storage\n\n| Storage Location | Encryption | TTL |\n|-----------------|------------|-----|\n| Upstash Redis (Remote MCP) | AES-256 encrypted | 30 days |\n\n> **Privacy Note**: No analytics, telemetry, or cookies are used. Tokens are encrypted at rest. 资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n## API Endpoints\n\n### Authorization Endpoint\n\n**Route**: `GET/POST /api/authorize`\n\nInitiates the OAuth flow by redirecting users to Tidal's login page.\n\n**Query Parameters**:\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `redirect_uri` | string | Client's callback URL |\n| `state` | string | CSRF protection token |\n| `code_challenge` | string | PKCE code challenge |\n| `code_challenge_method` | string | Must be \"S256\" |\n\n**Process**:\n1. Validates `redirect_uri` against allowed origins\n2. Generates PKCE code verifier and challenge\n3. Creates session ID for state management\n4. Stores session data in Redis\n5. Redirects to Tidal authorization URL\n\n资料来源：[site/app/api/authorize/route.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/api/authorize/route.ts)\n\n### Callback Endpoint\n\n**Route**: `/api/callback`\n\nHandles the OAuth callback from Tidal after user authentication.\n\n**Process**:\n1. Receives authorization code from Tidal\n2. Validates state parameter against stored session\n3. Exchanges code for access/refresh tokens\n4. Stores tokens in Redis with session data\n5. Redirects user back to MCP client\n\n### Token Endpoint\n\n**Route**: `POST /api/token`\n\nManages token operations including retrieval and refresh.\n\n**Operations**:\n| Operation | Description |\n|-----------|-------------|\n| Retrieve | Get stored tokens for a session |\n| Refresh | Refresh expired access tokens |\n| Delete | Revoke tokens and clear session |\n\n## MCP Tools (40 Total)\n\nThe MCP server exposes 40 tools organized into functional categories. Each tool includes safety annotations for AI assistants.\n\n资料来源：[site/app/mcp-lib/tools.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tools.ts)\n\n### Tool Categories\n\n| Category | Tool Count | Examples |\n|----------|------------|----------|\n| Search | 6 | `tidal_search`, `tidal_search_suggest` |\n| Track | 4 | `tidal_track_info`, `tidal_track_similar` |\n| Album | 2 | `tidal_album_info`, `tidal_album_by_barcode` |\n| Artist | 5 | `tidal_artist_info`, `tidal_artist_tracks` |\n| Playlist | 8 | `tidal_playlist_list`, `tidal_playlist_add_track` |\n| Library | 5 | `tidal_library_tracks`, `tidal_library_favorite_playlists` |\n| History | 2 | `tidal_recently_added`, `tidal_history_tracks` |\n| Playback | 3 | `tidal_playback_play`, `tidal_playback_info` |\n| User | 1 | `tidal_user_profile` |\n| Recommendations | 4 | `tidal_recommend`, `tidal_mix_items` |\n| Saved | 2 | `tidal_saved_list`, `tidal_saved_add` |\n| Sharing | 4 | `tidal_share_track`, `tidal_share_album` |\n\n### Tool Schema Example\n\nTools are defined using Zod schemas with safety annotations:\n\n```typescript\nserver.tool(\n 'tidal_album_info',\n 'Get album details including artists and cover art',\n {\n albumId: z.string().describe('Tidal album ID'),\n },\n {\n readOnlyHint: true,\n destructiveHint: false,\n openWorldHint: true,\n title: 'Album Info'\n },\n async ({ albumId }, extra) => {\n const { client, countryCode } = await getClientAndCountry(extractToken(extra));\n return text(await getAlbumInfoData(albumId, client, countryCode));\n }\n);\n```\n\n### Safety Annotations\n\n| Annotation | Type | Description |\n|------------|------|-------------|\n| `readOnlyHint` | boolean | Indicates if the tool only reads data |\n| `destructiveHint` | boolean | Indicates if the tool modifies/deletes data |\n| `openWorldHint` | boolean | Indicates if the tool interacts with external services |\n| `title` | string | Human-readable title for UI display |\n\n## Setup Instructions\n\n### Claude Desktop\n\n1. Open Claude Desktop settings\n2. Navigate to **Connectors** → **Add custom connector**\n3. Enter the connector URL:\n ```\n https://tidal-cli.lucaperret.ch/api/mcp\n ```\n4. Click **Connect** and authenticate with Tidal\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n### Smithery\n\nAccess via: [https://smithery.ai/servers/lucaperret/tidal](https://smithery.ai/servers/lucaperret/tidal)\n\nSmithery automatically re-scans tools and prompts after deployment.\n\n## Data Flow\n\n```mermaid\ngraph LR\n subgraph \"Request Flow\"\n A[MCP Request] --> B{Auth Check}\n B -->|Valid Token| C[Extract Token]\n B -->|Invalid/Missing| D[OAuth Flow]\n C --> E[Get Client & Country]\n E --> F[Call Tidal API]\n F --> G[Format Response]\n G --> H[MCP Response]\n end\n \n subgraph \"Tool Categories\"\n I[Search Tools]\n J[Playlist Tools]\n K[Library Tools]\n L[Playback Tools]\n end\n \n F --> I\n F --> J\n F --> K\n F --> L\n```\n\n## Distribution Channels\n\n| Channel | URL | Description |\n|---------|-----|-------------|\n| Direct MCP | `https://tidal-cli.lucaperret.ch/api/mcp` | Primary endpoint |\n| Smithery | [smithery.ai](https://smithery.ai/servers/lucaperret/tidal) | MCP registry |\n| ClawHub | [clawhub.ai](https://clawhub.ai/lucaperret/tidal-cli) | OpenClaw skill |\n\n## Configuration Options\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TIDAL_COUNTRY` | `US` | Fallback country code |\n| `TIDAL_CLIENT_ID` | (hardcoded) | OAuth client ID |\n\n### Session Management\n\n- **Storage Location**: Upstash Redis (encrypted)\n- **TTL**: 30 days\n- **Encryption**: AES-256 at rest\n- **Token Refresh**: Automatic via credentials provider\n\n## Security Considerations\n\n1. **PKCE Required**: All OAuth flows use Proof Key for Code Exchange\n2. **Redirect Validation**: Strict allowlist for callback URIs\n3. **Token Encryption**: OAuth tokens encrypted in Redis\n4. **No Client Secret**: Uses public OAuth pattern\n5. **State Parameter**: CSRF protection on all OAuth flows\n\n## Comparison: CLI vs MCP\n\n| Aspect | CLI | MCP Server |\n|--------|-----|------------|\n| Token Storage | `~/.tidal-cli/session.json` | Upstash Redis |\n| Session Type | Local only | Server-side |\n| Auth Flow | Browser-based | OAuth redirect |\n| Use Case | Direct terminal | AI assistant integration |\n| Platform | Node.js >= 20 | Any MCP client |\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| \"redirect_uri not allowed\" | Ensure client hostname matches allowed list |\n| Token expired | Re-authenticate via OAuth flow |\n| Tools not appearing | Refresh MCP client after deployment |\n\n### Deployment Notes\n\nAfter updating MCP tools or prompts:\n\n1. Deploy changes to Vercel\n2. Wait for auto-deploy completion\n3. Smithery will automatically re-scan (if using Smithery)\n\n资料来源：[CLAUDE.md](https://github.com/lucaperret/tidal-cli/blob/main/CLAUDE.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：lucaperret/tidal-cli\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | release_recency=unknown\n\n\n",
"markdown_key": "tidal-cli",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1183583268",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/lucaperret/tidal-cli"
},
{
"evidence_id": "art_9ee9219e0e994ec8ae228f35cc158018",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/lucaperret/tidal-cli#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "tidal-cli 说明书",
"toc": [
"https://github.com/lucaperret/tidal-cli 项目说明书",
"目录",
"Project Overview",
"Purpose and Scope",
"High-Level Architecture",
"Installation",
"Sign in with your Tidal account",
"Start exploring",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "be4269e6190924779877e2ab14c5ed11bc9e483d",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"src/artist.ts",
"src/search.ts",
"src/playlist.ts",
"src/history.ts",
"src/user.ts",
"src/share.ts",
"src/saved.ts",
"src/index.ts",
"src/mix.ts",
"src/track.ts",
"src/types.ts",
"src/album.ts",
"src/search-history.ts",
"src/auth.ts",
"src/recommend.ts",
"src/playback.ts",
"src/session.ts",
"src/library.ts",
"src/__tests__/saved.test.ts",
"src/__tests__/session.test.ts",
"src/__tests__/mix.test.ts",
"src/__tests__/library.test.ts",
"src/__tests__/playlist.test.ts",
"src/__tests__/artist.test.ts",
"src/__tests__/track.test.ts",
"src/__tests__/recommend.test.ts",
"src/__tests__/search-history.test.ts",
"src/__tests__/search.test.ts",
"src/__tests__/auth.test.ts",
"src/__tests__/share.test.ts",
"src/__tests__/album.test.ts"
],
"repo_inspection_verified": true,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @lucaperret/tidal-cli - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @lucaperret/tidal-cli 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`skills/tidal-cli/SKILL.md` Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`skills/tidal-cli/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npm install -g @lucaperret/tidal-cli` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `git clone https://github.com/lucaperret/tidal-cli.git` 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`skills/tidal-cli/SKILL.md` Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`skills/tidal-cli/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`CLAUDE.md`, `skills/tidal-cli/SKILL.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`CLAUDE.md`, `skills/tidal-cli/SKILL.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`CLAUDE.md`, `site/app/mcp-lib/redis.ts`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0008` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`skills/tidal-cli/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：111\n- 重要文件覆盖：33/111\n- 证据索引条目：33\n- 角色 / Skill 条目：1\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @lucaperret/tidal-cli 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @lucaperret/tidal-cli 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @lucaperret/tidal-cli 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 1 个角色 / Skill / 项目文档条目。\n\n- **tidal-cli**（skill）：Control Tidal music streaming from the terminal. Use when the user wants to search Tidal's catalog artists, albums, tracks, videos, playlists , manage playlists create, rename, delete, add/remove tracks , manage library/favorites, play music, explore artist/track info, find similar artists or tracks, get personalized recommendations, or view user profile. Triggers on: music-related requests mentioning Tidal, playlis… 激活提示：当用户任务与“tidal-cli”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/tidal-cli/SKILL.md`\n\n## 证据索引\n\n- 共索引 33 条证据。\n\n- **CLAUDE.md**（documentation）：tidal-cli — TypeScript CLI for Tidal music streaming. Designed for LLM agent automation via OpenClaw. 证据：`CLAUDE.md`\n- **tidal-cli**（documentation）：! 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 ! smithery badge https://smithery.ai/badge/lucaperret/tidal https://smithery.ai/servers/lucaperret/tidal ! 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 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"@lucaperret/tidal-cli\", \"version\": \"1.2.4\", \"description\": \"CLI for Tidal music streaming service, designed for LLM agent automation\", \"main\": \"dist/index.js\", \"bin\": { \"tidal-cli\": \"dist/index.js\" }, \"scripts\": { \"build\": \"tsc\", \"dev\": \"tsc --watch\", \"test\": \"vitest run\", \"test:watch\": \"vitest\", \"prepublishOnly\": \"npm run build\" }, \"keywords\": \"tidal\", \"music\", \"cli\", \"streaming\", \"llm\", \"agent\", \"automation\", \"openclaw\", \"playlist\", \"hifi\" , \"author\": \"Luca Perret\", \"license\": \"MIT\", \"homepage\": \"https://github.com/lucaperret/tidal-cli\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/lucaperret/tidal-cli.git\" }, \"bugs\": { \"url\": \"https://github.com/lucaperret/tid… 证据：`package.json`\n- **Package**（package_manifest）：{ \"name\": \"site\", \"version\": \"0.1.0\", \"private\": true, \"scripts\": { \"dev\": \"next dev\", \"prebuild\": \"node scripts/copy-cli-dist.js\", \"build\": \"next build\", \"start\": \"next start\" }, \"dependencies\": { \"@modelcontextprotocol/sdk\": \"^1.26.0\", \"@tidal-music/api\": \"^0.22.0\", \"@tidal-music/auth\": \"^1.6.0\", \"@tidal-music/common\": \"^0.2.0\", \"@upstash/redis\": \"^1.37.0\", \"@vercel/analytics\": \"^2.0.1\", \"framer-motion\": \"^12.38.0\", \"mcp-handler\": \"^1.1.0\", \"next\": \"^16.2.4\", \"react\": \"^19.2.5\", \"react-dom\": \"^19.2.5\", \"zod\": \"^4.4.3\" }, \"devDependencies\": { \"@tailwindcss/postcss\": \"^4.2.4\", \"@types/node\": \"^25.6.0\", \"@types/react\": \"^19.2.14\", \"@types/react-dom\": \"^19.2.3\", \"tailwindcss\": \"^4.2.4\", \"type… 证据：`site/package.json`\n- **tidal-cli**（skill_instruction）：CLI for Tidal music streaming. Search catalog, manage playlists, control library, play tracks, explore artists, discover new music. 证据：`skills/tidal-cli/SKILL.md`\n- **License**（source_file）：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: 证据：`LICENSE`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2017\", \"lib\": \"dom\", \"dom.iterable\", \"esnext\" , \"allowJs\": true, \"skipLibCheck\": true, \"strict\": true, \"noEmit\": true, \"esModuleInterop\": true, \"module\": \"esnext\", \"moduleResolution\": \"bundler\", \"resolveJsonModule\": true, \"isolatedModules\": true, \"jsx\": \"react-jsx\", \"incremental\": true, \"plugins\": { \"name\": \"next\" } , \"paths\": { \"@/ \": \"./ \" } }, \"include\": \"next-env.d.ts\", \" / .ts\", \" / .tsx\", \".next/types/ / .ts\", \".next/dev/types/ / .ts\", \" / .mts\" , \"exclude\": \"node modules\" } 证据：`site/tsconfig.json`\n- **Vercel**（structured_config）：{ \"buildCommand\": \"npm run build\", \"outputDirectory\": \".next\", \"framework\": \"nextjs\" } 证据：`site/vercel.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"commonjs\", \"lib\": \"ES2022\" , \"types\": \"node\" , \"outDir\": \"dist\", \"rootDir\": \"src\", \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"forceConsistentCasingInFileNames\": true, \"resolveJsonModule\": true, \"declaration\": true, \"sourceMap\": true }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\" } 证据：`tsconfig.json`\n- **Next.js site**（source_file）：node modules/ dist/ .env .env.local .skill 证据：`.gitignore`\n- **.npmignore**（source_file）：src/ site/ skills/ .ts tsconfig.json .gitignore .env .skill ROADMAP.md 证据：`.npmignore`\n- **See https://help.github.com/articles/ignoring-files/ for more about ignoring files.**（source_file）：See https://help.github.com/articles/ignoring-files/ for more about ignoring files. 证据：`site/.gitignore`\n- **Next.Config**（source_file）：import type { NextConfig } from \"next\"; 证据：`site/next.config.ts`\n- **Postcss.Config**（source_file）：const config = { plugins: { \"@tailwindcss/postcss\": {}, }, }; 证据：`site/postcss.config.mjs`\n- **Album**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { AlbumInfo, AlbumResult } from './types'; export type { AlbumInfo, AlbumResult }; 证据：`src/album.ts`\n- **Artist**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { ArtistInfo, ArtistTrack, ArtistAlbum, SimilarArtist, RadioPlaylist } from './types'; export type { ArtistInfo, ArtistTrack, ArtistAlbum, SimilarArtist }; 证据：`src/artist.ts`\n- **Auth**（source_file）：import { installLocalStorage } from './session'; 证据：`src/auth.ts`\n- **History**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { RecentItem, RecentType } from './types'; export type { RecentItem, RecentType }; 证据：`src/history.ts`\n- **!/usr/bin/env node**（source_file）：// Suppress \"TrueTime is not yet synchronized\" warnings from @tidal-music/auth const originalWarn = console.warn; console.warn = ...args: unknown = { if typeof args 0 === 'string' && args 0 .includes 'TrueTime' return; originalWarn ...args ; }; 证据：`src/index.ts`\n- **Library**（source_file）：import { getApiClient } from './auth'; import type { LibraryResourceType } from './types'; export type { LibraryResourceType }; 证据：`src/library.ts`\n- **Mix**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { MixCategory, MixItem } from './types'; export type { MixItem }; 证据：`src/mix.ts`\n- **Playback**（source_file）：import { getApiClient } from './auth'; import { exec } from 'child process'; import as fs from 'fs'; import as path from 'path'; import as os from 'os'; import type { PlaybackInfo, PlaybackUrl } from './types'; export type { PlaybackInfo, PlaybackUrl }; 证据：`src/playback.ts`\n- **Playlist**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { PlaylistInfo } from './types'; export type { PlaylistInfo }; 证据：`src/playlist.ts`\n- **Recommend**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { MixCategory, RecommendationItem } from './types'; export type { MixCategory, RecommendationItem }; 证据：`src/recommend.ts`\n- **Saved**（source_file）：import { getApiClient } from './auth'; import type { SavedItem, SavedItemType } from './types'; export type { SavedItem, SavedItemType }; 证据：`src/saved.ts`\n- **Search History**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { SearchHistoryEntry } from './types'; export type { SearchHistoryEntry }; 证据：`src/search-history.ts`\n- **Search**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { SearchType, SearchResult, SearchSuggestionsResult } from './types'; export type { SearchType, SearchResult, SearchSuggestionsResult }; 证据：`src/search.ts`\n- **Session**（source_file）：import as fs from 'fs'; import as path from 'path'; import as os from 'os'; 证据：`src/session.ts`\n- **Share**（source_file）：import { getApiClient } from './auth'; import type { ShareLink } from './types'; export type { ShareLink }; 证据：`src/share.ts`\n- **Track**（source_file）：import { getApiClient, getCountryCode } from './auth'; import type { TrackInfo, SimilarTrack, RadioPlaylist } from './types'; export type { TrackInfo, SimilarTrack }; 证据：`src/track.ts`\n- **Types**（source_file）：// Shared types for Data functions used by both CLI and MCP server 证据：`src/types.ts`\n- **User**（source_file）：import { getApiClient } from './auth'; import type { UserProfile } from './types'; export type { UserProfile }; 证据：`src/user.ts`\n- **Vitest.Config**（source_file）：import { defineConfig } from 'vitest/config'; 证据：`vitest.config.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`CLAUDE.md`, `README.md`, `package.json`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`CLAUDE.md`, `README.md`, `package.json`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Project Overview**：importance `high`\n - source_paths: README.md, CLAUDE.md, package.json\n- **System Architecture**：importance `high`\n - source_paths: CLAUDE.md, src/index.ts, src/session.ts, site/app/layout.tsx, site/package.json\n- **Getting Started**：importance `high`\n - source_paths: README.md, package.json, src/auth.ts\n- **CLI Commands - Core Modules**：importance `high`\n - source_paths: src/artist.ts, src/album.ts, src/track.ts, src/types.ts\n- **CLI Commands - Search & Discovery**：importance `high`\n - source_paths: src/search.ts, src/recommend.ts, src/mix.ts, src/search-history.ts\n- **CLI Commands - Library & Playlist Management**：importance `high`\n - source_paths: src/playlist.ts, src/library.ts, src/saved.ts, src/history.ts, src/share.ts\n- **CLI Commands - Playback System**：importance `medium`\n - source_paths: src/playback.ts, src/user.ts\n- **Authentication System**：importance `high`\n - source_paths: src/auth.ts, src/session.ts, site/app/mcp-lib/constants.ts, site/app/mcp-lib/tidal-oauth.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `be4269e6190924779877e2ab14c5ed11bc9e483d`\n- inspected_files: `package.json`, `README.md`, `src/artist.ts`, `src/search.ts`, `src/playlist.ts`, `src/history.ts`, `src/user.ts`, `src/share.ts`, `src/saved.ts`, `src/index.ts`, `src/mix.ts`, `src/track.ts`, `src/types.ts`, `src/album.ts`, `src/search-history.ts`, `src/auth.ts`, `src/recommend.ts`, `src/playback.ts`, `src/session.ts`, `src/library.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | host_targets=mcp_host, claude\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：lucaperret/tidal-cli\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/lucaperret/tidal-cli 项目说明书\n\n生成时间：2026-05-16 11:20:21 UTC\n\n## 目录\n\n- [Project Overview](#page-project-overview)\n- [System Architecture](#page-architecture)\n- [Getting Started](#page-getting-started)\n- [CLI Commands - Core Modules](#page-cli-commands)\n- [CLI Commands - Search & Discovery](#page-cli-commands-search)\n- [CLI Commands - Library & Playlist Management](#page-cli-commands-library)\n- [CLI Commands - Playback System](#page-cli-commands-playback)\n- [Authentication System](#page-authentication)\n- [Data Flow & Session Management](#page-data-flow)\n- [MCP Server Integration](#page-mcp-server)\n\n\n\n## Project Overview\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Getting Started](#page-getting-started)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n- [site/app/terms/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/terms/page.tsx)\n- [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n \n\n# Project Overview\n\ntidal-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.\n\n## Purpose and Scope\n\ntidal-cli serves two primary use cases:\n\n| Use Case | Description |\n|----------|-------------|\n| **CLI Tool** | Direct terminal interaction with Tidal for personal music management |\n| **MCP Server** | AI agent integration for Claude Desktop and other MCP-compatible clients |\n\n资料来源：[site/app/privacy/page.tsx:41-45]()\n\nThe 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.\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n A[User / AI Agent] --> B[tidal-cli]\n B --> C{Mode}\n C -->|CLI Mode| D[Local Execution]\n C -->|MCP Mode| E[Remote Server]\n D --> F[Tidal API]\n E --> F\n F --> G[Tidal Servers]\n \n D -.-> H[~/.tidal-cli/session.json]\n E -.-> I[Upstash Redis - Encrypted]\n \n style F fill:#4a90d9\n style G fill:#ff6b6b\n```\n\n资料来源：[site/app/privacy/page.tsx:41-52]()\n\n### CLI Mode\n\nWhen 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.\n\n### MCP Server Mode\n\nWhen 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.\n\n## Installation\n\n### Prerequisites\n\n- Node.js environment\n- Tidal account\n\n### Installation Commands\n\n```bash\nnpm install -g @lucaperret/tidal-cli\n\n# Sign in with your Tidal account\ntidal-cli auth\nOpening browser for Tidal authorization...\nAuthenticated successfully! User ID: 123456789\n\n# Start exploring\ntidal-cli search track \"Teardrop\"\n```\n\n资料来源：[site/app/page.tsx:101-115]()\n\n## Core Features\n\n### 40 Available Tools\n\ntidal-cli provides comprehensive coverage of Tidal's functionality across multiple domains:\n\n| Category | Capabilities |\n|----------|-------------|\n| **Search** | Search tracks, albums, artists, playlists, videos |\n| **Playlists** | Create, rename, delete playlists; add/remove tracks and albums |\n| **Playback** | Play tracks locally, get stream URLs, inspect playback quality |\n| **Library** | Manage favorites, add/remove artists, albums, tracks, videos |\n| **Discovery** | Find similar artists/tracks, personalized recommendations |\n| **History** | View listening history, search history, recent tracks |\n| **Saved** | Save-for-later functionality, sharing via public links |\n\n资料来源：[site/app/page.tsx:17-21]()\n\n### Discovery & History Commands\n\n```bash\ntidal-cli recommend # all mix categories\ntidal-cli recommend --type daily # daily | discovery | new-release | offline\ntidal-cli mix items --type daily # tracks inside a specific mix\ntidal-cli history tracks\ntidal-cli history albums\ntidal-cli history artists\ntidal-cli search history # your recent searches\ntidal-cli search history-delete \ntidal-cli search history-clear\ntidal-cli user profile\n```\n\n资料来源：[README.md:1-10]()\n\n### Playback Commands\n\n```bash\ntidal-cli playback play \ntidal-cli playback play --quality LOSSLESS\ntidal-cli playback info \ntidal-cli playback url \n```\n\n**Quality Options:** `LOW`, `HIGH`, `LOSSLESS`, `HI_RES`\n\n资料来源：[README.md:29-32]()\n\n### Save for Later & Sharing\n\n```bash\ntidal-cli saved list\ntidal-cli saved add --type tracks --id # tracks | albums | artists | playlists | videos\ntidal-cli saved remove --type albums --id \ntidal-cli share track # creates a public share link\ntidal-cli share album \n```\n\n资料来源：[README.md:22-26]()\n\n## JSON Output\n\nAll commands support structured JSON output by adding `--json` before any subcommand:\n\n```bash\ntidal-cli --json search track \"Around the World\"\ntidal-cli --json playlist list\ntidal-cli --json artist similar 8992\n```\n\n资料来源：[README.md:35-38]()\n\n## MCP Server Integration\n\n### AI Agent Support\n\ntidal-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.\n\n```mermaid\ngraph LR\n A[User Prompt] --> B[Claude AI]\n B --> C[MCP Server]\n C --> D[tidal-cli]\n D --> E[Tidal API]\n```\n\n### Setup for Claude Desktop\n\n1. Add the connector URL: `https://tidal-cli.lucaperret.ch/api/mcp`\n2. Connect your Tidal account through OAuth\n3. Begin natural language interactions\n\n### Example AI Agent Prompts\n\n| Prompt | Action |\n|--------|--------|\n| \"Create a playlist with the best tracks from Daft Punk's Discovery album\" | Searches, creates playlist, adds tracks |\n| \"Find artists similar to Massive Attack and add their top tracks to my library\" | Discovers similar artists, adds to favorites |\n| \"What are my playlists? Add the new LCD Soundsystem album to the first one\" | Lists playlists, searches album, adds tracks |\n| \"Play me something by Boards of Canada\" | Searches, picks a track, plays it |\n| \"Build a 2000s indie rock playlist with The Strokes, Arctic Monkeys, and Interpol\" | Multi-step: create, search, add tracks |\n\n资料来源：[site/app/page.tsx:67-78]()\n\n## Data Storage & Privacy\n\n### Local Storage (CLI Mode)\n\nAuthentication tokens are stored locally at:\n\n```\n~/.tidal-cli/session.json\n```\n\n### Server Storage (MCP Mode)\n\nFor MCP server usage, authentication tokens are stored in:\n\n- **Database:** Encrypted Redis database\n- **Provider:** Upstash (via Vercel)\n\n### Data Flow\n\n```mermaid\ngraph TD\n subgraph CLI_Mode[\"CLI Mode\"]\n A1[Local Device] --> A2[~/.tidal-cli/session.json]\n A2 --> A3[Tidal API]\n end\n \n subgraph MCP_Mode[\"MCP Mode\"]\n B1[Claude Desktop] --> B2[tidal-cli.lucaperret.ch]\n B2 --> B3[Upstash Redis]\n B3 --> B4[Tidal API]\n end\n```\n\n## Third-Party Services\n\ntidal-cli interacts with the following external services:\n\n| Service | Purpose |\n|---------|---------|\n| **Tidal API** (openapi.tidal.com) | Music library, playlists, and catalog access |\n| **Tidal Auth** (login.tidal.com, auth.tidal.com) | OAuth authentication |\n\n资料来源：[site/app/privacy/page.tsx:75-85]()\n\n## Legal & Licensing\n\n- **License:** MIT License\n- **Disclaimer:** tidal-cli is provided \"as is\" without warranty of any kind\n- **Affiliation:** Not affiliated with TIDAL\n\n资料来源：[site/app/terms/page.tsx:85-100]()\n\n## Key Source Files\n\n| File | Purpose |\n|------|---------|\n| `src/auth.ts` | Authentication handling |\n| `site/app/page.tsx` | Landing page with feature documentation |\n| `site/app/privacy/page.tsx` | Privacy policy and data handling |\n| `site/app/terms/page.tsx` | Terms of service |\n| `README.md` | Command reference and quick start |\n\n## Summary\n\ntidal-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.\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Project Overview](#page-project-overview), [Authentication System](#page-authentication), [MCP Server Integration](#page-mcp-server)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CLAUDE.md](https://github.com/lucaperret/tidal-cli/blob/main/CLAUDE.md)\n- [src/index.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/index.ts)\n- [src/session.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/session.ts)\n- [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n- [site/app/layout.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/layout.tsx)\n- [site/package.json](https://github.com/lucaperret/tidal-cli/blob/main/site/package.json)\n \n\n# System Architecture\n\n## Overview\n\ntidal-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.\n\nThe 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.\n\n**资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)**\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n CLI[tidal-cli CLI]\n MCP[MCP Server]\n WebApp[Next.js Web App]\n end\n\n subgraph \"Integration Layer\"\n AuthService[Authentication Service]\n APIClient[Tidal API Client]\n end\n\n subgraph \"External Services\"\n TidalAPI[Tidal API
openapi.tidal.com]\n TidalAuth[Tidal Auth
login.tidal.com
auth.tidal.com]\n end\n\n subgraph \"Data Storage\"\n LocalStorage[~/.tidal-cli/session.json]\n Redis[(Redis/Upstash)]\n end\n\n CLI --> AuthService\n MCP --> AuthService\n AuthService --> TidalAuth\n APIClient --> TidalAPI\n CLI --> APIClient\n MCP --> APIClient\n CLI --> LocalStorage\n MCP --> Redis\n WebApp --> MCP\n```\n\n**资料来源：[src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts), [src/session.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/session.ts)**\n\n## Component Architecture\n\n### CLI Client\n\nThe CLI client (`src/index.ts`) is the primary interface for end users. It provides a command-based interface with subcommands for various operations.\n\n| Command Category | Description | Example |\n|-----------------|-------------|---------|\n| `search` | Search artists, albums, tracks, videos, playlists | `tidal-cli search track \"Teardrop\"` |\n| `artist` | Artist information and related content | `tidal-cli artist info 8992` |\n| `album` | Album details and metadata | `tidal-cli album info ` |\n| `track` | Track information and similar tracks | `tidal-cli track info ` |\n| `playlist` | Playlist management | `tidal-cli playlist list` |\n| `playback` | Playback control and stream URLs | `tidal-cli playback play 5756235` |\n| `library` | User library management | `tidal-cli library add --track-id ` |\n| `saved` | Save for later functionality | `tidal-cli saved list` |\n| `recommend` | Recommendations and discovery | `tidal-cli recommend` |\n| `history` | User listening history | `tidal-cli history tracks` |\n| `user` | User profile information | `tidal-cli user profile` |\n\n**资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)**\n\n### MCP Server\n\nThe 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.\n\n```mermaid\ngraph LR\n A[Claude Desktop
claude.ai] -->|MCP Protocol| B[tidal-cli MCP Server]\n B -->|API Requests| C[Tidal API]\n B -->|Auth Token| D[Redis/Upstash]\n```\n\nThe MCP connector URL is available at `https://tidal-cli.lucaperret.ch/api/mcp` for remote server configuration.\n\n**资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)**\n\n### Web Application\n\nThe Next.js web application (`site/`) serves multiple purposes:\n\n| Route | Purpose |\n|-------|---------|\n| `/` | Landing page with features, installation, and AI agent setup |\n| `/terms` | Terms of Service documentation |\n| `/privacy` | Privacy Policy documentation |\n| `/api/mcp` | MCP server endpoint |\n| `/og-banner` | Open Graph banner generation |\n| `/banner` | Social sharing banner |\n\n**资料来源：[site/app/layout.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/layout.tsx)**\n\n## Authentication System\n\n### Authentication Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant TidalAuth\n participant TidalAPI\n participant LocalStorage\n\n User->>CLI: tidal-cli auth\n CLI->>TidalAuth: Initiate OAuth\n TidalAuth->>User: Open browser\n User->>TidalAuth: Login credentials\n TidalAuth->>CLI: Authorization code\n CLI->>TidalAuth: Exchange for tokens\n TidalAuth->>CLI: Access token + Refresh token\n CLI->>LocalStorage: Store tokens (~/.tidal-cli/session.json)\n CLI->>TidalAPI: Authenticated requests\n```\n\n### Token Storage\n\nThe system handles token storage differently based on the deployment mode:\n\n| Deployment Mode | Storage Location | Description |\n|----------------|------------------|-------------|\n| CLI (local) | `~/.tidal-cli/session.json` | Local file storage on user's device |\n| MCP Server | Redis (Upstash) | Server-side encrypted storage |\n\n**资料来源：[src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts), [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)**\n\n### Token Refresh\n\nThe authentication system includes automatic token refresh functionality:\n\n- Access tokens have limited validity\n- Refresh tokens are used to obtain new access tokens\n- The CLI automatically handles token refresh before expiration\n- MCP server manages token lifecycle server-side\n\n**资料来源：[src/session.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/session.ts)**\n\n## Data Flow\n\n### CLI Command Execution Flow\n\n```mermaid\ngraph TD\n A[tidal-cli command] --> B[Parse arguments]\n B --> C[Load session/Authenticate]\n C --> D[Build API request]\n D --> E[Execute request to Tidal API]\n E --> F{JSON flag?}\n F -->|Yes| G[Format JSON output]\n F -->|No| H[Format human-readable output]\n G --> I[Return result]\n H --> I\n```\n\n### Search Operation Flow\n\n```mermaid\ngraph LR\n A[User input] -->|search track| B[CLI]\n B --> C[Tidal API
openapi.tidal.com]\n C --> D[Parse response]\n D --> E[Display results]\n```\n\n**资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)**\n\n## External Dependencies\n\n### Tidal API Integration\n\n| Endpoint | Purpose | Reference |\n|----------|---------|-----------|\n| `openapi.tidal.com` | Music catalog API | Search, metadata, playback |\n| `login.tidal.com` | Login interface | OAuth initiation |\n| `auth.tidal.com` | Token exchange | OAuth flow |\n\n**资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)**\n\n### NPM Dependencies (CLI Core)\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `tidal-api` | Latest | Tidal API client |\n| `commander` | Latest | CLI argument parsing |\n| `open` | Latest | Browser opening for auth |\n\n**资料来源：[src/package.json](https://github.com/lucaperret/tidal-cli/blob/main/package.json)**\n\n### Web Application Dependencies\n\n| Package | Purpose |\n|---------|---------|\n| `next` | React framework |\n| `react` | UI components |\n| `framer-motion` | Animations |\n| `@radix-ui` | UI primitives |\n\n**资料来源：[site/package.json](https://github.com/lucaperret/tidal-cli/blob/main/site/package.json)**\n\n## CLI Command Structure\n\n### Command Hierarchy\n\n```\ntidal-cli\n├── auth # OAuth authentication\n├── search # Search operations\n│ ├── artist\n│ ├── album\n│ ├── track\n│ ├── video\n│ ├── playlist\n│ ├── suggest\n│ ├── editorial\n│ └── history\n├── artist # Artist operations\n│ ├── info\n│ ├── tracks\n│ ├── albums\n│ ├── similar\n│ └── radio\n├── album # Album operations\n│ ├── info\n│ └── barcode\n├── track # Track operations\n│ ├── info\n│ ├── similar\n│ ├── isrc\n│ └── radio\n├── playlist # Playlist operations\n│ ├── list\n│ ├── create\n│ ├── add-track\n│ ├── add-album\n│ └── remove\n├── playback # Playback operations\n│ ├── play\n│ ├── info\n│ └── url\n├── library # Library operations\n│ ├── add\n│ └── favorite-playlists\n├── saved # Save for later\n│ ├── list\n│ ├── add\n│ └── remove\n├── recommend # Discovery\n├── history # Listening history\n├── user # User profile\n├── share # Sharing\n└── --json # Global JSON output flag\n```\n\n**资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)**\n\n## Quality Options\n\nThe system supports multiple audio quality settings for playback:\n\n| Quality | Description |\n|---------|-------------|\n| `LOW` | Lowest quality streaming |\n| `HIGH` | High quality streaming |\n| `LOSSLESS` | Lossless audio (FLAC) |\n| `HI_RES` | High resolution audio |\n\n**资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)**\n\n## Project Structure\n\n```\ntidal-cli/\n├── src/\n│ ├── index.ts # CLI entry point\n│ ├── auth.ts # Authentication logic\n│ ├── session.ts # Session management\n│ └── ...\n├── site/\n│ ├── app/\n│ │ ├── page.tsx # Landing page\n│ │ ├── layout.tsx # Root layout\n│ │ ├── terms/ # Terms page\n│ │ ├── privacy/ # Privacy page\n│ │ ├── api/ # API routes (MCP)\n│ │ └── components/ # Reusable components\n│ └── package.json\n├── README.md\n├── CLAUDE.md # Developer documentation\n└── package.json\n```\n\n**资料来源：[CLAUDE.md](https://github.com/lucaperret/tidal-cli/blob/main/CLAUDE.md)**\n\n## Security Considerations\n\n### Local CLI Usage\n\n- Authentication tokens stored in `~/.tidal-cli/session.json`\n- Tokens never transmitted to external servers\n- Direct communication with Tidal API\n\n### MCP Server Usage\n\n- Tokens stored in encrypted Redis database (Upstash)\n- Server-side token management\n- Encrypted communication via HTTPS\n\n**资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)**\n\n## Deployment Architecture\n\n```mermaid\ngraph TD\n subgraph \"Development\"\n DevCLI[Local CLI]\n DevMCP[Local MCP Server]\n end\n\n subgraph \"Production\"\n ProdMCP[MCP Server
Vercel]\n ProdWeb[Web App
Vercel]\n Upstash[(Redis
Upstash)]\n end\n\n subgraph \"External\"\n Tidal[Tidal API]\n Claude[Claude Desktop
claude.ai]\n end\n\n DevCLI -->|OAuth| Tidal\n DevMCP -->|API| Tidal\n ProdMCP -->|Encrypted| Upstash\n ProdMCP -->|API| Tidal\n ProdWeb -->|MCP| ProdMCP\n Claude -->|MCP| ProdMCP\n```\n\n## Summary\n\nThe tidal-cli system architecture provides three distinct interfaces to the Tidal music streaming service:\n\n1. **CLI Client**: Direct terminal access with comprehensive command coverage\n2. **MCP Server**: AI agent integration for automated workflows\n3. **Web Application**: Documentation, marketing, and API endpoint hosting\n\nThe architecture prioritizes security through proper token management, offers flexibility through JSON output, and maintains compatibility with modern AI agent workflows through MCP protocol support.\n\n---\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[Project Overview](#page-project-overview), [Authentication System](#page-authentication)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n \n\n# Getting Started\n\nThis guide covers everything you need to install, configure, and start using tidal-cli effectively.\n\n## Overview\n\ntidal-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.\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Prerequisites\n\nBefore installing tidal-cli, ensure your environment meets the following requirements:\n\n| Requirement | Minimum Version | Description |\n|-------------|-----------------|-------------|\n| Node.js | >= 20 | JavaScript runtime required to execute the CLI |\n| npm | Latest | Node package manager (bundled with Node.js) |\n| Tidal Account | Any tier | Free, HiFi, or HiFi Plus subscription |\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## Installation\n\n### Global npm Installation\n\nThe recommended installation method uses npm globally:\n\n```bash\nnpm install -g @lucaperret/tidal-cli\n```\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n### Verify Installation\n\nAfter installation, verify tidal-cli is properly installed:\n\n```bash\ntidal-cli --version\n```\n\n## Initial Authentication\n\nAfter installation, you must authenticate with your Tidal account:\n\n```bash\ntidal-cli auth\n```\n\nThis command opens your default browser for OAuth authorization with Tidal. Once authenticated, your session tokens are stored locally.\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Usage Flow\n\n```mermaid\ngraph TD\n A[Install via npm] --> B[Run tidal-cli auth]\n B --> C[Browser Opens for OAuth]\n C --> D[Tidal Login]\n D --> E[Authorize Access]\n E --> F[Tokens Stored Locally]\n F --> G[Ready to Use]\n G --> H[Search, Playlists, Playback]\n```\n\n## Quick Start Commands\n\nAfter authentication, you can immediately start using tidal-cli:\n\n### Search\n\n```bash\ntidal-cli search track \"Around the World\"\ntidal-cli search artist \"Gorillaz\"\ntidal-cli search album \"Mezzanine\"\ntidal-cli search video \"Stylo\"\ntidal-cli search playlist \"Electronic\"\n```\n\n### Get Information\n\n```bash\ntidal-cli artist info \ntidal-cli album info \ntidal-cli track info \ntidal-cli user profile\n```\n\n### Playback\n\n```bash\ntidal-cli playback play \ntidal-cli playback play --quality LOSSLESS\ntidal-cli playback info \n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Quality Options\n\nWhen playing tracks, you can specify audio quality:\n\n| Quality | Description |\n|---------|-------------|\n| `LOW` | Standard quality |\n| `HIGH` | High quality |\n| `LOSSLESS` | Lossless/CD quality |\n| `HI_RES` | Hi-Res audio |\n\n## JSON Output\n\nAll commands support JSON output for scripting and automation:\n\n```bash\ntidal-cli --json search track \"Around the World\"\ntidal-cli --json playlist list\ntidal-cli --json artist similar 8992\n```\n\n## Session Storage\n\nWhen using tidal-cli as a CLI tool, authentication tokens are stored locally:\n\n```\n~/.tidal-cli/session.json\n```\n\n资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n## Next Steps\n\nOnce you're comfortable with the basics, explore these advanced features:\n\n- **Playlists**: Create and manage playlists with `playlist create`, `playlist add-track`\n- **Library**: Browse and manage your library with `library tracks`, `library favorite-artists`\n- **Discovery**: Get personalized recommendations with `recommend` and explore `history tracks`\n- **MCP Integration**: Connect to Claude Desktop or AI agents for automated workflows\n\n## Troubleshooting\n\n### Installation Issues\n\nIf npm install fails, try:\n```bash\nnpm install -g @lucaperret/tidal-cli --registry https://registry.npmjs.org/\n```\n\n### Authentication Issues\n\nIf `tidal-cli auth` doesn't open a browser, ensure your default browser is configured correctly.\n\n### Data Deletion\n\nTo remove all locally stored data:\n```bash\nrm -rf ~/.tidal-cli\n```\n\n资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n---\n\n\n\n## CLI Commands - Core Modules\n\n### 相关页面\n\n相关主题：[CLI Commands - Search & Discovery](#page-cli-commands-search), [CLI Commands - Library & Playlist Management](#page-cli-commands-library), [CLI Commands - Playback System](#page-cli-commands-playback)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) - CLI命令文档和用法说明\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx) - 网站首页，展示CLI功能\n \n\n# CLI Commands - Core Modules\n\n## Overview\n\nThe 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.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[User CLI Input] --> B[tidal-cli CLI Engine]\n B --> C[Core Modules]\n C --> D[Search Module]\n C --> E[Artist Module]\n C --> F[Album Module]\n C --> G[Track Module]\n C --> H[Playlist Module]\n C --> I[Playback Module]\n C --> J[Library Module]\n D --> K[Tidal API]\n E --> K\n F --> K\n G --> K\n H --> K\n I --> K\n J --> K\n```\n\n## Command Categories\n\nThe CLI organizes commands into functional modules as documented in the README:\n\n| Category | Primary Module | Key Capabilities |\n|----------|----------------|-------------------|\n| Search | `search` | Track, album, artist, video, playlist, suggestions |\n| Artists | `artist` | Info, tracks, albums, similar artists, radio |\n| Albums | `album` | Info, barcode lookup |\n| Tracks | `track` | Info, similar tracks, ISRC lookup, radio |\n| Playlists | `playlist` | List, create, add/remove tracks, add albums |\n| Playback | `playback` | Play, info, URL retrieval, quality control |\n| Library | `library` | Favorites management, history tracking |\n| Discovery | `recommend`, `history` | Personalized recommendations, listening history |\n\n## Search Module\n\nThe search module provides comprehensive catalog searching capabilities.\n\n### Supported Search Types\n\n```bash\ntidal-cli search artist \"\" # Artist search\ntidal-cli search album \"\" # Album search\ntidal-cli search track \"\" # Track search\ntidal-cli search video \"\" # Video search\ntidal-cli search playlist \"\" # Playlist search\ntidal-cli search suggest \"\" # Autocomplete suggestions\ntidal-cli search editorial \"\" # Editorial content search\n```\n\n### Search History Management\n\n```bash\ntidal-cli search history # View recent searches\ntidal-cli search history-delete # Delete specific entry\ntidal-cli search history-clear # Clear all search history\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Artist Module\n\nProvides artist information and related content discovery.\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `tidal-cli artist info ` | Get detailed artist information |\n| `tidal-cli artist tracks ` | List artist's tracks |\n| `tidal-cli artist albums ` | List artist's albums |\n| `tidal-cli artist similar ` | Find similar artists |\n| `tidal-cli artist radio ` | Generate artist radio stream |\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Album & Track Modules\n\n### Album Commands\n\n```bash\ntidal-cli album info # Get album details\ntidal-cli album barcode # Lookup album by barcode/EAN\n```\n\n### Track Commands\n\n```bash\ntidal-cli track info # Get track information\ntidal-cli track similar # Find similar tracks\ntidal-cli track isrc # Lookup track by ISRC\ntidal-cli track radio # Generate track radio stream\n```\n\n## Playlist Module\n\nFull playlist management capabilities.\n\n### Core Operations\n\n```bash\ntidal-cli playlist list # List all playlists\ntidal-cli playlist create --name \"\" # Create new playlist\ntidal-cli playlist add-track --playlist-id --track-id # Add single track\ntidal-cli playlist add-album --playlist-id # Add entire album\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Playback Module\n\nHandles track playback and stream URL retrieval.\n\n### Playback Commands\n\n```bash\ntidal-cli playback play # Play track\ntidal-cli playback play --quality LOSSLESS # Play with specific quality\ntidal-cli playback info # Get playback information\ntidal-cli playback url # Get stream URL\n```\n\n### Quality Options\n\n| Quality | Description |\n|---------|-------------|\n| `LOW` | Standard quality streaming |\n| `HIGH` | High quality streaming |\n| `LOSSLESS` | Lossless audio (FLAC) |\n| `HI_RES` | Hi-Res audio quality |\n\n## Discovery & History Module\n\n### Recommendations\n\n```bash\ntidal-cli recommend # All mix categories\ntidal-cli recommend --type daily # Daily mixes\ntidal-cli recommend --type discovery # Discovery mixes\ntidal-cli recommend --type new-release # New releases\ntidal-cli recommend --type offline # Offline mixes\ntidal-cli mix items --type daily # Get tracks from specific mix\n```\n\n### Listening History\n\n```bash\ntidal-cli history tracks # View track listening history\ntidal-cli history albums # View album listening history\ntidal-cli history artists # View artist listening history\n```\n\n### User Profile\n\n```bash\ntidal-cli user profile # Display user profile information\n```\n\n## Library Module\n\nManages user's personal library and saved content.\n\n### Saved Items\n\n```bash\ntidal-cli saved list # List saved items\ntidal-cli saved add --type --id # Add item to library\ntidal-cli saved remove --type --id # Remove from library\n```\n\n### Supported Item Types\n\n| Type | Description |\n|------|-------------|\n| `tracks` | Saved tracks |\n| `albums` | Saved albums |\n| `artists` | Favorite artists |\n| `playlists` | Saved playlists |\n| `videos` | Saved videos |\n\n### Favorites & Sharing\n\n```bash\ntidal-cli library add --track-id # Add track to library\ntidal-cli library favorite-playlists # List favorite playlists\ntidal-cli share track # Create public share link\ntidal-cli share album # Share album link\n```\n\n## JSON Output\n\nAll commands support JSON output for programmatic use:\n\n```bash\ntidal-cli --json search track \"Around the World\"\ntidal-cli --json playlist list\ntidal-cli --json artist similar 8992\n```\n\nThis enables integration with scripts and LLM agents for automation workflows.\n\n## CLI Options\n\n### Global Flags\n\n| Flag | Description |\n|------|-------------|\n| `--json` | Output results as JSON |\n| `--help` | Display command help |\n| `--version` | Show CLI version |\n\n## Integration with MCP Server\n\nThe CLI supports MCP (Model Context Protocol) integration for AI agent use:\n\n```\nhttps://tidal-cli.lucaperret.ch/api/mcp\n```\n\nThis enables Claude Desktop and other AI assistants to control Tidal programmatically.\n\n## Quick Start Commands\n\nBased on the website documentation, the essential commands to get started are:\n\n```bash\nnpm install -g @lucaperret/tidal-cli # Installation\ntidal-cli auth # OAuth authentication\ntidal-cli search track \"Teardrop\" # First search\ntidal-cli artist info 8992 # Artist lookup (Daft Punk example)\ntidal-cli playback play 5756235 # Playback\n```\n\n## Requirements\n\n- Node.js >= 20\n- Valid Tidal account (Free, HiFi, or HiFi Plus)\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n---\n\n\n\n## CLI Commands - Search & Discovery\n\n### 相关页面\n\n相关主题：[CLI Commands - Core Modules](#page-cli-commands), [CLI Commands - Library & Playlist Management](#page-cli-commands-library)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [src/search.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/search.ts)\n- [src/recommend.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/recommend.ts)\n- [src/mix.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/mix.ts)\n- [src/search-history.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/search-history.ts)\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n \n\n# CLI Commands - Search & Discovery\n\nThe 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.\n\n## Overview\n\nThe Search & Discovery functionality encompasses four primary areas:\n\n| Category | Purpose | Entry Point |\n|----------|---------|-------------|\n| **Catalog Search** | Query Tidal's music database by type | `tidal-cli search` |\n| **Discovery** | Access personalized mixes and recommendations | `tidal-cli recommend` |\n| **Listening History** | View recently played content | `tidal-cli history` |\n| **Search History** | Manage personal search activity | `tidal-cli search history` |\n\nThese commands support JSON output via the `--json` flag for programmatic consumption, making tidal-cli suitable for LLM agent integration through the MCP server.\n\n## Catalog Search\n\nThe `search` command provides type-specific queries against the Tidal API, enabling precise discovery of artists, albums, tracks, videos, playlists, editorial content, and search suggestions.\n\n### Supported Search Types\n\n```bash\ntidal-cli search artist \ntidal-cli search album \ntidal-cli search track \ntidal-cli search video \ntidal-cli search playlist \ntidal-cli search suggest \ntidal-cli search editorial \n```\n\n### Search Type Reference\n\n| Type | Description | Use Case |\n|------|-------------|----------|\n| `artist` | Find artists by name | \"Who is the best artist for this sound?\" |\n| `album` | Locate albums by title | \"Find all albums by this artist\" |\n| `track` | Search individual songs | \"Play me something similar\" |\n| `video` | Find music videos | \"Watch the official video\" |\n| `playlist` | Discover user playlists | \"Find playlists for parties\" |\n| `suggest` | Get search suggestions | Autocomplete functionality |\n| `editorial` | Browse curated editorial lists | \"What's trending in indie rock?\" |\n\n### JSON Output\n\nAll search commands support structured JSON output:\n\n```bash\ntidal-cli --json search track \"Around the World\"\ntidal-cli --json artist similar 8992\n```\n\nThis enables piping results to other tools or processing in automation scripts.\n\n## Discovery & Recommendations\n\nThe discovery system provides personalized content based on user listening patterns and algorithmic recommendations.\n\n### Mix Types\n\nThe `recommend` command accesses personalized mixes in various categories:\n\n```bash\ntidal-cli recommend # all mix categories\ntidal-cli recommend --type daily # daily mix\ntidal-cli recommend --type discovery # discovery mix\ntidal-cli recommend --type new-release # new releases\ntidal-cli recommend --type offline # offline-ready tracks\n```\n\n### Mix Reference Table\n\n| Type | Description | Refresh Frequency |\n|------|-------------|-------------------|\n| `daily` | Your daily personalized mix | Daily |\n| `discovery` | Tracks you've never listened to but might like | Weekly |\n| `new-release` | Recent releases matching your taste | Daily |\n| `offline` | Tracks optimized for offline playback | Dynamic |\n\n### Exploring Mix Content\n\nEach mix contains tracks that can be explored individually:\n\n```bash\ntidal-cli mix items --type daily\n```\n\nThis command retrieves all tracks within a specific mix, allowing users to add individual tracks to playlists or play them directly.\n\n## Listening History\n\ntidal-cli tracks your listening activity across different content types, enabling you to revisit recently played music.\n\n### History Commands\n\n```bash\ntidal-cli history tracks\ntidal-cli history albums\ntidal-cli history artists\n```\n\n### History Flow Diagram\n\n```mermaid\ngraph TD\n A[User plays content] --> B[Tidal API records play]\n B --> C[tidal-cli history command]\n C --> D{Content Type?}\n D -->|Tracks| E[Display recent tracks]\n D -->|Albums| F[Display recent albums]\n D -->|Artists| G[Display recent artists]\n E --> H[User can re-play or explore]\n F --> H\n G --> H\n```\n\n## Search History Management\n\ntidal-cli maintains a local search history that allows you to quickly access previous queries and clear them when needed.\n\n### Search History Commands\n\n```bash\ntidal-cli search history # display search history\ntidal-cli search history-delete # remove specific entry\ntidal-cli search history-clear # clear all history\n```\n\n### Search History Data Model\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `entry-id` | string | Unique identifier for the search entry |\n| `query` | string | The search term used |\n| `timestamp` | datetime | When the search was performed |\n| `result-count` | number | Number of results returned |\n\n## User Profile Integration\n\nThe `user profile` command provides context about your Tidal account, which influences search results and recommendations:\n\n```bash\ntidal-cli user profile\n```\n\nThis command returns account information including subscription tier, preferred audio quality, and personalization settings that affect recommendation quality.\n\n## MCP Server Integration\n\nThe Search & Discovery functionality is exposed through the MCP (Model Context Protocol) server, enabling AI agents like Claude to perform music discovery tasks autonomously.\n\n### Available MCP Tools\n\nThe MCP server exposes the following discovery-related tools:\n\n- `search_artist` - Search for artists\n- `search_track` - Search for tracks\n- `search_album` - Search for albums\n- `get_recommendations` - Fetch personalized recommendations\n- `get_listening_history` - Retrieve play history\n- `get_similar_artists` - Find similar artists\n\n### Integration Example\n\n```\nUser: \"Find artists similar to Massive Attack and add their top tracks to my library\"\nAgent: Uses search_artist → similar_artist lookup → track lookup → library_add\n```\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n subgraph \"CLI Layer\"\n A[User Command] --> B[Command Parser]\n end\n \n subgraph \"Service Layer\"\n B --> C[Search Service]\n B --> D[Recommend Service]\n B --> E[History Service]\n end\n \n subgraph \"API Layer\"\n C --> F[Tidal Search API]\n D --> G[Tidal Personalization API]\n E --> H[Tidal User History API]\n end\n \n subgraph \"Output Layer\"\n F --> I[Formatted Output]\n G --> I\n H --> I\n I --> J[JSON/Terminal]\n end\n```\n\n## Best Practices\n\n### Efficient Searching\n\n1. **Use specific types**: Prefer `search track` over broad searches when you know what you're looking for\n2. **Leverage JSON output**: Use `--json` for scripting and automation\n3. **Build on history**: Review your listening history to discover patterns\n\n### Recommendation Optimization\n\n1. **Regular usage improves recommendations**: The system learns from your play history\n2. **Explore different mix types**: Each mix type surfaces different content\n3. **Use discovery mix**: The `discovery` type shows new content you haven't heard\n\n### Search History Management\n\n1. **Clear periodically**: Use `search history-clear` to reset if results become biased\n2. **Delete specific entries**: Remove individual entries with `search history-delete `\n\n## Error Handling\n\nCommon issues and resolutions:\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| No search results | Query too specific or misspelled | Try broader terms or check spelling |\n| Empty history | No plays recorded yet | Start playing content through tidal-cli |\n| Stale recommendations | New account or low activity | Use the service more to improve personalization |\n| Rate limiting | Too many rapid requests | Add delays between commands |\n\n## Related Commands\n\n- [Playback Commands](playback.md) - Play discovered content\n- [Library Commands](library.md) - Save and manage favorites\n- [Playlist Commands](playlists.md) - Organize discovered music\n\n## References\n\n- Search implementation: `src/search.ts`\n- Recommendations: `src/recommend.ts`\n- Mix functionality: `src/mix.ts`\n- Search history: `src/search-history.ts`\n- Usage examples: `README.md`\n\n---\n\n\n\n## CLI Commands - Library & Playlist Management\n\n### 相关页面\n\n相关主题：[CLI Commands - Core Modules](#page-cli-commands), [CLI Commands - Playback System](#page-cli-commands-playback)\n\n\nRelated Source Files
\n\nThe following source files were used to generate this documentation page. Note: The core implementation files (`src/playlist.ts`, `src/library.ts`, `src/saved.ts`, `src/history.ts`, `src/share.ts`) were not available in the provided repository context. This page is generated based on README.md and the site landing page content.\n\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) — Primary CLI command documentation\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx) — Feature overview and command examples\n \n\n# CLI Commands - Library & Playlist Management\n\n## Overview\n\nThe 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.\n\ntidal-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.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[User / LLM Agent] --> B[tidal-cli CLI]\n B --> C{Library & Playlist Commands}\n \n C --> D[library]\n C --> E[playlist]\n C --> F[saved]\n C --> G[history]\n C --> H[share]\n \n D --> I[Tidal API]\n E --> I\n F --> I\n G --> I\n H --> I\n \n I --> J[User Library Data]\n I --> K[Playlist Data]\n I --> L[Share Links]\n```\n\n## Library Commands\n\nThe `library` command group manages your personal Tidal library, including favorites for artists, albums, tracks, and videos.\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `library add --track-id ` | Add a track to your library |\n| `library add --album-id ` | Add an album to your library |\n| `library add --artist-id ` | Add an artist to your library |\n| `library favorite-playlists` | List your favorite playlists |\n| `library remove --type --id ` | Remove an item from your library |\n\n### Usage Examples\n\n```bash\n# Add a track to your library\ntidal-cli library add --track-id 5756235\n\n# Add an album to your library\ntidal-cli library add --album-id 12345678\n\n# Add an artist to your library\ntidal-cli library add --artist-id 8992\n\n# Remove a track from your library\ntidal-cli library remove --type tracks --id 5756235\n\n# List your favorite playlists\ntidal-cli library favorite-playlists\n```\n\n### JSON Output\n\nAll library commands support JSON output for programmatic use:\n\n```bash\ntidal-cli --json library add --track-id 5756235\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Playlist Commands\n\nThe `playlist` command group provides complete playlist management capabilities including creation, modification, and deletion.\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `playlist list` | List all your playlists |\n| `playlist create --name ` | Create a new playlist |\n| `playlist add-track --playlist-id --track-id ` | Add a track to a playlist |\n| `playlist add-album --playlist-id ` | Add all tracks from an album |\n| `playlist rename --playlist-id --name ` | Rename a playlist |\n| `playlist delete --playlist-id ` | Delete a playlist |\n| `playlist remove-track --playlist-id --track-id ` | Remove a track |\n\n### Usage Examples\n\n```bash\n# List all playlists\ntidal-cli playlist list\n\n# Create a new playlist\ntidal-cli playlist create --name \"Late Night Electronic\"\n\n# Add a track to a playlist\ntidal-cli playlist add-track --playlist-id --track-id \n\n# Add an entire album to a playlist\ntidal-cli playlist add-album --playlist-id \n```\n\n### Playlist Workflow\n\n```mermaid\ngraph LR\n A[Create Playlist] --> B[Get Playlist ID]\n B --> C[Add Tracks]\n C --> D[Add Albums]\n D --> E[Organize & Share]\n \n F[List Playlists] -.-> B\n G[Search Content] -.-> C\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## Save for Later Commands\n\nThe `saved` command group manages your \"Save for Later\" queue, allowing you to bookmark content for future listening.\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `saved list` | List all saved items |\n| `saved add --type --id ` | Add an item to saved |\n| `saved remove --type --id ` | Remove an item from saved |\n\n### Supported Types\n\n| Type | Description |\n|------|-------------|\n| `tracks` | Individual tracks |\n| `albums` | Full albums |\n| `artists` | Artist profiles |\n| `playlists` | Other users' playlists |\n| `videos` | Music videos |\n\n### Usage Examples\n\n```bash\n# List all saved items\ntidal-cli saved list\n\n# Save a track for later\ntidal-cli saved add --type tracks --id 5756235\n\n# Save an album for later\ntidal-cli saved add --type albums --id 12345678\n\n# Remove a saved item\ntidal-cli saved remove --type albums --id 12345678\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## History Commands\n\nThe `history` command group provides access to your listening history and search history.\n\n### Listening History\n\n| Command | Description |\n|---------|-------------|\n| `history tracks` | View your recently played tracks |\n| `history albums` | View your recently played albums |\n| `history artists` | View your recently played artists |\n\n### Search History\n\n| Command | Description |\n|---------|-------------|\n| `search history` | View your recent searches |\n| `search history-delete ` | Delete a specific search entry |\n| `search history-clear` | Clear all search history |\n\n### Usage Examples\n\n```bash\n# View your recent track history\ntidal-cli history tracks\n\n# View your recent album history\ntidal-cli history albums\n\n# View your recent artist history\ntidal-cli history artists\n\n# View search history\ntidal-cli search history\n\n# Delete a specific search entry\ntidal-cli search history-delete \n\n# Clear all search history\ntidal-cli search history-clear\n```\n\n### User Profile\n\n```bash\ntidal-cli user profile\n```\n\nThis command displays your user profile information including subscription status and account details.\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Share Commands\n\nThe `share` command group creates public share links for Tidal content.\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `share track ` | Create a public share link for a track |\n| `share album ` | Create a public share link for an album |\n\n### Usage Examples\n\n```bash\n# Share a track\ntidal-cli share track 5756235\n\n# Share an album\ntidal-cli share album 12345678\n```\n\nThese commands generate public URLs that can be shared with others, allowing them to access the same content on Tidal.\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Discovery & Recommendations\n\nWhile not strictly library management, these commands help expand and organize your library through discovery.\n\n### Recommendation Commands\n\n| Command | Description |\n|---------|-------------|\n| `recommend` | Get all mix categories |\n| `recommend --type daily` | Get daily mixes |\n| `recommend --type discovery` | Get discovery mixes |\n| `recommend --type new-release` | Get new release mixes |\n| `recommend --type offline` | Get offline mixes |\n| `mix items --type ` | Get tracks from a specific mix |\n\n### Similar Artists & Tracks\n\n| Command | Description |\n|---------|-------------|\n| `artist similar ` | Find similar artists |\n| `track similar ` | Find similar tracks |\n| `artist radio ` | Get artist radio |\n| `track radio ` | Get track radio |\n\n### Usage Examples\n\n```bash\n# Get all recommendation categories\ntidal-cli recommend\n\n# Get daily mixes\ntidal-cli recommend --type daily\n\n# Get tracks from a specific mix\ntidal-cli mix items --type daily\n\n# Find similar artists\ntidal-cli artist similar 8992\n\n# Get artist radio station\ntidal-cli artist radio 8992\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## Command Reference Summary\n\n### Library Management\n\n| Command | Type | Key Options |\n|---------|------|-------------|\n| `library add` | Add | `--track-id`, `--album-id`, `--artist-id` |\n| `library remove` | Remove | `--type`, `--id` |\n| `library favorite-playlists` | Query | - |\n\n### Playlist Management\n\n| Command | Type | Key Options |\n|---------|------|-------------|\n| `playlist list` | Query | - |\n| `playlist create` | Create | `--name` |\n| `playlist add-track` | Modify | `--playlist-id`, `--track-id` |\n| `playlist add-album` | Modify | `--playlist-id` |\n| `playlist rename` | Modify | `--playlist-id`, `--name` |\n| `playlist delete` | Delete | `--playlist-id` |\n\n### Saved & History\n\n| Command | Category | Key Options |\n|---------|----------|-------------|\n| `saved list` | Saved | - |\n| `saved add` | Saved | `--type`, `--id` |\n| `history tracks` | History | - |\n| `search history` | History | - |\n\n## Authentication Requirement\n\nAll Library & Playlist Management commands require authentication with your Tidal account. Run the following once to authenticate:\n\n```bash\ntidal-cli auth\n```\n\nThis opens your browser for Tidal authorization. After initial authentication, all commands run non-interactively with auto-refreshing tokens.\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## Requirements\n\n- Node.js >= 20\n- A valid Tidal account (Free, HiFi, or HiFi Plus subscription)\n\n## See Also\n\n- [Search Commands](search-commands.md) - Finding content to add to your library\n- [Playback Commands](playback-commands.md) - Playing tracks from your library\n- [Artist & Album Commands](artist-album-commands.md) - Exploring the catalog\n\n---\n\n\n\n## CLI Commands - Playback System\n\n### 相关页面\n\n相关主题：[CLI Commands - Core Modules](#page-cli-commands), [Authentication System](#page-authentication)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/playback.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/playback.ts)\n- [src/user.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/user.ts)\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n- [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n \n\n# CLI Commands - Playback System\n\nThe 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.\n\n## Architecture Overview\n\nThe Playback System integrates with Tidal's streaming infrastructure through the Tidal API, handling audio quality selection, stream URL generation, and local playback execution.\n\n```mermaid\ngraph TD\n A[\"User Command
tidal-cli playback play \"] --> B[\"playback.ts
Command Handler\"]\n B --> C[\"Tidal API
Audio Stream Endpoint\"]\n C --> D[\"Stream URL
with Quality Parameters\"]\n D --> E[\"Local Audio Player
System Default\"]\n \n F[\"tidal-cli playback url \"] --> B\n G[\"tidal-cli playback info \"] --> B\n H[\"tidal-cli playback play --quality LOSSLESS\"] --> B\n```\n\n## Playback Commands\n\n### playback play\n\nPlays a track locally using the system's default audio player.\n\n```bash\ntidal-cli playback play \ntidal-cli playback play --quality LOSSLESS\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `` | string | Yes | Tidal track ID to play |\n| `--quality` | string | No | Audio quality level |\n\n**Supported Quality Levels:**\n\n| Quality | Description |\n|---------|-------------|\n| `LOW` | Low quality audio stream |\n| `HIGH` | High quality audio stream |\n| `LOSSLESS` | Lossless CD-quality audio (FLAC) |\n| `HI_RES` | High resolution audio |\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n### playback url\n\nRetrieves the direct stream URL for a track without playing it. This is useful for integration with external audio players or custom playback solutions.\n\n```bash\ntidal-cli playback url \n```\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n### playback info\n\nReturns detailed playback metadata for a track, including available quality options, codec information, and stream characteristics.\n\n```bash\ntidal-cli playback info \n```\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## JSON Output\n\nAll playback commands support structured JSON output for programmatic consumption:\n\n```bash\ntidal-cli playback play 5756235 --json\ntidal-cli playback url 5756235 --json\ntidal-cli playback info 5756235 --json\n```\n\n资料来源：[README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n## Integration with MCP Server\n\nThe playback system is exposed through the MCP (Model Context Protocol) connector, enabling AI agents like Claude to control Tidal playback:\n\n```bash\nhttps://tidal-cli.lucaperret.ch/api/mcp\n```\n\nThis allows prompts such as:\n\n> \"Play me something by Boards of Canada\"\n\nThe AI agent interprets the request, searches for appropriate tracks, and executes the playback command programmatically.\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## Command Structure\n\nThe playback commands follow the standard tidal-cli architecture:\n\n```mermaid\ngraph LR\n A[\"tidal-cli\"] --> B[\"playback\"]\n B --> C[\"play\"]\n B --> D[\"url\"]\n B --> E[\"info\"]\n C --> F[\"Track ID\"]\n C --> G[\"--quality flag\"]\n```\n\n## Typical Workflow Example\n\n```bash\n# 1. Search for a track\ntidal-cli search track \"Teardrop\"\n\n# 2. Get track details\ntidal-cli track info 5756235\n\n# 3. Play with default quality\ntidal-cli playback play 5756235\n\n# 4. Play with lossless quality\ntidal-cli playback play 5756235 --quality LOSSLESS\n\n# 5. Get stream URL for external player\ntidal-cli playback url 5756235 --json\n```\n\n## Quality Selection\n\nThe quality parameter allows explicit control over audio streaming quality:\n\n```bash\n# Play in highest available quality\ntidal-cli playback play 5756235 --quality HI_RES\n\n# Play lossless quality\ntidal-cli playback play 5756235 --quality LOSSLESS\n```\n\nIf no quality is specified, tidal-cli uses a sensible default based on your Tidal subscription level.\n\n## Error Handling\n\nWhen a track ID is invalid or the track is unavailable, the CLI returns a structured error message:\n\n```json\n{\n \"error\": \"track_not_found\",\n \"message\": \"Track with ID 5756235 not found\"\n}\n```\n\n## Source Files\n\n| File | Purpose |\n|------|---------|\n| `src/playback.ts` | Main playback command implementation |\n| `src/user.ts` | User preferences and quality settings |\n\n## Related Commands\n\n| Command | Description |\n|---------|-------------|\n| `tidal-cli search track` | Find tracks by name |\n| `tidal-cli track info` | Get detailed track metadata |\n| `tidal-cli track radio` | Generate a radio stream based on a track |\n\n---\n\n\n\n## Authentication System\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [MCP Server Integration](#page-mcp-server), [Data Flow & Session Management](#page-data-flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n- [src/session.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/session.ts) *(referenced in docs)*\n- [site/app/mcp-lib/constants.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/constants.ts) *(referenced in docs)*\n- [site/app/mcp-lib/tidal-oauth.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tidal-oauth.ts) *(referenced in docs)*\n- [site/app/mcp-lib/tools.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tools.ts)\n- [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n- [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n \n\n# Authentication System\n\n## Overview\n\nThe 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.\n\nThe 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.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n subgraph \"CLI Mode\"\n A1[User] -->|tidal-cli auth| B1[Local OAuth Flow]\n B1 --> C1[Tidal Login Page]\n C1 --> D1[Callback Server :25654]\n D1 --> E1[~/.tidal-cli/session.json]\n end\n \n subgraph \"MCP Server Mode\"\n A2[User] -->|Connect via MCP| B2[Remote OAuth Flow]\n B2 --> C2[Tidal Login Page]\n C2 --> D2[tidal-cli.lucaperret.ch /api/mcp]\n D2 --> E2[Upstash Redis Encrypted]\n end\n \n subgraph \"API Access\"\n E1 --> F1[Tidal API Client]\n E2 --> F2[Tidal API Client]\n end\n```\n\n## Authentication Modes\n\n### CLI Mode\n\nIn CLI mode, tidal-cli performs a complete OAuth 2.0 authorization code flow with PKCE (Proof Key for Code Exchange) support. The process involves:\n\n1. Starting a local HTTP server on port 25654 to receive the OAuth callback\n2. Opening the user's default browser to Tidal's authorization page\n3. Waiting for the user to authenticate with their Tidal credentials\n4. Exchanging the authorization code for access and refresh tokens\n5. Persisting tokens to the local session file\n\n**Token Storage Location**: `~/.tidal-cli/session.json`\n\n**Source**: [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md) | [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n### MCP Server Mode\n\nWhen 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.\n\n**Token Storage Location**: Upstash Redis (encrypted, 30-day TTL)\n\n**Source**: [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n## Authentication Flow (CLI)\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI as tidal-cli CLI\n participant Browser as User's Browser\n participant Tidal as Tidal Auth Server\n participant Callback as Local Server :25654\n \n User->>CLI: tidal-cli auth\n CLI->>CLI: Generate PKCE verifier/challenge\n CLI->>Callback: Start local server\n CLI->>Browser: Open Tidal authorization URL\n User->>Browser: Enter Tidal credentials\n Browser->>Tidal: Authorization request with PKCE\n Tidal->>Browser: Authorization code\n Browser->>Callback: Redirect with code\n Callback->>CLI: Receive authorization code\n CLI->>Tidal: Exchange code for tokens\n Tidal->>CLI: Access token + Refresh token\n CLI->>CLI: Store tokens in session.json\n CLI->>User: \"Authenticated successfully!\"\n```\n\n## Core Authentication Module\n\n### src/auth.ts\n\nThe primary authentication module provides several key functions for managing the authentication lifecycle:\n\n#### Functions\n\n| Function | Purpose | Return Type |\n|----------|--------|-------------|\n| `authenticate()` | Initiates the OAuth flow with browser-based login | `Promise` |\n| `getApiClient()` | Returns an authenticated API client instance | `Promise` |\n| `getCountryCode()` | Retrieves and caches the user's country code | `Promise` |\n\n#### getApiClient Implementation\n\n```typescript\nexport async function getApiClient(): Promise {\n await ensureInit();\n\n // Verify we have valid credentials\n const creds = await credentialsProvider.getCredentials();\n if (!creds.token) {\n console.error('Error: Not authenticated. Run `tidal-cli auth` first.');\n process.exit(1);\n }\n\n return createAPIClient(credentialsProvider);\n}\n```\n\nThe `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.\n\n**Source**: [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n\n#### getCountryCode Caching\n\n```typescript\nlet cachedCountryCode: string | null = null;\n\nexport async function getCountryCode(): Promise {\n if (cachedCountryCode) return cachedCountryCode;\n\n try {\n const client = await getApiClient();\n const { data } = await client.GET('/users/{id}' as any, {\n // ... implementation\n });\n // ...\n }\n}\n```\n\nThe country code is retrieved from the user's profile and cached in memory to avoid repeated API calls for the same information.\n\n**Source**: [src/auth.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/auth.ts)\n\n## MCP Authentication Tools\n\n### User Profile Tool\n\nThe MCP server exposes authentication-related tools for Claude integration:\n\n```typescript\nserver.tool('tidal_user_profile', 'Get your Tidal user profile', {},\n{ readOnlyHint: true, destructiveHint: false, openWorldHint: false, title: 'User Profile' },\nasync (_args, extra) => {\n const { client } = await getClientAndCountry(extractToken(extra));\n return text(await getUserProfileData(client));\n});\n```\n\n**Source**: [site/app/mcp-lib/tools.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tools.ts)\n\n### Token Extraction\n\nThe 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.\n\n## Data Storage Comparison\n\n| Aspect | CLI Mode | MCP Server Mode |\n|--------|----------|-----------------|\n| **Storage Location** | `~/.tidal-cli/session.json` | Upstash Redis (server-side) |\n| **Encryption** | File system permissions | Encrypted at rest |\n| **Token TTL** | Until revoked | 30-day TTL |\n| **Access** | Local only | Remote via MCP |\n| **User ID Retrieval** | `creds.userId` from session | Via `tidal_user_profile` tool |\n\n**Source**: [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n## Security Considerations\n\n### Credential Handling\n\nThe authentication system implements several security measures:\n\n1. **PKCE Support**: The OAuth flow uses Proof Key for Code Exchange to prevent authorization code interception attacks\n2. **Local-Only Storage (CLI)**: Authentication tokens never leave the user's device in CLI mode\n3. **Encrypted Storage (MCP)**: Server-side tokens are encrypted in Upstash Redis\n4. **No Password Storage**: Username and password are never seen or stored by tidal-cli—authentication occurs directly with Tidal\n\n**Source**: [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n### Data Deletion\n\nUsers can remove all locally stored authentication data by deleting the session directory:\n\n```bash\nrm -rf ~/.tidal-cli\n```\n\nFor MCP mode, tokens expire automatically after 30 days and can be revoked from the user's Tidal account settings.\n\n**Source**: [site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n## Usage Examples\n\n### CLI Authentication\n\n```bash\n# Initiate authentication\ntidal-cli auth\n# Output: Opening browser for Tidal authorization...\n# Output: Authenticated successfully! User ID: 123456789\n\n# Verify authentication by querying profile\ntidal-cli user profile\n```\n\n**Source**: [README.md](https://github.com/lucaperret/tidal-cli/blob/main/README.md)\n\n### MCP Server Setup\n\n```bash\n# MCP connector URL for Claude Desktop\nhttps://tidal-cli.lucaperret.ch/api/mcp\n```\n\nUsers configure this URL in Claude Desktop's Settings → Connectors → Add custom connector.\n\n**Source**: [site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n## Dependencies and Configuration\n\n### Required Environment\n\n- **Node.js**: >= 20\n- **Tidal Account**: Free, HiFi, or HiFi Plus subscription\n\n### Configuration Files\n\n| File | Purpose | Location |\n|------|---------|----------|\n| `session.json` | OAuth tokens and user session | `~/.tidal-cli/` |\n| `credentials` | Token provider configuration | Internal to auth module |\n\n## Related Documentation\n\n- [Privacy Policy](/privacy) - Detailed data handling practices\n- [Terms of Service](/terms) - Usage terms and acceptable use\n- [GitHub Repository](https://github.com/lucaperret/tidal-cli) - Source code and issue tracking\n\n---\n\n\n\n## Data Flow & Session Management\n\n### 相关页面\n\n相关主题：[Authentication System](#page-authentication), [System Architecture](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/session.ts](https://github.com/lucaperret/tidal-cli/blob/main/src/session.ts)\n- [site/lib/cli/session.js](https://github.com/lucaperret/tidal-cli/blob/main/site/lib/cli/session.js)\n- [site/app/mcp-lib/redis.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/redis.ts)\n- [site/app/api/token/route.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/api/token/route.ts)\n \n\n# Data Flow & Session Management\n\ntidal-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.\n\n## Architecture Overview\n\nThe system handles authentication differently depending on how users interact with tidal-cli:\n\n| Mode | Token Storage | Location | Data Flow |\n|------|--------------|----------|-----------|\n| CLI | Local filesystem | `~/.tidal-cli/session.json` | Device → Tidal API (direct) |\n| MCP | Encrypted Redis | Upstash (via Vercel) | Device → Vercel → Tidal API |\n\n资料来源：[site/app/privacy/page.tsx]()\n\n```mermaid\ngraph TD\n subgraph CLI_Mode[\"CLI Mode\"]\n A1[User Device] -->|OAuth| TIDAL_AUTH[Tidal Auth
login.tidal.com]\n A1 -->|API Calls| TIDAL_API[Tidal API
openapi.tidal.com]\n A1 -->|session.json| LOCAL[~/.tidal-cli/]\n end\n \n subgraph MCP_Mode[\"MCP Mode\"]\n A2[Claude Desktop
claude.ai] -->|MCP Protocol| MCP_ENDPOINT[https://tidal-cli.lucaperret.ch/api/mcp]\n MCP_ENDPOINT -->|Encrypted| REDIS[Upstash Redis
Vercel]\n MCP_ENDPOINT -->|API Calls| TIDAL_API2[Tidal API
openapi.tidal.com]\n A2 -->|OAuth| TIDAL_AUTH2[Tidal Auth
login.tidal.com]\n end\n```\n\n## CLI Mode Session Management\n\nWhen using tidal-cli as a command-line tool, authentication tokens are stored locally on the user's device.\n\n### Storage Location\n\n```\n~/.tidal-cli/session.json\n```\n\n资料来源：[site/app/privacy/page.tsx]()\n\n### Session Data Flow\n\n```mermaid\nsequenceDiagram\n participant User as User Device\n participant CLI as tidal-cli CLI\n participant TIDAL as Tidal Auth API\n participant LOCAL as Local Storage
~/.tidal-cli/\n\n User->>CLI: tidal-cli auth\n CLI->>TIDAL: Initiate OAuth flow\n TIDAL->>User: Open browser for login\n User->>TIDAL: Authenticate\n TIDAL-->>CLI: Authorization code\n CLI->>TIDAL: Exchange for tokens\n TIDAL-->>CLI: Access + Refresh tokens\n CLI->>LOCAL: Store in session.json\n Note over CLI,LOCAL: Tokens stored locally\n```\n\n### Data Privacy in CLI Mode\n\n- **Direct communication**: All API calls go directly from the user's device to Tidal's servers\n- **No intermediary**: No data passes through any third-party server\n- **Local-only storage**: Authentication tokens remain on the local filesystem\n- **User control**: Users have full control over their session data\n\n资料来源：[site/app/privacy/page.tsx]()\n\n## MCP Mode Session Management\n\nWhen 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.\n\n### MCP Endpoint Architecture\n\n```\nhttps://tidal-cli.lucaperret.ch/api/mcp\n```\n\n资料来源：[site/app/page.tsx]()\n\n### Session Data Flow\n\n```mermaid\nsequenceDiagram\n participant User as User/Claude Desktop\n participant Claude as Claude AI Agent\n participant Vercel as Vercel Edge
MCP Server\n participant Redis as Upstash Redis
Encrypted Storage\n participant TIDAL as Tidal API\n\n User->>Claude: Request music action\n Claude->>Vercel: MCP tool call\n Vercel->>Redis: Fetch/Store session\n Redis-->>Vercel: Encrypted tokens\n Vercel->>TIDAL: API request with token\n TIDAL-->>Vercel: Music data\n Vercel-->>Claude: MCP response\n Claude-->>User: Natural language response\n```\n\n### Server-Side Token Storage\n\n| Aspect | Description |\n|--------|-------------|\n| Storage Provider | Upstash (Redis) |\n| Hosting Platform | Vercel |\n| Encryption | Encrypted at rest |\n| Token Type | OAuth access + refresh tokens |\n\n资料来源：[site/app/privacy/page.tsx]()\n\n### MCP Configuration Steps\n\n| Step | Action | Description |\n|------|--------|-------------|\n| 1 | Open Claude Desktop Settings | Settings → Connectors → Add custom connector |\n| 2 | Add connector URL | `https://tidal-cli.lucaperret.ch/api/mcp` |\n| 3 | Authenticate | Complete OAuth flow in browser |\n| 4 | Token storage | Tokens stored in encrypted Redis |\n\n资料来源：[site/app/page.tsx]()\n\n## Token Lifecycle\n\n### Token Refresh Mechanism\n\nBoth CLI and MCP modes implement automatic token refresh to maintain continuous access:\n\n- **CLI Mode**: Token refresh handled locally by the CLI application\n- **MCP Mode**: Token refresh managed server-side by the Vercel edge functions\n\n### Available Quality Options for Playback\n\n| Quality | Description |\n|---------|-------------|\n| `LOW` | Standard quality stream |\n| `HIGH` | High quality stream |\n| `LOSSLESS` | Lossless audio quality |\n| `HI_RES` | High resolution audio |\n\n资料来源：[README.md]()\n\n## Data Deletion\n\n### CLI Mode Deletion\n\nTo remove all locally stored data:\n\n```bash\nrm -rf ~/.tidal-cli\n```\n\n资料来源：[site/app/privacy/page.tsx]()\n\nThis command removes:\n- `session.json` containing OAuth tokens\n- Any cached session data\n\n### MCP Mode Revocation\n\nFor MCP mode, users can revoke tidal-cli's access directly from their Tidal account settings. This invalidates the server-stored tokens.\n\n### Additional Options\n\n| Method | Scope | Action |\n|--------|-------|--------|\n| `rm -rf ~/.tidal-cli` | Local CLI data | Deletes session file |\n| Tidal Account Settings | MCP server data | Revokes OAuth application |\n| GitHub Issues | Support | Contact maintainer for data removal |\n\n资料来源：[site/app/privacy/page.tsx]()\n\n## External Service Dependencies\n\n### Tidal Services\n\n| Service | Endpoint | Purpose |\n|---------|----------|---------|\n| Tidal Auth | `login.tidal.com`, `auth.tidal.com` | OAuth authentication |\n| Tidal API | `openapi.tidal.com` | Music library, playlists, catalog access |\n\n### Third-Party Integrations\n\n| Provider | Service | Usage |\n|----------|---------|-------|\n| Vercel | Edge hosting | MCP server deployment |\n| Upstash | Redis database | Encrypted token storage |\n| Smithery | MCP registry | MCP connector discovery |\n\n资料来源：[site/app/privacy/page.tsx]()\n\n## Security Considerations\n\n### CLI Mode\n\n- Tokens stored in user-controlled filesystem\n- Direct API communication without intermediaries\n- User responsible for filesystem security\n\n### MCP Mode\n\n- Tokens encrypted at rest in Upstash Redis\n- Vercel edge infrastructure provides additional security layers\n- Server-side token management reduces client-side exposure\n\n## Summary\n\ntidal-cli implements a dual-mode session management strategy:\n\n1. **CLI Mode**: Local token storage with direct Tidal API communication\n2. **MCP Mode**: Server-side encrypted token storage for AI agent integration\n\nThe 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.\n\n---\n\n\n\n## MCP Server Integration\n\n### 相关页面\n\n相关主题：[Authentication System](#page-authentication)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [site/app/api/mcp/route.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/api/mcp/route.ts)\n- [site/app/api/authorize/route.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/api/authorize/route.ts)\n- [site/app/api/callback/route.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/api/callback/route.ts)\n- [site/app/api/token/route.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/api/token/route.ts)\n- [site/app/mcp-lib/tools.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tools.ts)\n \n\n# MCP Server Integration\n\n## Overview\n\nThe 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.\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Side\"\n Claude[Claude Desktop / claude.ai]\n end\n \n subgraph \"tidal-cli Infrastructure\"\n MCP_Endpoint[\"https://tidal-cli.lucaperret.ch/api/mcp\"]\n Auth_Endpoint[\"https://tidal-cli.lucaperret.ch/api/authorize\"]\n Callback[\"https://tidal-cli.lucaperret.ch/api/callback\"]\n Token_API[\"https://tidal-cli.lucaperret.ch/api/token\"]\n end\n \n subgraph \"External Services\"\n Tidal_API[\"Tidal API
openapi.tidal.com\"]\n Tidal_Auth[\"Tidal Auth
login.tidal.com\"]\n Redis[(Upstash Redis
Token Storage)]\n end\n \n Claude -->|\"MCP Protocol\"| MCP_Endpoint\n MCP_Endpoint -->|OAuth Flow| Auth_Endpoint\n Auth_Endpoint -->|\"Redirect\"| Tidal_Auth\n Tidal_Auth -->|\"Callback\"| Callback\n Callback -->|Token Exchange| Token_API\n Token_API -->|Store/Retrieve| Redis\n MCP_Endpoint -->|API Requests| Tidal_API\n \n style Redis fill:#f9f,stroke:#333,stroke-width:2px\n style Tidal_API fill:#bbf,stroke:#333,stroke-width:2px\n style Tidal_Auth fill:#bbf,stroke:#333,stroke-width:2px\n```\n\n## MCP Server Endpoint\n\nThe 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.\n\n### Connection URL\n\n```\nhttps://tidal-cli.lucaperret.ch/api/mcp\n```\n\n### Supported Clients\n\n| Client | URL Pattern | Status |\n|--------|-------------|--------|\n| Claude Desktop | `*.claude.ai` | ✅ Supported |\n| Smithery | `*.smithery.ai`, `smithery.run`, `*.smithery.run` | ✅ Supported |\n| Local Development | `localhost`, `127.0.0.1` | ✅ Supported |\n\n### Allowed Redirect URIs\n\nThe server validates incoming OAuth redirect URIs against an allowlist to prevent unauthorized callback origins:\n\n```typescript\nconst isAllowed =\n url.hostname.endsWith('.claude.ai') ||\n url.hostname === 'claude.ai' ||\n url.hostname.endsWith('.smithery.ai') ||\n url.hostname === 'smithery.run' ||\n url.hostname.endsWith('.smithery.run') ||\n url.hostname === 'localhost' ||\n url.hostname === '127.0.0.1';\n```\n\n资料来源：[site/app/api/authorize/route.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/api/authorize/route.ts)\n\n## OAuth Authentication Flow\n\nThe MCP server uses OAuth Authorization Code with PKCE (Proof Key for Code Exchange) for secure authentication without exposing client secrets.\n\n### Authentication Sequence\n\n```mermaid\nsequenceDiagram\n participant Client as MCP Client\n participant Server as tidal-cli Server\n participant Tidal as Tidal Auth\n \n Client->>Server: GET /api/authorize?redirect_uri=...\n Server->>Server: Generate PKCE (code_verifier, code_challenge)\n Server->>Server: Generate session_id\n Server->>Redis: Store OAuth session with PKCE data\n Server->>Client: Redirect to Tidal login\n Client->>Tidal: User authenticates\n Tidal->>Server: Callback with auth code\n Server->>Tidal: Exchange code for tokens\n Server->>Redis: Store encrypted tokens (30-day TTL)\n Server->>Client: Redirect to original client\n```\n\n### Session Storage\n\n| Storage Location | Encryption | TTL |\n|-----------------|------------|-----|\n| Upstash Redis (Remote MCP) | AES-256 encrypted | 30 days |\n\n> **Privacy Note**: No analytics, telemetry, or cookies are used. Tokens are encrypted at rest. 资料来源：[site/app/privacy/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/privacy/page.tsx)\n\n## API Endpoints\n\n### Authorization Endpoint\n\n**Route**: `GET/POST /api/authorize`\n\nInitiates the OAuth flow by redirecting users to Tidal's login page.\n\n**Query Parameters**:\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `redirect_uri` | string | Client's callback URL |\n| `state` | string | CSRF protection token |\n| `code_challenge` | string | PKCE code challenge |\n| `code_challenge_method` | string | Must be \"S256\" |\n\n**Process**:\n1. Validates `redirect_uri` against allowed origins\n2. Generates PKCE code verifier and challenge\n3. Creates session ID for state management\n4. Stores session data in Redis\n5. Redirects to Tidal authorization URL\n\n资料来源：[site/app/api/authorize/route.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/api/authorize/route.ts)\n\n### Callback Endpoint\n\n**Route**: `/api/callback`\n\nHandles the OAuth callback from Tidal after user authentication.\n\n**Process**:\n1. Receives authorization code from Tidal\n2. Validates state parameter against stored session\n3. Exchanges code for access/refresh tokens\n4. Stores tokens in Redis with session data\n5. Redirects user back to MCP client\n\n### Token Endpoint\n\n**Route**: `POST /api/token`\n\nManages token operations including retrieval and refresh.\n\n**Operations**:\n| Operation | Description |\n|-----------|-------------|\n| Retrieve | Get stored tokens for a session |\n| Refresh | Refresh expired access tokens |\n| Delete | Revoke tokens and clear session |\n\n## MCP Tools (40 Total)\n\nThe MCP server exposes 40 tools organized into functional categories. Each tool includes safety annotations for AI assistants.\n\n资料来源：[site/app/mcp-lib/tools.ts](https://github.com/lucaperret/tidal-cli/blob/main/site/app/mcp-lib/tools.ts)\n\n### Tool Categories\n\n| Category | Tool Count | Examples |\n|----------|------------|----------|\n| Search | 6 | `tidal_search`, `tidal_search_suggest` |\n| Track | 4 | `tidal_track_info`, `tidal_track_similar` |\n| Album | 2 | `tidal_album_info`, `tidal_album_by_barcode` |\n| Artist | 5 | `tidal_artist_info`, `tidal_artist_tracks` |\n| Playlist | 8 | `tidal_playlist_list`, `tidal_playlist_add_track` |\n| Library | 5 | `tidal_library_tracks`, `tidal_library_favorite_playlists` |\n| History | 2 | `tidal_recently_added`, `tidal_history_tracks` |\n| Playback | 3 | `tidal_playback_play`, `tidal_playback_info` |\n| User | 1 | `tidal_user_profile` |\n| Recommendations | 4 | `tidal_recommend`, `tidal_mix_items` |\n| Saved | 2 | `tidal_saved_list`, `tidal_saved_add` |\n| Sharing | 4 | `tidal_share_track`, `tidal_share_album` |\n\n### Tool Schema Example\n\nTools are defined using Zod schemas with safety annotations:\n\n```typescript\nserver.tool(\n 'tidal_album_info',\n 'Get album details including artists and cover art',\n {\n albumId: z.string().describe('Tidal album ID'),\n },\n {\n readOnlyHint: true,\n destructiveHint: false,\n openWorldHint: true,\n title: 'Album Info'\n },\n async ({ albumId }, extra) => {\n const { client, countryCode } = await getClientAndCountry(extractToken(extra));\n return text(await getAlbumInfoData(albumId, client, countryCode));\n }\n);\n```\n\n### Safety Annotations\n\n| Annotation | Type | Description |\n|------------|------|-------------|\n| `readOnlyHint` | boolean | Indicates if the tool only reads data |\n| `destructiveHint` | boolean | Indicates if the tool modifies/deletes data |\n| `openWorldHint` | boolean | Indicates if the tool interacts with external services |\n| `title` | string | Human-readable title for UI display |\n\n## Setup Instructions\n\n### Claude Desktop\n\n1. Open Claude Desktop settings\n2. Navigate to **Connectors** → **Add custom connector**\n3. Enter the connector URL:\n ```\n https://tidal-cli.lucaperret.ch/api/mcp\n ```\n4. Click **Connect** and authenticate with Tidal\n\n资料来源：[site/app/page.tsx](https://github.com/lucaperret/tidal-cli/blob/main/site/app/page.tsx)\n\n### Smithery\n\nAccess via: [https://smithery.ai/servers/lucaperret/tidal](https://smithery.ai/servers/lucaperret/tidal)\n\nSmithery automatically re-scans tools and prompts after deployment.\n\n## Data Flow\n\n```mermaid\ngraph LR\n subgraph \"Request Flow\"\n A[MCP Request] --> B{Auth Check}\n B -->|Valid Token| C[Extract Token]\n B -->|Invalid/Missing| D[OAuth Flow]\n C --> E[Get Client & Country]\n E --> F[Call Tidal API]\n F --> G[Format Response]\n G --> H[MCP Response]\n end\n \n subgraph \"Tool Categories\"\n I[Search Tools]\n J[Playlist Tools]\n K[Library Tools]\n L[Playback Tools]\n end\n \n F --> I\n F --> J\n F --> K\n F --> L\n```\n\n## Distribution Channels\n\n| Channel | URL | Description |\n|---------|-----|-------------|\n| Direct MCP | `https://tidal-cli.lucaperret.ch/api/mcp` | Primary endpoint |\n| Smithery | [smithery.ai](https://smithery.ai/servers/lucaperret/tidal) | MCP registry |\n| ClawHub | [clawhub.ai](https://clawhub.ai/lucaperret/tidal-cli) | OpenClaw skill |\n\n## Configuration Options\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TIDAL_COUNTRY` | `US` | Fallback country code |\n| `TIDAL_CLIENT_ID` | (hardcoded) | OAuth client ID |\n\n### Session Management\n\n- **Storage Location**: Upstash Redis (encrypted)\n- **TTL**: 30 days\n- **Encryption**: AES-256 at rest\n- **Token Refresh**: Automatic via credentials provider\n\n## Security Considerations\n\n1. **PKCE Required**: All OAuth flows use Proof Key for Code Exchange\n2. **Redirect Validation**: Strict allowlist for callback URIs\n3. **Token Encryption**: OAuth tokens encrypted in Redis\n4. **No Client Secret**: Uses public OAuth pattern\n5. **State Parameter**: CSRF protection on all OAuth flows\n\n## Comparison: CLI vs MCP\n\n| Aspect | CLI | MCP Server |\n|--------|-----|------------|\n| Token Storage | `~/.tidal-cli/session.json` | Upstash Redis |\n| Session Type | Local only | Server-side |\n| Auth Flow | Browser-based | OAuth redirect |\n| Use Case | Direct terminal | AI assistant integration |\n| Platform | Node.js >= 20 | Any MCP client |\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| \"redirect_uri not allowed\" | Ensure client hostname matches allowed list |\n| Token expired | Re-authenticate via OAuth flow |\n| Tools not appearing | Refresh MCP client after deployment |\n\n### Deployment Notes\n\nAfter updating MCP tools or prompts:\n\n1. Deploy changes to Vercel\n2. Wait for auto-deploy completion\n3. Smithery will automatically re-scan (if using Smithery)\n\n资料来源：[CLAUDE.md](https://github.com/lucaperret/tidal-cli/blob/main/CLAUDE.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：lucaperret/tidal-cli\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：lucaperret/tidal-cli\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1183583268 | https://github.com/lucaperret/tidal-cli | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# tidal-cli - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for lucaperret/tidal-cli.\n\nProject:\n- Name: tidal-cli\n- Repository: https://github.com/lucaperret/tidal-cli\n- Summary: Control Tidal from your terminal — search, playlists, playback, library, and recommendations via the Tidal API v2. Ships as a CLI, a remote MCP server for Claude Desktop/Smithery, and an OpenClaw skill. Built for scripting, LLM agent automation, and AI workflows. TypeScript, MIT.\n- Host target: mcp_host, claude\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Control Tidal from your terminal — search, playlists, playback, library, and recommendations via the Tidal API v2. Ships as a CLI, a remote MCP server for Claude Desktop/Smithery, and an OpenClaw skill. Built for scripting, LLM agent automation, and AI workflows. TypeScript, MIT.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-project-overview: Project Overview. Produce one small intermediate artifact and wait for confirmation.\n2. page-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. page-getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n4. page-cli-commands: CLI Commands - Core Modules. Produce one small intermediate artifact and wait for confirmation.\n5. page-cli-commands-search: CLI Commands - Search & Discovery. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/lucaperret/tidal-cli\n- https://github.com/lucaperret/tidal-cli#readme\n- skills/tidal-cli/SKILL.md\n- README.md\n- CLAUDE.md\n- package.json\n- src/index.ts\n- src/session.ts\n- site/app/layout.tsx\n- site/package.json\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：lucaperret/tidal-cli\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g @lucaperret/tidal-cli\n```\n\n来源：https://github.com/lucaperret/tidal-cli#readme\n\n## 来源\n\n- repo: https://github.com/lucaperret/tidal-cli\n- docs: https://github.com/lucaperret/tidal-cli#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_96e5a3a8426245738a3d6af1675d094b"
}