_
________________( )_____
.-' o `-.
.' . \
/ | ,-"
| ____.'--'
\ __.-'
`.| |`----------'| |'
|__| |__|
A music CLI that lives in your terminal. Search, control playback, and sync your Spotify, Apple Music and YouTube Music playlists to your own Google Drive.
Three steps, from the bottom up: first let capy reach your music platforms, then decide whether to sync your playlists to the cloud. capy's interface is in English by default; capy config set language zh-TW switches it to Traditional Chinese.
capy doesn't hold anyone's credentials, so the Spotify half uses your own app. Create one in the Spotify Developer Dashboard and set its redirect URI to http://127.0.0.1:8888/callback. It has to be 127.0.0.1: Spotify rejects localhost.
$ capy auth login spotify
# the wizard asks for the client ID, then opens the browser to finish authorization
You can start right away, with no other setup. Search prints its results directly: an aligned table in a terminal, clean TSV in a pipeline.
$ capy search Yellow
$ capy play Coldplay # an artist: plays their top tracks
$ capy now # what's playing
The master copies of your playlists live in the application data folder of your own Google Drive (only capy can see it, and you can clear it at any time). Only this step needs a Google login, and it asks for just three permissions: your identity, your email address, and the application data folder.
$ capy auth login google
$ capy pl link Commute spotify:Commute # link a platform playlist
$ capy pl sync Commute # two-way sync
Type capy in a terminal, with no arguments. The capybara at the start twitches its ears, blinks, eats the grass in its mouth down to a stub and picks up a new stalk. If the terminal is big enough (at least 30 rows tall), it stays at the bottom of the screen and goes on with its day: it blinks and flicks an ear now and then, and every so often eats a stalk of grass. When you type / to open the menu it makes room, and it steps aside while a command runs. In a smaller terminal it freezes after about three seconds (press any key to skip), and after that only the bottom four lines of the screen change. If you don't want any animation, set CAPY_MOTION=never: it freezes right away and never moves again. Either way, everything above is the terminal's own scrollback: the commands you typed, their output and any errors stay there, and you can scroll back and copy them. In a pipeline or cron it still only prints the help; it never turns into a program waiting for a key press.
_
________________( )_____
.-' o `-.
.' . \
/ | ,-"
| ____.'--'
\ __.-'
`.| |`----------'| |'
|__| |__|
capy · spotify
> pl list
ID NAME TRACKS
p.b16G4rbSY0DzME City Pop Nights -
p.JL68l7EhogEeXd Winter Warmth -
------------------------------------------------------
▶ Yellow · 1:23 / 4:09 · MacBook Pro · volume 50
> _
space play/pause · ←→ ±10 s · / commands · ? keys · q quit
capy wiki setup)Like the web now-playing bar, the "what's playing" line follows whichever platform is actually playing (only a platform that is playing takes it over, a paused one doesn't; if the default platform isn't logged in or can't play on this computer, it shows the first one that can), the playback keys and the playback commands you type (pause, next, prev, seek, vol, a bare play, now) act on the platform it shows, and capy --provider X pins it to one platform.
> pl show Show a playlist's tracks (with no argument in a terminal, opens a picker)
pl sync One round of pull, then push: one table, one confirmation
------------------------------------------------------
▶ Yellow · 1:23 / 4:09 · MacBook Pro · volume 50
> /pl s_
↑↓ select · Tab/⏎ complete · Esc close
Press / to open the command menu: it filters as you type, and Tab or ⏎ puts the command on the input line so you can add arguments. Once you've typed a full command (for example /pl show Commute), the menu closes and ⏎ runs it; the leading / is dropped automatically. The menu grows upward, over the scrollback, and never gets mixed into your history. The list is generated from the command tree itself, not kept as a separate copy.
A command typed on that line runs capy itself again, not inside the same process. So every subcommand keeps its usual behavior: tables where there are tables, and a confirmation question wherever it would ask one. Put playlist names that contain spaces in double quotes, for example pl show "Road Trip".
When the playback state can't be read, the full error is printed into the scrollback and stays there, and the line at the bottom keeps only a short version; after five failures in a row polling stops, and r reconnects. The command line works no matter what: when capy can't connect is exactly when you need it most (doctor, auth login).
capy --web starts a web UI on this computer, bound to 127.0.0.1 only. At startup it prints a URL with a one-time token, and in a terminal it also opens your browser for you (in a pipeline or in the background it only prints the URL).
It opens on Move: move a playlist from one platform to another in three steps. Choose the source and the destination (you can see at a glance whether each platform is connected, and connect one on the spot) → pick a playlist and decide whether to create a new one or add to an existing one → review which songs will move; nothing is written until you confirm. Matching the songs shows real progress, and songs that can't be moved are listed one by one. It never deletes the source, only adds, and keeps the order; it's free and has no song limit, because it runs on your own computer with your own accounts.
The limits first: moving into the Local library can only add to an existing M3U file (Spotify, Apple Music and YouTube Music can create new playlists); whether songs moved into Apple Music are also added to your Apple Music library depends on your Apple Music settings, and they can only be moved into playlists you created yourself; songs moved into YouTube Music also only go into playlists you created, and since it has no ISRC they're matched by title, artist and duration only; connecting your accounts the first time takes a few minutes (Spotify needs your own app, for Apple you copy the token yourself, and for YouTube Music you copy the login cookie yourself), and in exchange nobody holds your credentials for you. M3U playlists on your disk can be moved to Spotify, Apple Music or YouTube Music too.
The other pages: My playlists, Sync, Search, Song wiki (the story behind the song that's playing, written in your language by your own AI endpoint; see Song wiki below) and Accounts; under Advanced are Console (type any subcommand, just like in the terminal), ISRC lookup (asks all three platforms at once) and Diagnostics. The now-playing bar is always at the bottom of every page: what's playing, progress and playback controls, everything capy now shows. It follows whichever platform is actually playing (only a platform that is playing takes it over, a paused one doesn't; if the default platform isn't logged in or can't play on this computer, it shows the first one that can), its controls act on the platform it shows, and capy --web --provider X pins it to one platform. Every action on the page is a capy command behind the scenes, and Console keeps the full record; anything that needs your confirmation is asked by the command itself, and the page never answers for you. The Language menu in the navigation switches the interface language: it runs capy config set language, the same setting the terminal uses (so the terminal switches too), and the page reloads once the change is saved.
My playlists shows the master copies kept in your Google Drive: pick one on the left, and its song table appears on the right (a fixed height, so a long playlist scrolls inside the table; you can also search within the playlist). Songs with a match on a platform can be played right away on Spotify or Apple Music (macOS; a song that is only in your library and not in the Apple Music catalog is marked “Library only” and can't be played from here) or opened on YouTube Music, and every song this computer has details for can be looked up with “Wiki”, which tells that song's story in a window on the same page. Above the table you can see which platform playlists this master copy is linked to: “Sync this playlist” carries additions, removals and order across; a platform that isn't linked yet offers “Create one on Spotify” or “Link to an existing playlist on Spotify” (a merge, see below; and likewise for the others), and songs without a match can be sorted out with “Find matches” or “Review one by one”. Further down, “Read each platform's playlists” lists your playlists on each platform you're logged in to on this computer (not the Local library; link an M3U from Console with pl link), marks the ones already linked to a master copy, and lets you “Add to capy” the ones capy doesn't keep yet. Syncing, finding matches, reviewing one by one, adding songs and pulling songs in all list the changes and ask you to confirm before anything is written, and the page never answers for you. Only two first steps don't ask separately: “Create one on Spotify” first explains what it will do, and pressing Start then creates an empty playlist on that platform and links it right away; pressing “Add to capy” creates an empty master copy in your Drive and links it right away.
Sync starts from a playlist on a service. At the top are three facts that always stay visible: the master copy lives in your Google Drive, you can start from any playlist, and names can differ only at the moment of linking. “Playlists being synced” lists the master copies on this computer that are linked to a service, each with a “Sync” button, plus “Sync all”; if a linked service isn't signed in on this computer, the page explains that first and then syncs one service at a time. Below that, pick a service (Spotify, Apple Music, YouTube Music or the Local library) and capy reads your playlists there; pick one to see its songs, and the page offers the next step for its state: a playlist capy doesn't keep yet can be added with “Add to capy”; one already linked to a master copy offers “Create one on Spotify”, “Link to an existing playlist on Spotify” or “Sync this playlist” (and likewise for the others); one with the same name as a master copy offers “Link to the master copy”. “Check for duplicates” only checks and changes nothing. On a second computer that has no copy of your master copies yet, press “Read master copies back”. “Advanced” at the bottom runs pull, push, sync and dedup by master copy name.
Linking to a playlist that's already there (a merge): capy first compares the songs on both sides and adds the songs that playlist has and the master copy doesn't to the end of the master copy in their current order (none of the master copy's songs move), then arranges that playlist like the master copy: adding songs, moving them, removing extra copies and renaming it to the master copy's name. These changes are listed in one table and confirmed once; if you cancel, nothing is written and nothing is linked. Songs it isn't sure about are offered to you to review one by one first. After that it finds matches for the newly added songs on the other services and syncs them there. In a terminal this is capy pl link --merge Commute apple:<playlist ID>, then capy resolve Commute and capy pl sync Commute.
The web UI stays on your computer: it binds to 127.0.0.1 only, so other devices on your network can't reach it; a one-time token is generated at every start, and the URL stops working when the process exits. Credentials never pass through the page: a secret you type into a wizard only goes from the browser into the process and then into the keychain, and token values in command echoes are always masked as ***.
It runs one command at a time (a second one is refused), because it shares the same Drive and local data as the terminal. While a command runs, a status line appears at the bottom: what it's doing, how long it has been running and the latest line it printed (while matching songs, which song it's on); the Stop button next to it stops it at any time (so does Ctrl-C on Console's command line). Once you've confirmed a write, Stop asks you to press it a second time, because stopping halfway may leave only part of the change written. A few commands aren't available on the web: the debug group, the three secret flags (use the wizard instead) and now --watch (the now-playing bar already shows it); capy update runs, but the web process is still the old version afterwards and asks you to restart it.
The terminal's interactive mode runs capy itself again, so each subcommand keeps its usual behavior; the web UI runs commands inside the same process, and the page answers their prompts. The two work differently because a terminal already has a TTY it can hand to a child process, and a browser doesn't.
Grouped by topic below. In a terminal, each command prints a table meant for people (cells wrap instead of being cut off when they don't fit, and IDs are always complete; when the table is wider than the terminal, a pager opens first: one row per line, ← → scroll sideways, ↑ ↓ up and down, g G jump to the top and bottom, q leaves, and Ctrl-C stops the whole command; after you leave, the table stays in the scrollback, wrapped. Commands run with --yes don't open the pager, and CAPY_PAGER=never turns it off entirely). In a pipeline the output is TSV, ready for cut and awk.
--provider apple or --provider youtube switches the platform, and --limit sets how many results you get.artist:, pl: or track:, the same as --type.1:05:30 for longer content, or plain seconds such as 83 in scripts.--watch keeps it updated, with a progress bar, and follows whichever platform is playing (--provider pins one).play --device.apple --create, youtube --create) and links it right away. Use it when you copy a playlist over from another platform, so you don't have to create it in the app first. If you already have a playlist of your own with that name on the platform, it stops and tells you how to link that one instead.capy pl dedup apple:Workout instead reads the platform playlist directly and only prints a report (it doesn't touch Drive and needs no link); to have capy remove the duplicates, link the playlist to a master copy and use the first form.Run these commands without a playlist name in a terminal and a picker opens: pl link asks three times (the platform → which playlist on that platform, where Spotify, Apple Music and YouTube Music also offer "create a new empty playlist" → which master copy to link it to, where you can also create a new one on the spot), and pl unlink asks twice. Behind a pipeline or in cron it doesn't ask, and you still have to give every argument.
none means the platform doesn't have this track.--refresh asks again, capy wiki title --artist artist asks about another song, and --json is for scripts. Every answer ends with a fixed reminder that it was generated by AI and may be wrong. In the web UI it's the Song wiki page (every song on My playlists that this computer has details for also has a “Wiki” button that asks about that song, with the title and artist taken from the playlist's master copy in your Drive); in interactive mode, press w.play --pick) and the playlist tracks remembered for sync, all cached on this computer.language): the interface is in English by default, capy config set language zh-TW switches it to Traditional Chinese, and en switches it back.The differences come from the platforms themselves, not from capy cutting corners. Where they differ, the command tells you directly instead of quietly skipping.
| Capability | Spotify | Apple Music | YouTube Music | Local library |
|---|---|---|---|---|
| Search | Yes | Yes | Yes | Matches within the library |
| Playback control | Connect | macOS only; songs not in your library only open in Music.app | Not supported | Not supported |
| Read playlists | Yes | Yes | Yes | M3U files |
| Write playlists | Yes | Only playlists you created | Only playlists you created | Yes |
| Create playlists | Yes | Yes | Yes | Create the file yourself |
| Credentials | Your own app | A token you copy from the web player | A login cookie you copy from the web player | Not needed |
One command does it. The example copies the Apple Music playlist "Roadtrip" to Spotify; you need to be logged in to the source platform, the target platform and Google first (YouTube Music works as a source or a target too).
$ capy migrate Roadtrip --from apple --to spotify # create a private playlist with the same name on Spotify and move the tracks over
$ capy migrate Roadtrip --from apple --to spotify:Driving # or add to an existing playlist, after the tracks it already has
$ capy migrate Roadtrip --from spotify --to apple # the other way: create a playlist with the same name on Apple Music and move the Spotify tracks over
$ capy migrate Roadtrip --from spotify --to youtube # to YouTube Music: creates a playlist with the same name there; no ISRC, so tracks are matched by title, artist and duration
$ capy migrate # no arguments: pick the source, the playlist and the target step by step
It lists what it will move first and does nothing until you confirm; when a new playlist is needed, that too is created only after you confirm. The target's existing order comes first, and the source's tracks follow in the source's order; tracks the target already has (the same track, or the same ISRC) are skipped. The source is never touched, and the target only gets additions: if the target has removals, reorders or renames that haven't been synced, it stops and asks you to run capy pl sync first. Tracks that weren't found on the target platform aren't pushed this time; in a terminal you can review them one by one on the spot, otherwise the last lines give you the commands to add them later. Afterwards only the target is linked to the master copy (the source isn't linked: it's a one-time copy); if you want to follow the source's changes later, the last lines give you the pl link --merge and pl sync commands, which link the master copy to the source (the source is arranged like the master copy; you see the table and confirm first); on the web it's “Link to an existing playlist” on the Sync page. The exception: if the master copy is already linked to the source (you were halfway through the manual steps below), the source side is pulled into the master copy too, the master copy wins, and the last lines say that both sides are linked. Whether tracks moved into Apple Music are also added to your Apple Music library depends on your Apple Music settings (that's Apple's behavior), and they can only be moved into playlists you created yourself.
What happens behind the scenes: capy links both platforms to the same master copy, then pushes. If you want the two sides to stay in sync, do it by hand once as shown below; after that, capy pl sync is all you need.
Link the Apple playlist first; the master copy is created automatically if it doesn't exist. Then use --create to create an empty private playlist with the same name on Spotify, linked to the same master copy.
$ capy pl link Roadtrip apple:Roadtrip
$ capy pl link Roadtrip spotify --create
Leave out --provider: on the Apple side the tracks are pulled into the master copy; the Spotify side is empty, so this device only records what it looked like. Without this step, the push later on is refused.
$ capy pl pull Roadtrip
Tracks with an ISRC are matched exactly; the rest are fuzzy-matched on title, artist and duration, and the ones that don't score high enough go into a queue for you to review.
$ capy resolve Roadtrip --provider spotify
$ capy resolve --review # only needed if the previous step listed a queue
The skip rows in the table are the tracks that can't be copied this time: tracks not yet matched on Spotify, usually ones you uploaded to Apple yourself or ones Spotify simply doesn't have.
$ capy pl push Roadtrip --provider spotify --dry-run
$ capy pl push Roadtrip --provider spotify
Nothing gets deleted along the way: this is the Spotify side's first pull, so everything pushed is an addition. Afterwards the two sides stay linked, and whenever either side changes, capy pl sync Roadtrip carries it across. If you only want a one-time copy, use capy migrate above, or run capy pl unlink Roadtrip apple when you're done. The other direction (Spotify to Apple) works the same way: capy migrate Roadtrip --from spotify --to apple, or swap the two platforms in the steps above (capy pl link Roadtrip apple --create).
Creating playlists and pushing tracks were implemented from Spotify's official documentation as of February 2026, but haven't been run against a real account yet. If you get a 404, or a playlist capy created shows up as public in the app, please report it.
M3U files on your disk can act as a platform too, with two-way sync with Spotify. They're tied to this computer: on another computer, capy skips this link instead of treating the playlist as deleted.
$ capy config set local_root ~/Music/playlists
$ capy pl link Commute local:Commute.m3u8
$ capy pl sync Commute
Track metadata lives in library.json in the same folder, and you maintain it yourself. Only tracks with an ISRC filled in can be matched automatically with the same track on a streaming platform; the others each stay a separate track. Writing back rewrites the whole file, so comments and #EXTINF lines that other tools wrote into the M3U are overwritten.
Not on our servers, because there are none. The SQLite database on this computer is only a cache: delete it and the next run rebuilds it completely from Drive.
Anything that would remove tracks from a playlist lists them first for you to confirm, and above a threshold it stops outright; only --force lets it through. --dry-run only shows, and changes nothing.
No path in capy sorts or shuffles a playlist: sync only follows a new order when the platform itself reordered the playlist, dedup only removes the later copy, and the tracks that weren't touched never change their relative order. The one exception is the table you confirm in capy pl link --merge: when you join a master copy to a playlist that already has songs, that playlist is arranged in the master copy's order; the master copy's own songs don't move, and no later sync reorders anything because of the merge.
That isn't a use Apple officially supports: the token expires, the method may stop working at any time, and you use it at your own risk. capy only guides you through copying it; it never reads your browser's cookies and never injects any script.
Adding tracks uses Apple's documented endpoint; removing, reordering and renaming use the endpoints Apple's own web player uses, which Apple has made no promises about, so they'll break if Apple changes them. Apple-curated playlists, Favorite Songs and Purchased Music can't be written: capy stops and writes nothing. capy doesn't write collaborative playlists at all for now (Apple returns a 500 error when their contents are replaced), and sync skips such a playlist and says why; copying it into a regular playlist first and linking that one usually works (not tested). Whether tracks added to a playlist are also added to your Apple Music library depends on your settings in Apple Music; that's Apple's behavior. Removing and reordering replace the whole track list: the playlist order always follows the master copy, and whether the Date Added shown in the Mac Music app gets reset hasn't been verified.
The Music app's scripting interface can only play tracks that are in your library. So when you play an Apple Music song (capy play, or the Search page of the web UI), capy first looks for it in the Music library on your computer, by title, artist and duration, and by album when that leaves more than one. If it finds exactly one, it plays it and checks that playback really started. Otherwise it opens the song in the Music app with the song highlighted, and you double-click it there (the Play button would resume whatever was playing before): the command still exits 0 but doesn't print ▶, and on the web UI's Search page the button for Apple Music songs says Open in Music.app. capy never adds songs to your library to get around this.
That isn't a use Google officially supports: what you paste is your Google account's YouTube login session (capy keeps only three session cookies, in the keychain), and anyone holding it can act as you on all of YouTube; automated access to YouTube is also against its Terms of Service, so you use it at your own risk. To revoke it, sign out of all devices in your Google Account → Security; Google may also invalidate it at any time, and then you just log in again. capy only guides you through copying it and never reads your browser. The YouTube Music account can be a different one from the account you use for Google Drive; capy auth status shows both. Playlist ids carry the account's channel id, so after logging in to another account the old account's links are skipped, not unlinked.
Liked Music, automatic playlists and playlists saved from other channels are read-only. One round of changes is one request: when the changes only add tracks they're appended, otherwise the whole playlist is replaced (every row removed, then added back in the master copy's order; a rename rides in the same request), verified up to YouTube's 5,000-track cap; the request is atomic, so a rejected change leaves the playlist untouched, but a replace resets "date added". YouTube Music has no ISRC, so cross-platform matching relies on title, artist and duration only; the audio version and the music video of the same song are two ids, and only a manual decision (capy resolve --review or capy resolve pin) can merge them. capy doesn't play YouTube Music for you (on the web Search page that row only has an Open on YouTube Music link), and it never deletes a YouTube Music playlist.
When it isn't in a terminal, output is always plain-text TSV, with no colors and no interactive prompts. Exit codes mean something: 0 success, 1 error, 2 needs you, 3 stopped by a safety check. In the TSV of pl pull / push / sync, migrate, dedup and resolve, the reason column is for people and follows the interface language; scripts should read the last column, reason_code, which is the same in every language.