spotdl is a cli tool to archive and synchronize spotify tracks for offline usage. Its main use case is to be able to listen to music on devices that have poor or no support for spotify. spotdl requires a spotify premium account.

spotdl login $USERNAME $PASSWORD

# It is also possible to use an ID or URL instead of a URI
spotdl download spotify:album:7vfuTRXIAYJz5Uc8SddnTr

The download command tries to avoid downloading any already existing tracks by looking at the metadata of existing tracks in the destination directory.

spotdl download spotify:playlist:7dXMxn9chL56TWB31fa33J

By default spotdl will cache playlist metadata for a few hours so if you want to make sure you are synchronizing the latest playlist just remove it from the cache first with:

spotdl cache remove spotify:playlist:7dXMxn9chL56TWB31fa33J

Login to a spotify account using username and password. Only spotify premium accounts are supported.

spotdl login $USERNAME $PASSWORD

After the login succeeds a token is stored in the cache directory, the password itself is not stored on disk.

Logout from a spotify account.

spotdl logout $USERNAME

This is equivalent to just removing the file storing the credentials.

Print information about a spotify resource.

spotdl info spotify:playlist:7dXMxn9chL56TWB31fa33J

Download a spotify resource to a directory. This will avoid downloading any tracks that already exist in the output directory.

When downloading an artist all its albums, singles and compilations will be downloaded but no "appears on" albums.

An example of this command was already shown above, for more details use spotdl download --help.

Scan all files in a directory and print the spotify ID and path of any tracks.

The spotdl sync commands are just helpers that maintain a manifest file that contains a list of spotify resources. These resources can then be synced using spotdl sync download. To add and remove resources the commands spotdl sync add and spotdl sync remove can be used. Use the --help flag with any of these commands to see all the possible flags.

spotdl attempts to cache all metadata retreived from spotify to avoid having to use the network, but sometimes it might be required to remove something from cache earlier than normal.

The cache is just a set of key-value pairs stored in the filesystem.

To list all keys use:

spotdl cache list

To remove one or more keys use:

spotdl cache remove <key1> <key2> ...

To clear the entire cache use:

spotdl cache clear

Sometimes it might be usefull to known if a track with a given spotify id is already in your collection. It is possible to achieve this using spotdl scan <dir> and parsing the output, but this command can take a while to run on large collection.

To solve this problem the spotdl watcher commands allow you to monitor one or more directories and query for any existing tracks.

The watcher will listen on a unix socket and watch a set of directories. To start the watcher use:

spotdl watcher watch --scan <dir>

To query the watcher use:

spotdl watcher list         # List all spotify tracks (similar to scan)
spotdl watcher contains     # Check if a track is being watched

Here is an example systemd service that starts the watcher on login:

[Unit]
Description=spotdl watcher

[Service]
Type=simple
Environment=RUST_LOG=debug
ExecStart=/usr/bin/fish -c 'spotdl watcher watch --scan %h/music --scan-exclude %h/music/ephemeral'
RestartSec=10
Restart=always

[Install]
WantedBy=default.target