> ## 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.

# Apple Music

> Push clickwheel playlists to your Apple Music library and pull them back via MusicKit.

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.

<Note>
  Apple Music sync needs a **paid Apple Developer Program** membership to create
  the MusicKit key. The other integrations don't.
</Note>

## Setup

<Steps>
  <Step title="Install the Apple Music extra">
    ```bash theme={null}
    pipx inject clickwheel 'clickwheel[applemusic]'
    ```
  </Step>

  <Step title="Create a MusicKit key">
    At [developer.apple.com → Keys](https://developer.apple.com/account/resources/authkeys/list),
    create a key with **Media Services (MusicKit)** enabled and download the
    `.p8`.
  </Step>

  <Step title="Configure clickwheel">
    ```yaml title="~/.clickwheel/config.yaml" theme={null}
    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`.
  </Step>

  <Step title="Authorize and verify">
    ```bash theme={null}
    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.
  </Step>
</Steps>

## 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](https://developer.apple.com/forums/thread/107807);
the deletion propagates through iCloud Music Library.

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## From Claude

You can also drive this from Claude. Set up the
[MCP server](/concepts/mcp-server), then the
[Apple Music tools](/reference/mcp-tools/apple-music) are yours.