How to Install cliamp on Ubuntu: A Retro Terminal Music Player Inspired by Winamp

cliamp is what you get when someone rebuilds Winamp 2.x for the terminal. It is a Go music player with a spectrum visualizer, a 10-band equaliser, a playlist editor and a generous set of colour themes. Beyond local files and internet radio it streams from Spotify, Qobuz, Tidal, Navidrome, Jellyfin, Plex, YouTube Music and more, and it can drop the UI entirely to run as a daemon that scripts and status bars control.

cliamp is not available from the Ubuntu archive. Getting it normally means piping an install script into your shell, grabbing a release binary by hand, or compiling it with Go and a handful of codec headers, and every one of those leaves future updates to you.

The unofficial deb.griffo.io repository offers a cleaner path: cliamp packaged as a proper Ubuntu .deb and delivered over APT, so you install it and keep it current with the same commands you already use.

Install the Latest cliamp on Ubuntu: The Short Version

If you only came for the commands, this adds the repository and installs the latest cliamp .deb package on Ubuntu:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null
sudo apt update
sudo apt install cliamp

The rest of this guide explains what each command does, how to verify the install, how to keep cliamp up to date, and what to check when something goes wrong.

What Makes cliamp Special?

📼 Classic Winamp feel - A retro terminal interface with playlist, seek bar, volume, shuffle and repeat right where you expect them.
🎚️ Graphic equaliser - Ten bands with presets like Rock, Jazz and Bass Boost, and a Custom curve that is saved between sessions.
🌈 A wall of visualizers - Bars, Wave, Scope, Flame, Matrix, Sakura and plenty more, with a full-screen option.
🎨 Built-in and custom themes - 22 bundled themes, winamp, nord and catppuccin among them, plus your own TOML files.
📻 Internet radio - Browse the Radio Browser directory by country or genre, or define your own stations.
☁️ Streaming services - Spotify, Qobuz, Tidal, Navidrome, Jellyfin, Emby, Plex, Audiobookshelf, SoundCloud, Mixcloud, NetEase and YouTube Music.
🎙️ Podcasts - Find, search and subscribe to shows with no account or API key required.
🤖 Daemon mode with IPC - Go headless and control playback from Waybar, Polybar, keybindings, cron jobs or over SSH.
🔌 Lua plugins - Isolated plugins add scrobbling, notifications, status-bar output and new visualizers.

Why Use the deb.griffo.io Repository?

Easy installation and updates through APT rather than a shell installer.
Automatic dependency management provided by the Ubuntu packaging, ALSA library included.
Always tracks upstream releases so you stay near the latest cliamp.
No compiling from source, and no Go toolchain or audio development headers to look after.
Integrates with your desktop - a man page, a desktop entry with icon, and bash and zsh completions come in the package.
Works across supported Ubuntu releases, with the codename detected for you.

Prerequisites

Before starting, confirm you have:

An Ubuntu system (Jammy 22.04 LTS, Noble 24.04 LTS, Questing 25.10, or Resolute 26.04 LTS) on amd64 or arm64
sudo privileges
curl installed (sudo apt install curl if needed)

cliamp recommends ffmpeg for AAC, ALAC, Opus and WMA files, and suggests yt-dlp for YouTube, YouTube Music, SoundCloud, Mixcloud, Bandcamp and Bilibili playback.

Step 1: Add the deb.griffo.io Repository

# Create the keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install the repository GPG key
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

# Add the repository (auto-detects your distro codename)
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null

# Update the package list
sudo apt update

Breaking it down:

Create the keyrings directory - makes sure /etc/apt/keyrings exists with the right permissions.
Install the GPG key - downloads and de-armours the repository key into its own keyring so APT can verify signatures.
Add the repository - writes a signed-by source line, letting lsb_release -sc fill in your Ubuntu codename.
Update the package list - refreshes APT’s view of available packages.

Step 2: Update the Package List

If you did not run the final command above, do it now:

sudo apt update

Step 3: Install cliamp

Install with APT:

sudo apt install cliamp

Ubuntu installs recommended packages by default, so ffmpeg comes along automatically. Suggested packages do not, which means yt-dlp needs its own install if you want online sources:

sudo apt install yt-dlp

Because the repository is already enabled, APT hands you the up-to-date yt-dlp from deb.griffo.io instead of the older Ubuntu archive build. The yt-dlp on Ubuntu guide explains why that matters.

