Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clickwheel.fm/llms.txt

Use this file to discover all available pages before exploring further.

​
auth

clickwheel apple auth [OPTIONS]
Run the Music User Token authorization flow. Opens your browser to sign in with your Apple ID, then saves the token to ~/.clickwheel/.env. One-time per Mac and Apple ID; the token is long-lived but can be revoked. Examples 
# One-time browser authorization
clickwheel apple auth

​
delete

clickwheel apple delete [OPTIONS] NAME
Delete a library playlist from your Apple Music account. macOS-only; the deletion syncs to your other devices via iCloud Music Library. Deletes EVERY playlist matching the name, useful for clearing duplicates from failed pushes.
​
name
string
required
Apple Music library playlist name to delete.
​
--yes, -y
boolean
Skip the confirmation prompt.

​
doctor

clickwheel apple doctor [OPTIONS]
Probe Apple Music end-to-end (config, .p8, dev token, user token, storefront, iCloud Music Library state). Mirrors plex doctor. Examples 
# End-to-end Apple Music probe
clickwheel apple doctor

​
list

clickwheel apple list [OPTIONS]
List every library playlist in your Apple Music account. Read-only. Use before apple pull to find the playlist you want. Manual and smart playlists both appear; smart ones come back with canEdit=false (we can pull them but you can’t push back).

​
match

clickwheel apple match [OPTIONS] NAME
Preview how a playlist’s tracks resolve to Apple Music song IDs. Read-only (creates nothing), but caches the matches so the next apple push is faster. Tracks below --min-confidence are flagged low-confidence for review before pushing. Examples 
# Preview how tracks resolve (no writes)
clickwheel apple match road-trip
​
name
string
required
clickwheel playlist to match.
​
--refresh
boolean
Ignore the cache and re-match every track.
​
--min-confidence
number
default:"0.85"
Threshold between matched and low-confidence.

​
pull

clickwheel apple pull [OPTIONS] NAME
Import an Apple Music library playlist into clickwheel’s local store. Tracks are matched against your library; unmatched rows are reported (usually files Apple has that clickwheel hasn’t scanned yet). Examples 
# Import an Apple Music playlist
clickwheel apple pull road-trip
​
name
string
required
Apple Music playlist to import.
​
--overwrite
boolean
Replace an existing clickwheel playlist with the same name.
​
--min-fuzzy
number
default:"0.85"
Fuzzy-match threshold for unmatched cache entries.

​
push

clickwheel apple push [OPTIONS] NAME
Create a playlist in your Apple Music account from a clickwheel playlist. Low-confidence matches are skipped by default; pass --include-low (after a clickwheel apple match review) to include them. Examples 
# Create the playlist in Apple Music
clickwheel apple push road-trip

# Include low-confidence matches
clickwheel apple push road-trip --include-low
​
name
string
required
clickwheel playlist to push to Apple Music.
​
--refresh
boolean
Ignore the cache and re-match every track.
​
--min-confidence
number
default:"0.85"
Reject matches below this confidence.
​
--include-low
boolean
Push low-confidence matches too (use after reviewing).
​
--yes, -y
boolean
Skip the confirmation prompt.