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

cliamp is a terminal music player that borrows its look and feel from Winamp 2.x: a spectrum visualizer, a 10-band equaliser, a playlist editor and a stack of themes, all rendered in your terminal. Written in Go, it plays local files and internet radio, streams from services such as Spotify, Qobuz, Tidal, Navidrome, Jellyfin, Plex and YouTube Music, and can run as a headless daemon you control from scripts and status bars.

cliamp is not part of the official Debian archive. The usual routes are a piped install script, a hand-downloaded release binary, or building it with Go and a pile of audio development headers, and all of them leave you to track new releases yourself.

The unofficial deb.griffo.io repository takes care of that: it packages cliamp as a standard Debian .deb served over APT, so installation and updates use the tooling you already run for the rest of your system.

Install the Latest cliamp on Debian: The Short Version

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

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?

📼 Winamp nostalgia, in a terminal - A retro interface with a playlist, seek bar, volume, shuffle and repeat controls.
🎚️ 10-band equaliser - Built-in presets such as Rock, Jazz and Bass Boost, plus your own saved Custom curve.
🌈 Dozens of visualizers - Bars, Wave, Scope, Flame, Matrix, Sakura and many more, including a full-screen mode.
🎨 Themes - 22 built-in colour themes, from winamp and dracula to catppuccin and gruvbox, plus custom TOML themes.
📻 Internet radio - Browse tens of thousands of stations from the Radio Browser directory, or add your own.
☁️ Streaming providers - Spotify, Qobuz, Tidal, Navidrome, Jellyfin, Emby, Plex, Audiobookshelf, SoundCloud, Mixcloud, NetEase and YouTube Music.
🎙️ Podcasts - Discover, search and subscribe to shows without an account or API key.
🤖 Headless daemon and IPC - Run without a UI and drive playback from Waybar, Polybar, hotkeys, cron or SSH.
🔌 Lua plugins - Sandboxed plugins for scrobbling, notifications, status-bar output and extra visualizers.

Why Use the deb.griffo.io Repository?

Easy installation and updates through APT, no curl-to-shell installer.
Automatic dependency management handled by Debian packaging, including the ALSA library cliamp links against.
Always tracks upstream releases so you stay close to the latest cliamp.
No compiling from source, no Go toolchain and no codec development headers to install.
Desktop integration included - the package ships a man page, a desktop entry with the application icon, and bash and zsh completions.
Works across supported Debian releases, with the codename detected automatically.

Prerequisites

Before you start, make sure you have:

A Debian-based system (Bookworm 12, Trixie 13, Forky 14, or Sid) on amd64 or arm64
sudo privileges
curl installed (sudo apt install curl if needed)

The package recommends ffmpeg, which cliamp uses for AAC, ALAC, Opus and WMA playback, and suggests yt-dlp, which it needs for YouTube, YouTube Music, SoundCloud, Mixcloud, Bandcamp and Bilibili.

Step 1: Add the deb.griffo.io Repository

Add the signing key and repository source:

# 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

What each command does:

Create the keyrings directory - ensures /etc/apt/keyrings exists with proper permissions.
Install the GPG key - downloads the repository key and de-armours it into a dedicated keyring for verification.
Add the repository - writes a signed-by source line, with lsb_release -sc supplying your Debian codename.
Update the package list - refreshes APT so it knows about the new packages.

Step 2: Update the Package List

If you skipped the last line, run the update now:

sudo apt update

Step 3: Install cliamp

Install cliamp with APT:

sudo apt install cliamp

APT installs cliamp together with ffmpeg, since recommended packages are installed by default. Suggested packages are not, so if you want YouTube and SoundCloud playback add yt-dlp as well:

sudo apt install yt-dlp

With the repository enabled you get the current yt-dlp from deb.griffo.io rather than an older archive build, which matters for a tool that breaks whenever sites change. The yt-dlp on Debian guide covers it in detail.

Step 4: Verify the Installation

The binary is simply cliamp. Confirm the version:

cliamp --version

You should see output similar to:

cliamp version v2.2.0

cliamp --help lists every flag and subcommand, and man cliamp opens the manual page shipped with the package.

Getting Started with cliamp

Playing Your Music

Point cliamp at a directory, a set of files, or a stream URL:

# Play a whole directory
cliamp ~/Music

# Play specific files
cliamp *.mp3 *.flac

# Play an internet radio stream
cliamp https://example.com/stream

Once the player is open, press ? or Ctrl+K to see every keybinding. The essentials:

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

Tweaking Playback from the Command Line

Flags override your config for a single session:

# Shuffle a directory and start playing immediately
cliamp --shuffle --auto-play ~/Music

# Repeat everything with a preset EQ curve
cliamp --repeat all --eq-preset "Bass Boost" ~/Music

# Keep CPU usage down over SSH or on battery
cliamp --low-power ~/Music

Radio, Podcasts and Streaming Services

Press R inside the player to browse the Radio Browser directory by country or genre. For podcasts, start with the podcast provider:

cliamp --provider podcast