Step 4: Verify the Installation

The binary is cliamp. Check the version:

cliamp --version

You should see something like:

cliamp version v2.2.0

Run cliamp --help for the complete flag and subcommand listing, or man cliamp for the packaged manual page.

Getting Started with cliamp

Your First Playlist

Hand cliamp a folder, some files or a stream address:

# Play everything in a folder
cliamp ~/Music

# Play a selection of files
cliamp *.mp3 *.flac

# Tune in to a radio stream
cliamp https://example.com/stream

Inside the player, ? or Ctrl+K brings up the full keymap. These are the ones you will reach for most:

Key	Action
`Space`	Play / pause
`>` `<`	Next / previous track
`Left` `Right`	Seek 5 seconds
`+` `-`	Volume up / down
`z` / `r`	Toggle shuffle / cycle repeat
`e`	Cycle EQ presets
`v` / `V`	Cycle visualizers / full-screen visualizer
`t`	Choose a theme
`/`	Search the playlist
`q`	Quit

One-Off Playback Options

Command-line flags change behaviour for the current session without touching your config:

# Start a shuffled folder straight away
cliamp --shuffle --auto-play ~/Music

# Loop the whole list through an EQ preset
cliamp --repeat all --eq-preset "Bass Boost" ~/Music

# Lighter on CPU for SSH sessions or laptops on battery
cliamp --low-power ~/Music

Radio, Podcasts and Your Accounts

R opens the radio browser, where you can narrow stations down by country or genre. Podcasts have their own provider:

cliamp --provider podcast

Account-based services such as Navidrome, Jellyfin, Plex, Spotify, Qobuz, Tidal and YouTube Music are configured through a small wizard that adds the right section to ~/.config/cliamp/config.toml without disturbing anything else:

cliamp setup

Online Sources with yt-dlp

Once yt-dlp is present, cliamp plays and searches web sources as easily as local files:

# Play a YouTube or SoundCloud link
cliamp https://www.youtube.com/watch?v=dQw4w9WgXcQ
cliamp https://soundcloud.com/artist/track

# Search from the shell and play the top hit
cliamp search "never gonna give you up"
cliamp search-sc "lofi beats"

In the TUI, Ctrl+F searches the provider you currently have open.

Managing Playlists from the Shell

Local playlists are plain TOML files, and the playlist subcommand edits them without launching the interface:

# Build a playlist from a folder and look at it
cliamp playlist create "Road Trip" ~/Music/Albums
cliamp playlist list
cliamp playlist show "Road Trip"

# Open it and start playing
cliamp --playlist "Road Trip" --auto-play

Running cliamp as a Background Daemon

Headless mode keeps the music going with no terminal UI, while every other shell, hotkey or status bar can steer it:

# Launch the daemon on a playlist
cliamp --daemon --auto-play --playlist "Road Trip"

# Control it from any terminal
cliamp toggle
cliamp next
cliamp volume -3
cliamp status --json

Feed cliamp status --json to a Waybar or Polybar module, and bind your media keys to cliamp toggle, cliamp next and cliamp prev.

Configuration, Themes and Plugins

Persistent settings live in ~/.config/cliamp/config.toml. For example, to start with the winamp theme, a Rock EQ and the classic bars:

theme = "winamp"
eq_preset = "Rock"
visualizer = "Bars"

Many choices you make interactively, like the theme selected with t, are saved automatically. Custom themes belong in ~/.config/cliamp/themes/ and Lua plugins in ~/.config/cliamp/plugins/, managed with cliamp plugins:

cliamp plugins list
cliamp plugins install bjarneo/cliamp-plugin-lastfm

Before a plugin runs, cliamp shows you where it came from, its SHA-256 and the permissions it asks for, and it stays disabled until you approve it.

Keeping cliamp Updated

cliamp rides along with your normal Ubuntu upgrades:

sudo apt update && sudo apt upgrade

When a newer cliamp appears in deb.griffo.io, apt upgrade installs it alongside your other packages. Since it is managed by APT, use apt rather than the built-in cliamp upgrade, which is designed for standalone binary installs.

Other Tools from deb.griffo.io

The repository includes many tools that sit well next to cliamp:

