CLI tool
bjarneo/cliamp avatar
bjarneo/cliamp

cliamp: a terminal music player that treats your servers as sources

cliamp - Terminal music player inspired by winamp

4,631 stars344 forksGoMIT

At a glance

What is it?
cliamp is a Go terminal music player built on Bubbletea that plays local files, radio, podcasts and self-hosted music servers from one interface. The interesting part is the daemon, the wizard and the codec dependency split across macOS and Linux.
Who is it for?
Adopt cliamp if your listening already lives on a self-hosted server or in a directory and you want to drive it from the keyboard, including from a status bar or a script reading cliamp status --json. Skip it if reconciling ffmpeg, yt-dlp and four Homebrew codec libraries is not a day you want to spend, and use cliamp mobile instead if you want phone playback.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • bjarneo/cliamp4,631 ★ · +321
Star history
Repository2026-09-232026-11-15
bjarneo/cliamp4.3k4.6k

321 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

One binary for a directory, a stream and eighteen remote services

cliamp answers to three different arguments: a directory, a list of files, or a URL. That is the whole entry surface. Everything beyond it is a source the same player opens. Alongside local files, the source list covers about 58,000 Radio Browser stations, podcasts, YouTube and YouTube Music, SoundCloud, Mixcloud, Bilibili, Spotify, Qobuz, Tidal, NetEase Cloud Music, Yandex Music, Xiaoyuzhou, and the self-hosted servers Navidrome, Lyrion, Plex, Jellyfin, Emby and Audiobookshelf. That breadth is the pitch, but it is also the source of nearly every rough edge in the project, because the sources do not share an authentication model. Self-hosted servers want a URL and a key. Spotify, Qobuz and Tidal sign in with OAuth later, inside the player. Podcasts want neither. The audience is a person who already has a server or a folder and wants one keyboard-driven surface across all of it, rather than a browser tab per service.

Bubbletea in the foreground, the same player in the background

The interface is a Bubbletea program styled with Lip Gloss, and the audio comes from Beep, with go-librespot handling Spotify. Underneath sit provider/, ipc/, playlist/, player/, pluginmgr/, luaplugin/ and mediactl/ packages, which tells you where the boundaries are. The part that changes how you use it is the daemon. Run cliamp with the --daemon flag and there is no TUI, but the same player keeps running: it loads your Lua plugins, reports plays to Navidrome, Jellyfin and the other providers that accept play reports, and writes every track into Recently Played as it starts. A running player is then controlled from another shell or from a key binding:

bash
cliamp toggle
cliamp next
cliamp status --json

The status flag is machine readable, so a status bar can parse it. Media keys work through MPRIS on Linux, Now Playing on macOS, and global hotkeys on Windows.

Six install paths, and the codec cost lands on macOS

The shortest path pipes a remote script into a shell:

bash
curl -fsSL https://cliamp.stream/install.sh | sh

Homebrew installs the runtime libraries with the formula, which is the difference that matters later:

bash
brew install bjarneo/cliamp/cliamp

Arch and Nix users have yay -S cliamp and nix run github:bjarneo/cliamp, and go install github.com/bjarneo/cliamp@latest builds from source with Go 1.26.10 or later. Prebuilt binaries come from GitHub Releases, or from source with:

bash
git clone https://github.com/bjarneo/cliamp.git && cd cliamp && go build -o cliamp .

Two optional-looking dependencies do real work. ffmpeg handles AAC, ALAC, Opus and WMA. yt-dlp handles YouTube, YouTube Music, SoundCloud, Mixcloud, Bandcamp, Bilibili and NetEase Cloud Music. Strip either one and a slice of the advertised sources simply stops resolving, which is the first contradiction worth noticing: they sit under the heading for optional runtime dependencies, yet seven of the listed sources need yt-dlp.

The setup wizard edits config.toml in place

Remote providers are configured through an interactive wizard rather than hand-written keys:

bash
cliamp setup

