tidal-cli: Instructions file for Claude Code

CLAUDE.md

Project

tidal-cli — TypeScript CLI for Tidal music streaming. Designed for LLM agent automation via OpenClaw.

Architecture

• API: @tidal-music/api client against https://openapi.tidal.com/v2 (JSON:API spec)
• Auth: OAuth Authorization Code + PKCE. No client_secret. Client ID hardcoded (public OAuth pattern).
• Session: localStorage polyfill backed by ~/.tidal-cli/session.json. Tokens auto-refresh.
• Country code: Auto-detected from user profile via /users/me. Fallback: TIDAL_COUNTRY env var, then US.
• Playback: Uses /trackManifests/{id} (DASH segments), not the legacy v1 API.

Source Layout

src/
├── index.ts       # CLI entry point (commander)
├── auth.ts        # OAuth, getApiClient(), getCountryCode()
├── session.ts     # localStorage/EventTarget polyfills for Node.js
├── types.ts       # Shared types for *Data() functions
├── search.ts      # Search + suggestions
├── artist.ts      # Artist info, tracks, albums, similar, radio
├── track.ts       # Track info, similar, radio, ISRC lookup
├── album.ts       # Album info, barcode lookup
├── playlist.ts    # Playlist CRUD, track management, reorder
├── library.ts     # Library/favorites + favorited playlists
├── playback.ts    # Stream manifests, DASH download, local play
├── recommend.ts   # User recommendations (mixes)
├── history.ts     # Recently added items
├── user.ts        # User profile
└── __tests__/     # Vitest unit tests (111 tests)

site/app/
├── .well-known/oauth-authorization-server/  # OAuth metadata discovery
├── api/authorize/   # OAuth authorize → redirects to Tidal
├── api/callback/    # Tidal OAuth callback → stores tokens
├── api/token/       # Token exchange (code → access token)
├── api/mcp/         # MCP Streamable HTTP handler (32 tools)
└── mcp-lib/         # Redis, Tidal OAuth, tool definitions, constants

Commands

Run npm run build then node dist/index.js --help for the full command list.

Testing

npm test           # vitest run
npm run test:watch # vitest watch