@freeyourmusic/cli

Local command-line interface for Free Your Music. Talks to a running Free Your Music desktop app over loopback HTTP — no separate auth required.

Requires Free Your Music desktop to be running. The CLI is a thin client; the desktop process owns music-service authentication, license checks, and importer execution.

Quickstart

npm i -g @freeyourmusic/cli
# Make sure the Free Your Music desktop app is open and signed in.
fym status

Expected output (free tier, no signed-in license):

✓ Desktop running (vXX.X.X, pid 12345)
  License: free (no account)
✓ Connected: (none)
  Search quota: 0 / 100

Commands

Run fym --help for the full list. Every command takes --json.

| Group | Commands | Tier | |---|---|---| | Desktop | status, services, accounts [--service=<id>], login <service>, logout <service> | free | | Read | playlists list, playlists get <id>, tracks list, library tracks\|albums\|artists, history recent | free | | Search | search tracks\|albums\|artists "<query>" | free, 100 searches a day | | Write | playlists create\|rename\|delete, tracks add\|remove\|reorder, library like\|unlike, follow artist, unfollow artist | Pro |

Most commands need --service=<id>. When a service has two or more connected accounts, add --account=<id-or-label>.

On a desktop app that runs the server data path (Realm exit), the read, search and write commands answer UNSUPPORTED_OPERATION; status, services and accounts still work.

Exit codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | User error (bad args, missing param) | | 2 | Auth (service not connected) | | 3 | Desktop not running | | 4 | License gate (Pro required) | | 5 | Search quota exceeded |

How it works

The Free Your Music desktop app runs a loopback HTTP server on a random port. On startup it writes ~/.fym/cli-config.json ({ port, token, version, pid }, mode 0600). The CLI reads that file, then makes JSON-RPC calls over HTTP. All importer work, license enforcement, and quota tracking run inside the desktop process — the CLI is just a thin transport.

Privacy

No telemetry is added by the CLI. All traffic is 127.0.0.1 only. Bearer token is rotated on every desktop launch and never leaves the machine.

Error reporting

Published builds report unexpected failures to FreeYourMusic's Sentry project. Tool arguments, bridge credentials, request payloads and Redux state are not attached. Development/test builds do not report. Set FYM_DISABLE_TELEMETRY=1 to disable reporting, or SENTRY_DSN to use your own destination. MCP protocol output remains on stdout; diagnostic output uses stderr.

Maintainers

The version is copied from renderer/package.json at publish time. The master-desktop pipeline publishes it (gitlab-ci/.publish.yml, ci/fym-cli/publish.sh, npm Trusted Publishing, no --provenance). No CI job runs this package's tsc-lint, lint or test; run them yourself with pnpm --filter @freeyourmusic/cli <script>.