Apple Music CLI (am)

Manage Apple Music from your terminal. Create playlists, import songs, and control your library with simple commands.

Features

• 🎵 List playlists - View all your Apple Music playlists
• ➕ Create playlists - Make new playlists instantly
• 📥 Import songs - Bulk import from text/CSV files
• 🔍 Add songs - Search and add from your library
• 🗑️ Delete playlists - Clean up your collection
• 📋 Show tracks - List contents of any playlist
• 🔄 Retry logic - Automatically retries failed AppleScript calls
• 📊 Progress tracking - See import progress with summary reports

Installation

From Source

# Clone the repository
git clone https://github.com/YOUR_USERNAME/apple-music-cli.git
cd apple-music-cli

# Install to local bin
mkdir -p ~/.local/bin
cp bin/am-cli ~/.local/bin/am
chmod +x ~/.local/bin/am

# Add to PATH if needed
export PATH="$HOME/.local/bin:$PATH"

Homebrew (Future)

brew tap your-tap/apple-music-cli
brew install apple-music-cli

Requirements

• macOS with Music app (pre-installed)
• Python 3.x (pre-installed on macOS)
• Active Apple Music subscription (for songs to be available)

Usage

Basic Commands

# List all your playlists
$ am list

# Create a new playlist
$ am create "Workout Mix"

# Show playlist contents
$ am show "Workout Mix"

# Delete a playlist
$ am delete "Old Playlist"

Import from File

Create a text file with one song per line:

$ cat songs.txt
Queen - Bohemian Rhapsody
The Beatles - Hey Jude
Led Zeppelin - Stairway to Heaven

Then import:

$ am import "Workout Mix" songs.txt

📁 Importing 3 songs to 'Workout Mix'

🎵 Activating Music app...
📋 Loading current playlist...
   Playlist has 0 songs

[01/03] Searching: Queen - Bohemian Rhapsody
      ❌ Song not found in library
[02/03] Searching: The Beatles - Hey Jude
      ❌ Song not found in library
[03/03] Searching: Led Zeppelin - Stairway to Heaven
      ❌ Song not found in library

==================================================
📊 IMPORT SUMMARY
==================================================

   ✅ Added:      0
   ❌ Not Found:  3
   ⚠️  Errors:     0
   ⏭️  Skipped:    0

   Total:        3

📝 Results saved to: ~/am_import_Workout_Mix_20260222_114030.json

Add Individual Song

$ am add "Favourites" "Queen"

🔍 Searching: Queen
   To playlist: Favourites

   ✅ Added: Bohemian Rhapsody - Queen

Important Limitations

⚠️ Local Library Only: This tool searches your Apple Music library (songs you've downloaded or purchased).

To search the full Apple Music catalog (95M songs) and add any song, you need:

• Apple Music API access
• $99/year Apple Developer Program membership

This is a deliberate Apple limitation, not a bug.

Architecture

am/
├── bin/
│   └── am-cli          # Main CLI executable
├── SKILL.md            # OpenClaw skill documentation
├── _meta.json          # Skill metadata
├── LICENSE             # MIT License
└── README.md           # This file

How It Works

1. AppleScript Bridge: Communicates with Music app via osascript
2. Retry Logic: Automatically retries failed AppleScript calls (max 3)
3. State Persistence: Saves import results to JSON for later review
4. Error Handling: Gracefully handles failures, continues processing

Technical Stack

• Language: Python 3
• Interface: CLI via argparse
• Apple Integration: AppleScript (osascript)
• License: MIT

Future Roadmap

Phase 1: Core (Current)

• ✅ Playlist CRUD via AppleScript
• ✅ Song import from file
• ✅ Retry and error handling

Phase 2: Catalog Access (Requires $99/yr Dev Account)

• 🔲 Apple Music API integration
• 🔲 Search full catalog (95M songs)
• 🔲 Add songs from catalog to library

Phase 3: Advanced Features

• 🔲 Cross-platform sync (Spotify, YouTube Music)
• 🔲 Smart playlists
• 🔲 API for automation
• 🔲 Web UI

Development

# Clone repo
git clone https://github.com/YOUR_USERNAME/apple-music-cli.git
cd apple-music-cli

# Test locally
python3 bin/am-cli list

# Run tests
# (coming soon)

Why Not Use Apple's App?

Feature	Apple Music App	am CLI
GUI	✅	❌
Bulk import from file	❌	✅
Automation/scriptable	❌	✅
Cross-platform (w/ API)	❌	✅ (future)
Terminal-native	❌	✅

Similar Projects

Project	Language	Notes
ryanccn/am	Rust	Playback control, Discord Rich Presence
mcthomas/Apple-Music-CLI-Player	Shell	Basic controller script
Cider	Electron	Paid ($3.99), GUI client

Troubleshooting

"Song not found in library"

The song must be in your Apple Music library (downloaded or purchased). This tool cannot search the Apple Music streaming catalog without API access.

Solution: Add the song to your library in the Music app first.

"AppleScript error"

# Test AppleScript manually
osascript -e 'tell app "Music" to activate'

# If that fails, check:
# 1. Music app is installed
# 2. Music app is not restricted
# 3. osascript is available: which osascript

Permission Issues

If you see permission errors, grant Terminal access to:

• System Settings → Privacy & Security → Automation → Terminal
• System Settings → Privacy & Security → Apple Events → Terminal

License

MIT License - see LICENSE file

Contributing

Pull requests welcome! Areas for contribution:

• Apple Music API integration
• Better error messages
• More import formats (CSV, JSON)
• Cross-platform support
• Tests

Acknowledgments

• Inspired by ryanccn/am
• Built for the OpenClaw ecosystem
• ryanccn's work showed the potential, this extends it

---

Built with 🎵 by OpenClaw