yt-dlp - the downloader behind cliamp’s YouTube, SoundCloud and Mixcloud support.
Termusic - a feature-rich terminal music player written in Rust.
lowfi - a minimal lofi player for focus music in the background.
Ghostty - a fast, GPU-accelerated terminal emulator that keeps visualizers smooth.

Troubleshooting

GPG or Key Errors

If APT flags the repository as unsigned or the key as invalid, re-import it:

curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Package Not Found

If APT cannot locate cliamp:

Re-run sudo apt update after adding the repository.
Verify your Ubuntu release is supported (Jammy, Noble, Questing, or Resolute).
Check your architecture with dpkg --print-architecture; only amd64 and arm64 builds exist.
Check the source list: cat /etc/apt/sources.list.d/deb.griffo.io.list.

No Sound and an “audio output unavailable” Message

cliamp outputs through ALSA, which needs a bridge package to reach PipeWire or PulseAudio:

# PipeWire (default on Ubuntu 22.10 and later)
sudo apt install pipewire-alsa

# PulseAudio (Jammy 22.04, WSL2)
sudo apt install libasound2-plugins

Certain Files or Websites Refuse to Play

cliamp hands AAC, ALAC, Opus and WMA decoding to ffmpeg, and YouTube, SoundCloud, Mixcloud and Bandcamp to yt-dlp. Install whichever is missing:

sudo apt install ffmpeg yt-dlp

A YouTube link that worked last week and fails today almost always means yt-dlp needs an update; the yt-dlp on Ubuntu guide has the details.

No Tab Completion in fish

The package intentionally ships completions for bash and zsh only. The fish script upstream generates is currently malformed, so including it would break fish sessions rather than help them.

An Older Install Shadows the Package

If you installed cliamp before with the install script or make install, a binary in ~/.local/bin can override the packaged one:

which -a cliamp

Delete the stray binary or reorder your PATH so /usr/bin/cliamp wins.

Uninstalling

Remove cliamp with:

sudo apt remove cliamp

To also remove the repository and key:

sudo rm /etc/apt/sources.list.d/deb.griffo.io.list
sudo rm /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Removing the package leaves ~/.config/cliamp/ untouched, so delete it too if you want your playlists and settings gone.

Conclusion

On Ubuntu, deb.griffo.io turns cliamp into a first-class APT package: no installer script, no Go build, no manual updates. What you get is a Winamp-flavoured player that has grown into a hub for local music, radio, podcasts and streaming services, with a daemon mode and plugins for when you want to wire it into the rest of your desktop.

Install cliamp and yt-dlp, choose a theme and visualizer that make you smile, and let apt upgrade take care of the rest.

Frequently Asked Questions

How do I install the latest cliamp on Ubuntu?

Add the deb.griffo.io APT repository and its signing key, then run sudo apt install cliamp. The repository tracks upstream cliamp releases, so you get the latest packaged version rather than a build frozen when your distribution was released.

Is there a `.deb` package for cliamp?

Yes. deb.griffo.io publishes cliamp as a signed .deb for Ubuntu. You could download that .deb and install it by hand, but adding the repository is the better option: APT then resolves dependencies and picks up new versions on its own.

How do I update cliamp to the latest version?

Run sudo apt update && sudo apt upgrade. Leave cliamp upgrade alone; it is meant for self-managed binaries, not packaged installs.

Do I need ffmpeg and yt-dlp?

MP3, FLAC, OGG and WAV files, and most radio streams, play without either. ffmpeg adds AAC, ALAC, Opus and WMA, while yt-dlp unlocks YouTube, YouTube Music, SoundCloud, Mixcloud, Bandcamp and Bilibili. sudo apt install ffmpeg yt-dlp covers both.

How do I install cliamp on Debian?

Exactly the same way; lsb_release -sc simply resolves to a different codename. There is a companion guide with the Debian specifics: How to install cliamp on Debian.

Which Ubuntu releases are supported?

Jammy 22.04 LTS, Noble 24.04 LTS, Questing 25.10 and Resolute 26.04 LTS, on amd64 and arm64. Because the repository line is built from lsb_release -sc, the matching suite is selected for you.

Resources

Disclaimer: The deb.griffo.io repository is an unofficial community project and is not affiliated with the official Debian or Ubuntu projects, or with the upstream cliamp project. Streaming and downloading content may be subject to the terms of service of the platforms you use.