On this page6 sections ▾
The FreeYourMusic CLI lets you work with your music services from a terminal: list playlists, search, and, with Premium, create and edit playlists. It talks to the FreeYourMusic desktop app on your computer, so the desktop app must be open.
What you need
- The FreeYourMusic desktop app on macOS, Windows or Linux, open and with your music services connected. Download it here.
- Node.js with npm, to install the CLI.
Install the CLI
Install and check the FreeYourMusic CLI
- Open the FreeYourMusic desktop app.
- In a terminal, run npm i -g @freeyourmusic/cli.
- Run fym status. It shows that the desktop app is running, your licence, the connected services and your search quota.
- Run fym --help to see every command.
What can I do with it?
| Group | Commands | Plan |
|---|---|---|
| Desktop | status, services, accounts, login, logout | Free |
| Read | playlists list, playlists get, tracks list, library tracks, library albums, library artists, history recent | Free |
| Search | search tracks, search albums, search artists | Free: 100 searches a day. Premium: unlimited |
| Write | playlists create, rename and delete; tracks add, remove and reorder; library like and unlike; follow and unfollow artist | Premium |
Most commands need --service=<id>, for example fym playlists list --service=spotify. Run fym services to see the IDs. If you connected two or more accounts of one service, add --account=<id-or-label>.
Add --json to any command to get output that scripts and other tools can read.
The free search quota resets every day at midnight UTC. See the CLI page for more examples and the pricing page for Premium.
Exit codes
| Code | Meaning | What to do |
|---|---|---|
| 0 | Success | Nothing. |
| 1 | A wrong or missing argument | Check the command with fym --help. |
| 2 | The service is not connected | Connect the service in the desktop app, or run fym login. |
| 3 | The desktop app is not running | Open the FreeYourMusic desktop app. |
| 4 | The command needs Premium | Upgrade to Premium, or use a free command. |
| 5 | The daily search quota is used up | Wait for the reset at midnight UTC, or upgrade to Premium. |
How it works and what stays private
When the desktop app starts, it opens a small local connection on your computer and writes its address and a key to ~/.fym/cli-config.json. Only your user account can read that file. The CLI reads it and sends its requests to the desktop app over 127.0.0.1, so they never leave your computer.
The key changes every time the desktop app starts. The desktop app does all the work: it signs in to your services, checks your licence and counts your searches.
The CLI adds no tracking. Published versions report unexpected errors to our crash-reporting tool, without your command arguments or credentials. Set FYM_DISABLE_TELEMETRY=1 to turn that off.
Frequently asked questions
Does the CLI work without the desktop app?
No. The CLI is a thin client of the desktop app. Open FreeYourMusic on your computer first, or the CLI exits with code 3.
Is the CLI free?
Yes for reading your libraries and for up to 100 searches a day. Creating and editing playlists, editing your library and unlimited search need Premium.
A command answers UNSUPPORTED_OPERATION. Why?
That command is not available for your account yet. The status, services and accounts commands always work.
Should I use the CLI or the MCP server?
Use the CLI for scripts and automation. Use the MCP server when you want to ask an AI assistant to work with your music in a chat.
Need help with the CLI? Contact support and paste the output of fym status.