It writes each provider's keys into that provider's section of ~/.config/cliamp/config.toml, and on Windows with HOME unset it uses %APPDATA%\cliamp\config.toml. The behaviour that makes it usable more than once is that it keeps your other keys and comments, and it validates supported server connections as it goes. Spotify, Qobuz and Tidal deliberately do not get credentials at this stage; they sign in later inside the player. Mixcloud checks optional browser-session or OAuth credentials only when you use them. So setup is not a one-shot configuration dump, it is a partial one, and a reader who finishes the wizard expecting every source to be live will find two or three still waiting. Custom radio stations live in a separate file, ~/.config/cliamp/radios.toml, with the same Windows fallback.

Radio location is read from the system timezone, not geo-IP

Press R in the player to open the Radio Browser directory, about 58,000 stations. N browses by country, the genre and tag index loads the directory's complete tag list, and the slash key filters either list. Letter f pins the countries you listen to, and Enter on a country or tag loads its stations as a playlist. The design choice here is that cliamp refuses to guess where you are unless you pick Use my location and accept. After that it reads your country from the system timezone, and never from a geo-IP service. Hosting a station yourself is a different repository, cliamp-server.

macOS binaries fail on a missing libvorbisenc.2.dylib

The clearest documented failure mode is a macOS dynamic link error. Prebuilt binaries and install.sh link dynamically to FLAC, Vorbis, Ogg and mpg123 from Homebrew, so a fresh machine without those libraries produces an error such as Library not loaded: /opt/homebrew/opt/libvorbis/lib/libvorbisenc.2.dylib. The remedy is to install the four libraries, or to use the Homebrew formula, which pulls them in. Linux Release binaries link those same codecs statically and need no codec packages, though an ALSA bridge for your sound server can still be required. Windows is the odd one out: the zip includes the codec DLLs that Spotify requires, and cliamp stores its config under %APPDATA%\cliamp when HOME is not set. Build from source on Linux and the ALSA development headers become a hard prerequisite.

Where the terminal player and cliamp mobile diverge

The documented alternative is not a competing player but a separate client from the same project. cliamp mobile is a native Android client for radio, podcasts and the same servers this player talks to, so the difference in approach is the whole stack below the interface: a terminal program drawing with Bubbletea against Beep, versus a phone app. Where that changes decisions is playback context. On a desktop, MPRIS, Now Playing and Windows global hotkeys do the work of media keys, and cliamp status --json gives a script the same reach. The second boundary is the toolchain. The desktop path can need ffmpeg, yt-dlp, and on macOS four Homebrew codec libraries.

Editorial conclusion

Adopt cliamp if your listening already lives on a self-hosted server or in a directory and you want to drive it from the keyboard, including from a status bar or a script reading cliamp status --json. Skip it if reconciling ffmpeg, yt-dlp and four Homebrew codec libraries is not a day you want to spend, and use cliamp mobile instead if you want phone playback. Verify first that the providers you actually use have credentials written into config.toml by cliamp setup: podcasts need no account or API key, and Spotify, Qobuz and Tidal still sign in later inside the player.

Frequently asked questions

How to use CLIAMP?

Pass a directory, a list of files, or a stream URL to the cliamp binary and the player opens in the terminal. Press Ctrl+K inside the player to see all keybindings, and run cliamp setup to configure remote providers through the wizard.

What is CLIAMP on Linux?

cliamp is a terminal music player written in Go that plays local files and remote servers from the terminal. On Linux the Release binaries link FLAC, Vorbis, Ogg and mpg123 statically, and an ALSA bridge for your sound server can still be needed.

How do I connect cliamp to Spotify?

Spotify is one of the providers the setup wizard covers, but it is an OAuth provider and does not take keys during setup. It signs in later, inside the player.

What is cliamp?

cliamp is a retro terminal music player inspired by Winamp, built with Bubbletea, Lip Gloss, Beep and go-librespot. It plays local files, streams, podcasts, radio and named remote services, and is distributed under the MIT licence.

Official sources

  1. bjarneo/cliamp on GitHub
  2. License: MIT
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/bjarneo-cliamp.svg)](https://hysenlabs.com/projects/bjarneo-cliamp)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/bjarneo-cliamp.svg)](https://hysenlabs.com/projects/bjarneo-cliamp)

Was this useful?