npm package: @leokok/poke-apple-music
Description: Clone poke-music, install editable, run Apple Music MCP + Poke tunnel
Latest version: 0.4.0

# @leokok/poke-apple-music (npm)

## Fast start

`npx @leokok/poke-apple-music` or **`npx poke-music`** runs a **readiness check** first (macOS, **Homebrew** as optional, Git, Node/npx, Python 3.10+, Poke login). Missing Homebrew does **not** block the run.  
If something required is missing, it asks **y/n** and tries, in order:

- **Official [Homebrew](https://brew.sh) install script** when brew is absent and you need Git/Node/Python  
- **Batch `brew install`** `git`, `node`, and/or `python@3.12` when Homebrew is already available  
- **Git:** `xcode-select --install` (Command Line Tools), then opening [git-scm.com/mac](https://git-scm.com/download/mac)  
- **Node:** **fnm**, **nvm**, or **asdf** if detected, then opening [nodejs.org](https://nodejs.org/en/download/) — the CLI also tries to refresh `PATH` in-process after brew/fnm/nvm  
- **Python:** **pyenv** if present, then [python.org macOS](https://www.python.org/downloads/macos/)  
- **`npx poke@latest login`** (you finish in the browser)

Only after everything passes does it **clone or update** [poke-music](https://github.com/leoakok/poke-music) under `~/.local/share/poke-apple-music/repo` (**each run** fast-forwards with `git pull`, with a fallback for shallow clones), then **`pip install -e`** when `HEAD` changes, start the MCP server, and run **`poke tunnel`**.

If **`APPLE_MUSIC_MCP_PORT`** (default **8765**) is busy, the CLI picks the **next free port** and passes it to Python and **`poke tunnel`** (opt out with **`APPLE_MUSIC_STRICT_PORTS=1`**).

While the bridge runs, Python stderr shows **short, useful lines** (e.g. what tool ran: search, play, pause) instead of raw MCP noise. For full SDK logs, set **`POKE_APPLE_MUSIC_RAW_SDK_LOG=1`**.

**Updating:** New **CLI** behavior comes from the **npm package** version — use `npx @leokok/poke-apple-music@latest` or **`npx poke-music@latest`** (same CLI). New **Python/repo** changes on GitHub are picked up on the next run via **git** in that cache (no need to bump npm for repo-only fixes, unless you change the CLI).

Non-interactive / CI: **`npx @leokok/poke-apple-music --yes`** or **`POKE_APPLE_MUSIC_YES=1`** (auto-attempts the same fixes without prompts; still needs a TTY for `poke login` unless already logged in).

Set a custom tunnel label with **`-n/--name`**:

```bash
npx @leokok/poke-apple-music@latest --name "Work Mac"
# or
npx poke-music@latest -n "Work Mac"
```

There is **no** PyPI `mcp-applemusic` dependency — only this repo + `mcp`.

## Requirements

- **git** on your `PATH`
- **macOS**, **Python 3.10+**, **Node 18+**
- `npx poke@latest login` completed once

## Usage

```bash
npx @leokok/poke-apple-music
# or (same tool):
npx poke-music
```

The scoped package installs binaries **`poke-apple-music`** and **`poke-music`**. The unscoped [`poke-music`](https://www.npmjs.com/package/poke-music) package installs **`poke-music`** only.

Fork / mirror:

```bash
export POKE_APPLE_MUSIC_REPO="https://github.com/you/poke-music.git"
npx @leokok/poke-apple-music
```

## Local development

Use the repository root for development, not the npm package folder:

```bash
cd poke-music
npm install
node npm/poke-apple-music/cli.mjs --help
node npm/poke-apple-music/cli.mjs
```

## Cache layout

| Path | Contents |
|------|----------|
| `~/.local/share/poke-apple-music/repo` | Git clone of the repo |
| `~/.local/share/poke-apple-music/venv` | Python venv |
| `~/.local/share/poke-apple-music/installed-git-head` | Last `pip install -e` revision |

After a `git pull` changes `HEAD`, the next run reinstalls editable.

## CLI options

```bash
poke-apple-music --help
```

- `-h`, `--help` show usage
- `-v`, `--version` print launcher version
- `-y`, `--yes` run non-interactively
- `-n`, `--name <label>` set the `poke tunnel -n` display label

## Publish

From **`poke-music/npm/poke-apple-music`**:

```bash
npm publish --access public
```

The short name **`poke-music`** is a [separate package](../poke-music/) — bump **both** `package.json` versions together, then `cd ../poke-music && npm publish --access public` (or rely on CI).

## NO_COLOR

Set `NO_COLOR=1` for plain output.

## Troubleshooting (what the CLI tries to tell you)

| Situation | What to do |
|-----------|------------|
| Not macOS | Run on a Mac with the Music app. |
| No `git` | `xcode-select --install` or `brew install git`. |
| No `python3` | Install from [python.org](https://www.python.org/downloads/macos/) or `brew install python`. Optional: `POKE_APPLE_MUSIC_PYTHON`. |
| Not logged into Poke | `npx poke@latest login`. |
| `git pull` / update failed | See message; often offline, divergent local edits in the cache, or permission. Wipe cache: `rm -rf ~/.local/share/poke-apple-music`. |
| Clone / pip errors | Check internet; confirm `POKE_APPLE_MUSIC_REPO`; reset cache with `rm -rf ~/.local/share/poke-apple-music`. |
| Port already in use | The CLI tries the next free port after `APPLE_MUSIC_MCP_PORT` (default 8765). Use `APPLE_MUSIC_STRICT_PORTS=1` to fail instead of auto-bumping. |
| MCP crashes on start | Open an issue on GitHub with the Python traceback (run `pip install -e` from a clone to debug). |
| Don’t want prompts | `npx @leokok/poke-apple-music --yes` or `POKE_APPLE_MUSIC_YES=1` (still need Poke login unless already done). |
| `poke login` in a script | Log in once in a normal terminal; `--yes` won’t complete OAuth for you. |