crabidy/docs/src/config.md

Configuration

Crabidy reads its configuration from TOML files in ~/.config/crabidy/, the platform config directory. Every file is optional. On first start each component writes its own file filled in with defaults, then reads it back — so a fresh install runs with sensible values and leaves you an editable file for each piece. A provider whose config fails to load simply does not mount; it does not stop the server.

Which providers mount at all is controlled by crabidy-server.toml (see Enabling and disabling providers), which the server now also writes on first start.

The config files

File	Component	Auto-created
tidaly.toml	Tidal	yes
ytdy.toml	YouTube	yes
fyyd.toml	podcasts	yes
fsdy.toml	local fs	yes
cbd-tui.toml	cbd-tui	yes
cbd.toml	cbd	yes
crabidy-server.toml	server	yes

• tidaly.toml, ytdy.toml, fyyd.toml, and fsdy.toml configure the media providers — Tidal, YouTube, fyyd podcasts, and a local music folder (its filesystem root). See Providers.
• cbd-tui.toml and cbd.toml are client configs (below).
• crabidy-server.toml holds the enabled-providers list (below) and server auth (see Roles and authorization).

Enabling and disabling providers

On first start the server writes crabidy-server.toml with every provider enabled:

providers = ["tidal", "youtube", "fyyd", "fs", "crabidy", "orphans"]

Remove a name to disable that provider — it no longer mounts and drops out of the library tree; its own config file (e.g. tidaly.toml) is then left unread. Deleting the whole providers line re-enables everything (the same as a fresh install with no file). Because orphans is a view over the store, disabling crabidy disables orphans too.

Client config: cbd-tui.toml and cbd.toml

cbd-tui (the standalone terminal client) reads cbd-tui.toml; cbd (server plus TUI in one process) reads its own cbd.toml. They are separate files with the same options so the two can run side by side on one machine: a common setup is cbd playing locally against its in-process server while cbd-tui, pointed at a remote server (a Raspberry Pi, say), acts as a remote control. A single shared file would force one use to follow the other's address.

Both live under a [server] table:

[server]
# Where to find the server. Default (both files): localhost, which is
# what cbd's own in-process server listens on. Point cbd-tui.toml at a
# remote server to drive it as a remote control.
address = "http://127.0.0.1:50051"

# Credentials, used only when the server has [auth] configured.
# `user` is the role name (see ./auth.md); leave both empty against an
# open server.
user = ""
password = ""

# Show the frequency-spectrum bars under the track progress.
spectrum = true

Every option is also a command-line flag, given before the subcommand (cbd-tui --address http://pi:50051 --user owner, cbd --spectrum false). A provided flag overrides the file value; an omitted flag leaves the file value in place. To write credentials into the config once instead of editing by hand, use the auth subcommand (see Command line):

cbd-tui auth owner 'my-password'
cbd-tui auth queue-owner 'pw' --address http://pi:50051

`password` is stored in **plaintext** — the client always holds a
plaintext credential, not a hash. Keep the client config file private.
The password is never written to logs.

For the client's spectrum option in context, see The terminal client.

Where the server's own data lives

The server-managed crabidy provider does not live under ~/.config. Following the XDG split, its two parts sit in two roots:

• ~/.local/state/crabidy/ — the provider's TOML tree: the track files for your saved queues, bookmarks, and captures (the /crabidy library subtree). This is state.
• ~/.local/share/crabidy/ — the content-addressed audio store: the actual playable files that captures download, shared and de-duplicated across every save. This is data.

Neither needs configuration; both start empty and the server manages them. See The crabidy store for how saves, captures, and de-duplication work.

Client and TUI log files also go to ~/.local/state/crabidy/. The provider ignores non-track files there, so the logs do not show up in the library.