arnef/godeez
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

docs: document credential login and update CLI output

Browse Source
This commit is contained in:
Mathis Maquenne
2026-08-05 10:47:49 +02:00
parent 1fbbd60106
commit 97153c1688
1 changed files with 78 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+78 -45
View File
@@ -12,30 +12,26 @@ A simple Go tool for downloading music from [Deezer](https://www.deezer.com).
[Installation](#installation) • [Installation](#installation) •
[Updating](#updating) • [Updating](#updating) •
[Configuration](#configuration) • [Configuration](#configuration) •
[Usage](#usage) • [Usage](#usage)
[Contributing](#contributing) •
[Support](#support-the-project) •
[License](#license)
</div> </div>
## Features ## Features
- Download playlists, albums, artists’ top tracks, and individual tracks - Download playlists, albums, artists' top tracks, and individual tracks
- Choose audio quality: **MP3 128kbps**, **MP3 320kbps** (default), or **FLAC** (⚠️ non‑premium accounts are limited to 128kbps) - Choose audio quality: MP3 128 kbps, MP3 320 kbps (default), or FLAC (⚠️ non-premium accounts are limited to 128 kbps)
- Authenticate with an ARL cookie or with your Deezer email and password
- Automatically embed metadata tags (artist, album, title, artwork, etc.) - Automatically embed metadata tags (artist, album, title, artwork, etc.)
- Fetch and tag songs with **BPM**, **musical key**, and **genre** - Fetch and tag tracks with BPM, musical key, and genre
- Skip already-downloaded files using hashes and metadata - Works on Windows, macOS, and Linux
- Support Windows, macOS, and Linux
- Provide a simple, easy-to-use CLI
## Installation ## Installation
To install **GoDeez**, download the latest binary for your platform from the [Releases](https://github.com/mathismqn/godeez/releases) page. Prebuilt binaries are available for every release.
1. Go to the [Releases](https://github.com/mathismqn/godeez/releases) page. 1. Go to the [Releases](https://github.com/mathismqn/godeez/releases) page.
2. Download the appropriate binary for your operating system and architecture, named `godeez_<version>_<os>_<arch>`. 2. Download the appropriate binary for your operating system and architecture, named `godeez_<version>_<os>_<arch>`.
3. (Optional) Move the binary to a directory included in `$PATH` for easier access. 3. (Optional) Move the binary to a directory on your `$PATH` for easier access.
Example (Linux/macOS): Example (Linux/macOS):
@@ -45,7 +41,7 @@ chmod +x godeez_1.5.0_linux_amd64
mv godeez_1.5.0_linux_amd64 /usr/local/bin/godeez mv godeez_1.5.0_linux_amd64 /usr/local/bin/godeez
``` ```
Every release also ships a `checksums.txt`, so you can verify a download: Each release also includes a `checksums.txt`, so you can verify your download:
```bash ```bash
sha256sum -c checksums.txt --ignore-missing sha256sum -c checksums.txt --ignore-missing
@@ -54,7 +50,8 @@ sha256sum -c checksums.txt --ignore-missing
### macOS ### macOS
The macOS binaries are not signed with an Apple Developer certificate, so The macOS binaries are not signed with an Apple Developer certificate, so
Gatekeeper blocks them the first time. Clear the quarantine flag once: Gatekeeper blocks them on first run. You only need to clear the quarantine flag
once:
```bash ```bash
xattr -d com.apple.quarantine /usr/local/bin/godeez xattr -d com.apple.quarantine /usr/local/bin/godeez
@@ -62,10 +59,10 @@ xattr -d com.apple.quarantine /usr/local/bin/godeez
## Updating ## Updating
**GoDeez** can replace itself with the latest release: **GoDeez** can update itself to the latest release:
```bash ```bash
# See whether a new version exists # Check for a new version
godeez update --check godeez update --check
# Download, verify, and install it # Download, verify, and install it
@@ -76,13 +73,13 @@ The new binary is verified against the release's published SHA256 checksum
before it replaces the current one. If **GoDeez** lives in a directory you do before it replaces the current one. If **GoDeez** lives in a directory you do
not own (such as `/usr/local/bin` on some systems), run `sudo godeez update`. not own (such as `/usr/local/bin` on some systems), run `sudo godeez update`.
To disable the notice about new versions: To disable new-version notifications:
```bash ```bash
export GODEEZ_NO_UPDATE_CHECK=1 export GODEEZ_NO_UPDATE_CHECK=1
``` ```
To see what you are running: To check which version you are running:
```bash ```bash
godeez version godeez version
@@ -90,7 +87,11 @@ godeez version
## Configuration ## Configuration
**GoDeez** requires a Deezer ARL cookie for authentication. Set it as an environment variable: **GoDeez** authenticates to Deezer in one of two ways: with an **ARL cookie** copied from your browser, or with your **email and password**. The ARL cookie works out of the box and is the recommended option; email/password login requires two extra keys that **GoDeez** does not ship (see below).
### ARL cookie
Set your ARL cookie as an environment variable:
```bash ```bash
export DEEZER_ARL="your_arl_cookie_here" export DEEZER_ARL="your_arl_cookie_here"
@@ -98,29 +99,60 @@ export DEEZER_ARL="your_arl_cookie_here"
To make it persistent, add the line above to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.). To make it persistent, add the line above to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.).
### How to retrieve your ARL cookie #### How to retrieve your ARL cookie
1. Open your browser and log in to your [Deezer](https://www.deezer.com) account. 1. Open your browser and log in to your [Deezer](https://www.deezer.com) account.
2. Open the Developer Tools (right-click on the page and select “Inspect” or press F12). 2. Open the **Developer Tools** (right-click on the page and select **Inspect**, or press <kbd>F12</kbd>).
3. Navigate to the **Application** tab (Chrome/Edge) or **Storage** tab (Firefox). 3. Navigate to the **Application** tab (Chrome/Edge) or **Storage** tab (Firefox).
4. In the left panel, look for **Cookies** and select `https://www.deezer.com`. 4. In the left panel, look for **Cookies** and select **https://www.deezer.com**.
5. Find the `arl` cookie and copy its value. 5. Find the `arl` cookie and copy its value.
> **Note:** The ARL cookie may expire after some time. If you get authentication errors, retrieve a fresh cookie using the steps above. > **Note:** The ARL cookie may expire after some time. If you get authentication errors, retrieve a fresh cookie using the steps above.
### Email and password
Instead of copying a cookie, you can log in once with your Deezer account:
```bash
godeez login
```
You will be prompted for your email and password. On success, **GoDeez** stores your credentials in your system keyring under the service name `godeez`. From then on, **GoDeez** authenticates on its own and renews the session when it expires.
To remove the stored credentials:
```bash
godeez logout
```
#### Gateway keys
Email/password login goes through Deezer's mobile gateway, which requires two keys:
```bash
export DEEZER_MOBILE_API_KEY="your_api_key_here"
export DEEZER_MOBILE_GW_KEY="your_gateway_key" # exactly 16 characters
```
**GoDeez** does not bundle these keys, so you have to supply your own. For background on what they are and where they live in Deezer's clients, see [this write-up](https://gist.github.com/svbnet/b79b705a4c19d74896670c1ac7ad627e). If either variable is missing, `godeez login` exits with an error.
> **Note:** `DEEZER_ARL` takes precedence over stored credentials. If it is set, **GoDeez** always uses the cookie and never falls back to your login, so unset it (and remove it from your shell profile) before running `godeez login`.
> **Note:** The keyring entry holds your password alongside the ARL because the password is reused to renew expired sessions. On Linux, the keyring requires a running secret service; without one, `godeez login` fails with `system keyring is unavailable`.
### Output directory ### Output directory
Downloaded files are saved to `~/Music/GoDeez`. The download database (`.tracks.db`) is stored alongside your music in the output directory. Downloaded files are saved to `~/Music/GoDeez`. The download database (`.tracks.db`) is stored in the same directory as your music.
> **Upgrading from v1.3.0?** The `~/.godeez` directory and `config.toml` are no longer used. Set the `DEEZER_ARL` environment variable instead. Your existing database will be migrated automatically on first run. > **Upgrading from v1.3.0?** The `~/.godeez` directory and `config.toml` are no longer used. Set the `DEEZER_ARL` environment variable instead. Your existing database will be migrated automatically on first run.
## Usage ## Usage
### CLI Overview ### CLI overview
Running `godeez` without arguments shows the help menu: Running `godeez` without arguments shows the help menu:
```bash ```text
GoDeez is a tool to download music from Deezer GoDeez is a tool to download music from Deezer
Usage: Usage:
@@ -128,10 +160,12 @@ Usage:
Available Commands: Available Commands:
completion Generate the autocompletion script for the specified shell completion Generate the autocompletion script for the specified shell
download Download songs from Deezer download Download tracks from Deezer
help Help about any command help Help about any command
login Log in to Deezer with your email and password
logout Remove stored Deezer credentials
update Update GoDeez to the latest version update Update GoDeez to the latest version
version Print the GoDeez version version Print the current version of GoDeez
Flags: Flags:
-h, --help help for godeez -h, --help help for godeez
@@ -141,16 +175,16 @@ Use "godeez [command] --help" for more information about a command.
### Download commands ### Download commands
```bash ```text
Download songs from Deezer Download tracks from Deezer
Usage: Usage:
godeez download [command] godeez download [command]
Available Commands: Available Commands:
album Download songs from an album album Download tracks from an album
artist Download top songs from an artist artist Download an artist's top tracks
playlist Download songs from a playlist playlist Download tracks from a playlist
track Download a single track track Download a single track
Flags: Flags:
@@ -158,7 +192,7 @@ Flags:
--genre fetch genre and add to file tags --genre fetch genre and add to file tags
-h, --help help for download -h, --help help for download
-q, --quality string download quality [mp3_128, mp3_320, flac] (default "mp3_320") -q, --quality string download quality [mp3_128, mp3_320, flac] (default "mp3_320")
--strict fail the song download if the quality is not available --strict fail the download if the requested quality is unavailable
-t, --timeout duration timeout for each download (e.g. 10s, 1m, 2m30s) (default 2m0s) -t, --timeout duration timeout for each download (e.g. 10s, 1m, 2m30s) (default 2m0s)
Use "godeez download [command] --help" for more information about a command. Use "godeez download [command] --help" for more information about a command.
@@ -173,32 +207,31 @@ godeez download album 12345678
# Download a playlist # Download a playlist
godeez download playlist 87654321 godeez download playlist 87654321
# Download top tracks from an artist # Download an artist's top tracks (limit to 5 tracks)
godeez download artist 11223344 --limit 5 godeez download artist 11223344 --limit 5
# Download a single track # Download a single track
godeez download track 98765432 godeez download track 98765432
# Download with specific quality, BPM and genre data # Download with specific quality, BPM, and genre data
godeez download track 98765432 --quality flac --bpm --genre godeez download track 98765432 --quality flac --bpm --genre
``` ```
## Contributing ## Contributing
Contributions help make **GoDeez** a better tool for everyone, and any help is greatly appreciated. Contributions make **GoDeez** better for everyone, and any help is greatly appreciated — whether it's a bug fix, a new feature, or a documentation improvement.
Whether it’s a bug fix, a new feature, or improving documentation, your input is valuable.
If you have an idea for improvement, feel free to fork the repository and submit a pull request. You can also open an issue if you spot a bug or have a feature suggestion. To contribute, fork the repository and open a pull request. To report a bug or suggest a feature, open an issue instead.
## Support the Project ## Support the project
If **GoDeez** helps you enjoy your music collection, please consider giving it a ⭐! If **GoDeez** helps you enjoy your music collection, please consider giving it a star ⭐
**Why star us?** **Why star the project?**
- Helps more music lovers discover the project - Helps more music lovers discover it
- Shows appreciation for the work and motivates development - Shows appreciation for the work and keeps me motivated
- Takes just one click but means the world to us! - Takes one click, and it means a lot
## License ## License
@@ -206,4 +239,4 @@ This project is licensed under the MIT License. See the [LICENSE](https://github
--- ---
> ⚠️ This tool is provided for educational and personal use only. Please ensure your usage complies with Deezer’s Terms of Service. > ⚠️ This tool is provided for educational and personal use only. Please ensure your usage complies with Deezer's Terms of Service.