id = "scdl"
name = "scdl"
homepage = "https://github.com/scdl-org/scdl"
description = "SoundCloud downloader"
executables = ["scdl"]

[dotfiles]

# The upstream CLI source resolves its config to
# $XDG_CONFIG_HOME/scdl/scdl.cfg, falling back to ~/.config/scdl/scdl.cfg.
# The file contains the SoundCloud client ID and auth token, so it is treated
# as a credential-bearing file rather than ordinary syncable content.
# https://github.com/scdl-org/scdl/blob/master/scdl/scdl.py
paths = []
secret = ["[configHome]/scdl/scdl.cfg"]

[commands]
format = 1
label = "Download from SoundCloud"
description = "Download a SoundCloud track, playlist or user's uploads with scdl. Naming formats, size limits, yt-dlp passthrough and credentials are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = false, short_attached = false, short_bundles = false }

[[commands.source]]
id = "help"
kind = "help"
url = "https://github.com/scdl-org/scdl/blob/master/scdl/scdl.py"
revision = "master 2026-10-27"
evidence = """
    -l [url]                        URL can be track/playlist/user
    -a                              Download all tracks of user (including reposts)
    -t                              Download all uploads of a user (no reposts)
    -f                              Download all favorites (likes) of a user
    -p                              Download all playlists of a user
    -r                              Download all reposts of user
    -c                              Continue if a downloaded file already exists
    -o [offset]                     Start downloading a playlist from the [offset]th track
    --onlymp3                       Download only mp3 files
    --path [path]                   Use a custom path for downloaded files
    --download-archive [file]       Keep track of track IDs in an archive file,
    --sync [file]                   Compares an archive file to a playlist and downloads/removes
    --flac                          Convert original files to .flac. Only works if the original
    --no-playlist-folder            Download playlist tracks into main directory,
    --overwrite                     Overwrite file if it already exists
    --no-playlist                   Skip downloading playlists
    --opus                          Prefer downloading opus streams over mp3 streams
"""

[[commands.field]]
id = "url"
label = "SoundCloud URL"
description = "Track, playlist or user URL."
type = "url"
option = ["-l"]
sources = ["help"]

[[commands.field]]
id = "all_tracks"
label = "All tracks of user"
description = "Including reposts."
type = "boolean"
option = ["-a"]
sources = ["help"]

[[commands.field]]
id = "uploads"
label = "Uploads of user"
description = "No reposts."
type = "boolean"
option = ["-t"]
sources = ["help"]

[[commands.field]]
id = "favorites"
label = "Favorites (likes) of user"
type = "boolean"
option = ["-f"]
sources = ["help"]

[[commands.field]]
id = "path"
label = "Download folder"
type = "path"
option = ["--path"]
path = { kind = "directory", role = "output", must_exist = false }
sources = ["help"]

[[commands.field]]
id = "continue"
label = "Continue if file exists"
type = "boolean"
option = ["-c"]
sources = ["help"]

[[commands.field]]
id = "overwrite"
label = "Overwrite existing files"
type = "boolean"
option = ["--overwrite"]
effect = "overwrite"
sources = ["help"]

[[commands.field]]
id = "archive"
label = "Download archive"
description = "Record downloaded track IDs here and skip them next time."
type = "path"
option = ["--download-archive"]
path = { kind = "file", role = "output", must_exist = false }
sources = ["help"]

[[commands.field]]
id = "onlymp3"
label = "Only MP3"
type = "boolean"
option = ["--onlymp3"]
sources = ["help"]

[[commands.field]]
id = "no_playlist_folder"
label = "No playlist subfolder"
type = "boolean"
option = ["--no-playlist-folder"]
sources = ["help"]

[[commands.task]]
id = "single"
label = "Download a track or playlist"
fields = ["url", "path", "continue", "onlymp3"]
required = ["url"]

[[commands.task]]
id = "user-uploads"
label = "Download a user's uploads"
set = { uploads = [true] }
fields = ["url", "uploads", "path", "archive"]
required = ["url"]

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["url", "all_tracks", "uploads", "favorites", "path"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["continue", "overwrite", "archive", "onlymp3", "no_playlist_folder"]