Tidekeeper CLI

Tidekeeper CLI is an unofficial maintained fork of yaronzz/Tidal-Media-Downloader, focused on keeping the Python command-line tool installable, testable, and usable on current Python versions.

The CLI is available as both tidekeeper and the legacy-compatible tidal-dl.

Scope

• Maintain the Python CLI fork with modern packaging and CI.
• Improve install reliability, authenticated API requests, retries, partial files, timeouts, and error reporting.
• Keep compatibility with existing tidal-dl workflows where practical.

This project does not aim to bypass access controls, subscription checks, or DRM.

Install

python -m pip install "git+https://github.com/OpenNerdz/tidekeeper-cli.git#subdirectory=TIDALDL-PY"

Linux one-command installer:

curl -fsSL https://raw.githubusercontent.com/OpenNerdz/tidekeeper-cli/main/install.sh | bash

Then run:

tidekeeper

Termux

Termux support is for the CLI install path only.

pkg update && pkg upgrade -y && pkg install -y curl
curl -fsSL https://raw.githubusercontent.com/OpenNerdz/tidekeeper-cli/main/install.sh | bash
tidekeeper

To save downloads to Android shared storage:

termux-setup-storage
export TIDEKEEPER_DOWNLOAD_PATH="/storage/emulated/0/Download/Tidekeeper"

If ffmpeg fails with cannot locate symbol "x265_api_get_216", your Termux packages are mismatched. Run:

pkg update
pkg upgrade -y
pkg reinstall -y ffmpeg x265
ffmpeg -version

If it still fails, run termux-change-repo, switch mirrors, then repeat the commands above.

Usage

tidekeeper --help
tidekeeper --doctor
tidekeeper
tidekeeper -l "https://tidal.com/browse/track/70973230"

tidekeeper --doctor checks the saved client, token, download path, and local tools without starting a download.

Dolby Atmos downloads are opt-in:

tidekeeper -q Atmos
tidekeeper -l "https://tidal.com/browse/album/123456"

When an Atmos stream is downloaded, the default track filename gets a [Dolby Atmos] suffix. Custom track filename formats can also use {StreamQuality} and {Codec}, for example:

{TrackNumber} - {ArtistName} - {TrackTitle} [{StreamQuality}] [{Codec}]

If TIDAL blocks a requested stream manifest or the requested format is not available for a track, Tidekeeper falls back through lower audio qualities so the download can continue when another entitled format is available. Track output shows the requested quality and the fallback quality when this happens.

If a track download fails, Tidekeeper appends it to failed-tracks.txt in the download folder. The file keeps comments with the title and reason, followed by a plain TIDAL track URL. Retry those tracks later with:

tidekeeper -l "/path/to/downloads/failed-tracks.txt"

Legacy command:

tidal-dl --help

Development

See CONTRIBUTING.md for pull request guidelines and the expected local checks. See CHANGELOG.md for release history.

git clone https://github.com/OpenNerdz/tidekeeper-cli.git
cd tidekeeper-cli/TIDALDL-PY
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
python -m compileall -q tidal_dl
python -m unittest discover -s tests

Build

./build.sh

Build outputs are written under TIDALDL-PY/dist and TIDALDL-PY/exe.

Attribution

This project is based on yaronzz/Tidal-Media-Downloader, originally authored by YaronH and contributors. The original project is licensed under Apache-2.0. See NOTICE and LICENSE.

Disclaimer

This project is unofficial and is not affiliated with, endorsed by, or sponsored by TIDAL or Block, Inc. Use it only where you have the right to do so, and follow the laws and service terms that apply in your location.

Security

Please report security-sensitive issues privately and redact tokens from logs. See SECURITY.md for details.