To connect Navidrome, Jellyfin, Plex, Spotify, Qobuz, Tidal, YouTube Music and the other account-based providers, run the interactive wizard. It writes the right block to ~/.config/cliamp/config.toml and leaves the rest of the file alone:

cliamp setup

YouTube and SoundCloud via yt-dlp

With yt-dlp installed, cliamp can play and search online sources directly:

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

# Search from the command line and play the result
cliamp search "never gonna give you up"
cliamp search-sc "lofi beats"

Inside the player, Ctrl+F searches whichever provider is active.

Local Playlists

cliamp keeps playlists as TOML files and can manage them without opening the TUI:

# Create a playlist from a directory and inspect it
cliamp playlist create "Road Trip" ~/Music/Albums
cliamp playlist list
cliamp playlist show "Road Trip"

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

Headless Mode and Remote Control

Run cliamp without a UI and control it from any other terminal, a keybinding or a status bar:

# Start the daemon and play a playlist
cliamp --daemon --auto-play --playlist "Road Trip"

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

cliamp status --json is what you wire into Waybar or Polybar, and cliamp toggle, cliamp next and cliamp prev map neatly onto media keys.

Themes, Config and Plugins

cliamp reads its settings from ~/.config/cliamp/config.toml. Set a default theme, EQ preset and visualizer there:

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

Most choices you make in the player, such as the theme picked with t, are remembered for you anyway.

Custom themes go in ~/.config/cliamp/themes/ and Lua plugins in ~/.config/cliamp/plugins/. Plugins are managed with cliamp plugins:

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

cliamp shows each plugin’s source, hash and permissions before you approve it, and will not run a plugin whose contents you have not trusted.

Keeping cliamp Updated

Because cliamp arrived via APT, updates come with the rest of the system:

sudo apt update && sudo apt upgrade

Whenever deb.griffo.io ships a newer cliamp, apt upgrade installs it automatically. Skip the built-in cliamp upgrade here: it is meant for self-managed binary installs, not for a file the package manager owns.

Other Tools from deb.griffo.io

The repository packages plenty of tools that fit naturally alongside cliamp:

yt-dlp - the downloader cliamp relies on for YouTube, SoundCloud and friends.
Termusic - another feature-rich terminal music player, written in Rust.
lowfi - an extremely simple lofi player for background focus music.
Ghostty - a fast, GPU-accelerated terminal that does those visualizers justice.

Troubleshooting

GPG or Key Errors

If APT reports an unsigned repository or an invalid key, import it again:

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 see the cliamp package:

Re-run sudo apt update after adding the repository.
Confirm your release is supported (Bookworm, Trixie, Forky, or Sid).
Confirm your architecture is amd64 or arm64 (dpkg --print-architecture); upstream publishes no other builds.
Inspect the source list: cat /etc/apt/sources.list.d/deb.griffo.io.list.

”audio output unavailable”

cliamp talks to ALSA. On desktops running PipeWire or PulseAudio, ALSA needs a bridge to reach the sound server:

# PipeWire (the default on Trixie and newer)
sudo apt install pipewire-alsa

# PulseAudio
sudo apt install libasound2-plugins

Some Formats or Online Sources Will Not Play

AAC, ALAC, Opus and WMA go through ffmpeg, and YouTube, SoundCloud, Mixcloud and Bandcamp go through yt-dlp. Make sure both are installed:

sudo apt install ffmpeg yt-dlp

If a YouTube URL that used to work suddenly fails, update yt-dlp first; see the yt-dlp on Debian guide.

Fish Shell Completions Are Missing

That is deliberate. The package ships bash and zsh completions only, because the fish completion script upstream generates is currently broken and would only cause errors in fish sessions.

Conflicting cliamp Installations

If you previously used the install script or make install, an older copy in ~/.local/bin may take precedence:

which -a cliamp

Remove the stray binary, or adjust your PATH so the APT-managed cliamp in /usr/bin wins.

Uninstalling

Remove cliamp with:

sudo apt remove cliamp

To also drop 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

Your playlists, themes and settings stay in ~/.config/cliamp/ until you delete that directory yourself.

Conclusion

cliamp brings the joy of Winamp back to the terminal and then goes much further, with streaming providers, internet radio, podcasts, a headless daemon and Lua plugins. Installing it from deb.griffo.io gives Debian users all of that without an installer script, a Go toolchain or manual updates.

Add the repository, install cliamp alongside yt-dlp, pick a theme and a visualizer, and keeping your music player current becomes just another apt upgrade.

Frequently Asked Questions

How do I install the latest cliamp on Debian?

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 Debian. 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. Skip cliamp upgrade, which is intended for self-managed binary installs rather than packaged ones.

Do I need ffmpeg and yt-dlp?

Not for MP3, FLAC, OGG or WAV files and most radio streams. You need ffmpeg for AAC, ALAC, Opus and WMA, and yt-dlp for YouTube, YouTube Music, SoundCloud, Mixcloud, Bandcamp and Bilibili. Install both with sudo apt install ffmpeg yt-dlp.

How do I install cliamp on Ubuntu?

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

Which Debian releases are supported?

Bookworm 12, Trixie 13, Forky 14 and Sid, 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.