Skip to main content
clickwheel reads runtime settings from ~/.clickwheel/config.yaml. Only music_dir is required.

​
Minimal config

~/.clickwheel/config.yaml

​
Settings

Environment variables override the config file. Each is the setting name in UPPER_CASE (e.g. MUSIC_DIR), except the library_* settings, which add a CLICKWHEEL_ prefix.

​
Integration settings

Plex, Apple Music, and Last.fm each add their own settings (server URLs, tokens, API keys, path remap). Set them up in their guides, and keep secrets in ~/.clickwheel/.env rather than in config.yaml:

​
How auto-scan works

select, edit, diff, and sync auto-scan when the catalog looks stale, via a cheap two-tier check:
  1. Probe: re-scans if a top-level folder in music_dir is newer than the last scan (a new artist or album).
  2. Fallback: re-scans anyway once auto_scan_staleness_minutes has elapsed, catching tracks added inside existing albums that the probe can’t see.
The probe is much cheaper than a full scan, so it runs on every command without slowing you down.
  • Pass --no-scan to any command to skip both tiers and use cached data.
  • Set auto_scan: false to disable it for the whole session.
  • Lower auto_scan_staleness_minutes if you often add tracks inside existing albums and want the fallback to fire sooner.
The probe can’t see metadata-only edits inside files. After clickwheel fix or any external tag editor, run clickwheel scan so the catalog picks up the new tags. The MCP server never auto-scans: run clickwheel scan in a terminal and the next chat session sees the change.

​
MCP server environment

The MCP server is configured by environment variables (not the YAML file), all prefixed CLICKWHEEL_MCP_. The default transport is stdio for local desktop clients, which needs none of these; the rest configure the HTTP transport for remote access (see Remote / mobile access). The HTTP server binds 127.0.0.1:8000/mcp by default; the HOST, PORT, and PATH vars override that if needed.

​
Where data lives

clickwheel stores its catalog at ~/.clickwheel/clickwheel.db (SQLite). The location isn’t configurable. The database is safe to delete; clickwheel scan rebuilds it from your music directory.