Apple Music

clickwheel syncs playlists to and from your Apple Music account through the official MusicKit API. Playlists propagate to your other Apple devices via iCloud Music Library.

Apple Music sync needs a paid Apple Developer Program membership to create the MusicKit key. The other integrations don’t.

Setup

Install the Apple Music extra

pipx inject clickwheel 'clickwheel[applemusic]'

Create a MusicKit key

At developer.apple.com → Keys, create a key with Media Services (MusicKit) enabled and download the .p8.

Configure clickwheel

~/.clickwheel/config.yaml

apple_music_enabled: true
apple_music_storefront: us
apple_music_key_id: <Key ID, 10 chars>
apple_music_team_id: <Team ID, top-right of developer.apple.com>
apple_music_key_file: /Users/you/.clickwheel/AuthKey_<KEYID>.p8

chmod 600 the .p8.

Authorize and verify

clickwheel apple auth     # one-time browser sign-in; mints a user token
clickwheel apple doctor   # nine-stage end-to-end probe

auth opens MusicKit JS in your browser; sign in with your Apple ID. The doctor checks config, the .p8, both tokens, iCloud Music Library state, and storefront. Per-stage detail tells you what to fix.

Push, pull, delete

Command	What it does
`clickwheel apple list`	List your Apple Music library playlists
`clickwheel apple match <name>`	Preview how tracks resolve (no writes)
`clickwheel apple push <name>`	Create the playlist in Apple Music
`clickwheel apple pull <name>`	Import an Apple Music playlist into clickwheel
`clickwheel apple delete <name>`	Remove an Apple Music playlist

Pull is handy when you curated on your iPhone and want it on the iPod. Delete drives Music.app via AppleScript, because Apple’s REST API refuses to delete library playlists; the deletion propagates through iCloud Music Library.

How push matches tracks

Push resolves each track via a match ladder: ISRC tag → catalog fuzzy search (title/artist/album weighted) → your library when iCloud Music Library is on. Low-confidence matches are skipped unless you pass --include-low. Resolved IDs cache in SQLite, so repeat pushes skip the network.

Two tokens, briefly

MusicKit needs a developer token (a JWT clickwheel signs locally with your .p8, re-signed on demand) and a Music User Token (long-lived, minted in the browser by apple auth). Catalog reads need only the developer token; anything touching your library needs both. If you already have a pre-signed JWT from another project, set APPLE_MUSIC_DEVELOPER_TOKEN and the .p8/Key ID/Team ID become optional.

From Claude

You can also drive this from Claude. Set up the MCP server, then the Apple Music tools are yours.

Getting started

Everyday use

Integrations

Claude (MCP)

Concepts

Help

Setup

Push, pull, delete

From Claude

​Setup

​Push, pull, delete

​From Claude

Setup

Push, pull, delete

From Claude