id       = "beets"
name     = "beets"
homepage = "https://beets.io"
description = "The media library management system for obsessive music geeks."
# The beet, from the documentation's static assets.
icon     = "https://raw.githubusercontent.com/beetbox/beets/master/docs/_static/beets_logo_nobg.png"
executables   = ["beet"]

[dotfiles]

# https://beets.readthedocs.io/en/stable/reference/config.html, "Location":
# the config file is ~/.config/beets/config.yaml on Unix,
# ~/Library/Application Support/beets/config.yaml on macOS and
# %APPDATA%\beets\config.yaml on Windows — the three spellings of one place,
# which is what [appData] names. (The same page notes macOS also honours
# ~/.config/beets, and $BEETSDIR overrides all of it.)
paths = ["[appData]/beets/config.yaml"]

# library.db (the library database) and state.pickle sit in the same directory
# and are data, not configuration. Neither is named above, so there is nothing
# to carve out of what is.
exclude = []

# config.yaml is not a credential end to end — it is the import policy, the
# path formats and the plugin list. Only the plugin keys are lifted out below.
secret = []

# The library location. "directory: The path to the directory where you'd like
# to keep your music" and "library: The path to the beets library file"
# (reference/config.html) — both absolute paths into this machine's disk, and
# the one thing in the file that does not survive a move to another machine.
# They are also where the user's music and library actually sit, which is the
# first thing they would need back after a rebuild, so both are kept: backup.
[[dotfiles.machine_lines]]
file  = "[appData]/beets/config.yaml"
match = { key_path = ["directory", "library"] }
scope = "backup"

# Plugin credentials that live in the same file: the Discogs plugin documents
# `user_token` and `apikey`
# (https://beets.readthedocs.io/en/stable/plugins/discogs.html) and the Spotify
# plugin documents `client_secret`
# (https://beets.readthedocs.io/en/stable/plugins/spotify.html).
[[dotfiles.secret_paths]]
file  = "[appData]/beets/config.yaml"
match = { key_path = ["discogs.user_token", "discogs.apikey", "spotify.client_secret"] }

[commands]
format = 1
label = "beets"
description = "Import music into the library and query it. Other beet subcommands and plugin options are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.subcommand]]
path = ["import"]
label = "Import music"
description = "Import files or directories into the library. Archives, incremental and resume options are left out."

[[commands.subcommand.source]]
id = "cli"
kind = "manual"
url = "https://beets.readthedocs.io/en/stable/reference/cli.html"
revision = "master 2026-10-27"
evidence = """
beet import [-CMWAPRqst] [-l LOGPATH] PATH...
the ``-m`` (move) option.
``-C`` (don't copy), ``-M`` (don't move), and ``-W`` (don't write tags) options.
using ``-A`` (don't
the ``-l`` option to
the ``-q`` (quiet) option
the ``-t`` (for *timid*) option.
supplying the ``-s`` option.
use the ``--flat`` option.
use the ``--pretend``
``--set field=value``
"""

[[commands.subcommand.field]]
id = "copy"
label = "Move files instead of copying"
type = "boolean"
option = ["-m"]
effect = "overwrite"
sources = ["cli"]

[[commands.subcommand.field]]
id = "no_copy"
label = "Don't copy files"
type = "boolean"
option = ["-C"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "no_write"
label = "Don't write tags"
type = "boolean"
option = ["-W"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "no_autotag"
label = "Don't autotag"
type = "boolean"
option = ["-A"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "quiet"
label = "Quiet (no prompts)"
type = "boolean"
option = ["-q"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "timid"
label = "Timid (confirm every match)"
type = "boolean"
option = ["-t"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "singletons"
label = "Import as singletons"
type = "boolean"
option = ["-s"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "flat"
label = "Flat (one album per directory)"
type = "boolean"
option = ["--flat"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "pretend"
label = "Preview only"
type = "boolean"
option = ["--pretend"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "logpath"
label = "Log skipped items to file"
type = "path"
option = ["-l"]
path = { kind = "file", role = "output" }
sources = ["cli"]

[[commands.subcommand.field]]
id = "paths"
label = "Files or directories"
type = "path"
position = 0
multiple = true
min = 1
path = { kind = "any", role = "input", must_exist = true }
sources = ["cli"]

[[commands.subcommand.task]]
id = "import"
label = "Import (copy files)"
fields = ["paths", "quiet", "pretend"]
required = ["paths"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["paths", "copy", "pretend", "quiet"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["no_copy", "no_write", "no_autotag", "timid", "singletons", "flat", "logpath"]

[[commands.subcommand]]
path = ["list"]
label = "Query the library"
description = "List matching tracks or albums. Query syntax is passed through as typed."

[[commands.subcommand.source]]
id = "cli"
kind = "manual"
url = "https://beets.readthedocs.io/en/stable/reference/cli.html"
revision = "master 2026-10-27"
evidence = """
beet list [-apf] [-l LIMIT] QUERY
You can use the ``-a`` switch to search for albums instead of individual items.
Use the ``-l LIMIT`` (``--limit=LIMIT``) flag
The ``-p`` option makes beets print out filenames of matched items
the ``-f`` option lets you specify a specific format
"""

[[commands.subcommand.field]]
id = "albums"
label = "Albums instead of tracks"
type = "boolean"
option = ["-a"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "paths"
label = "Print file paths"
type = "boolean"
option = ["-p"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "format"
label = "Output format"
description = "Template such as '$album: $albumtotal'."
type = "string"
option = ["-f"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "limit"
label = "Limit"
type = "integer"
option = ["--limit", "-l"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "query"
label = "Query"
type = "string"
position = 0
multiple = true
sources = ["cli"]

[[commands.subcommand.task]]
id = "search"
label = "Search"
fields = ["query", "albums"]
required = ["query"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["query", "albums", "paths", "format", "limit"]