A terminal-based YouTube Music client written in Go. Search music, download audio, manage a play queue, bookmark favorites, and play music — all from the keyboard, inside your terminal.
curl -fsSL https://anas1412.github.io/ytmgo/install.sh | bashIt detects your system automatically:
- Arch Linux — installs via
paruoryayfrom the AUR (falls back to binary) - Other Linux / macOS — downloads the static binary and installs deps
Override the install dir:
YTMGO_INSTALL_DIR=/opt/bin curl ... | bash
The one-liner above handles this, but you can also install directly:
yay -S ytmgo
# or
paru -S ytmgogo build -o ytmgo .
./ytmgocurl -fsSL https://anas1412.github.io/ytmgo/uninstall.sh | bashPrompts you with three confirmations:
- Remove binary — deletes
~/.local/bin/ytmgo(or/usr/local/bin/ytmgo) - Remove user data — deletes
~/.config/ytmgo/(settings, favorites, play history, queue) - Remove downloads — deletes
~/.local/share/ytmgo/downloads/(all your downloaded files)
| Flag | Behavior |
|---|---|
-y / --yes |
Skip all prompts, remove everything |
--keep-downloads |
Keep your downloaded audio files |
--keep-user-data |
Keep your config database (settings, favorites, history) |
# Silent full removal
curl -fsSL https://anas1412.github.io/ytmgo/uninstall.sh | bash -s -- -y
# Remove binary + config, keep your music files
curl -fsSL https://anas1412.github.io/ytmgo/uninstall.sh | bash -s -- -y --keep-downloads
# Remove binary + files, keep your favorites and settings
curl -fsSL https://anas1412.github.io/ytmgo/uninstall.sh | bash -s -- -y --keep-user-dataSystem dependencies (mpv, yt-dlp, ffmpeg) are not touched — they may be used by other applications.
- Search from the terminal — No browser, no tabs. Search, pick, and queue without leaving your terminal.
- Download in one key — Press
xon any track and it downloads. Queue-friendly, one at a time, with progress feedback. - Favorites page —
fto bookmark. Dedicated page to browse them all. Heart shows on every favorited track. - Full mouse support — Click tabs, click panels, click the progress bar to seek. Most terminal apps can't do this.
- Discord Rich Presence — Show what you're listening to — track, artist, play status — live on your Discord profile.
- Static binary, no bloat — Pure Go, no Electron, no browser engine. Starts instantly, sips RAM, gets out of your way.
- Go 1.22+
- mpv — audio playback backend
- yt-dlp — YouTube / YouTube Music streaming URL resolution and downloads
- ffmpeg — audio extraction for downloads (yt-dlp dependency)
These are required for playback and downloads:
# Debian / Ubuntu
sudo apt install mpv yt-dlp ffmpeg
# macOS
brew install mpv yt-dlp ffmpeg
# Arch Linux
sudo pacman -S mpv yt-dlp ffmpegyt-dlp is the core download engine — it searches YouTube Music for the track and streams/downloads the audio. ffmpeg is used by yt-dlp for audio extraction.
# Clone or navigate to the project
cd ytmgo
# Build
go build -o ytmgo .
# Run
./ytmgoOr use the pre-built binary included in the repository.
| Step | Action |
|---|---|
| 1 | Press Tab to focus the search input |
| 2 | Type a query and press Enter |
| 3 | Browse results in the left panel (↑↓ / jk) |
| 4 | Press Enter on a result to add to queue + start download |
| 5 | Tab to the queue panel, select a track, press Enter to play |
| 6 | Control playback with keys (see below) |
Tab cycles focus through: search input → result list → queue panel → settings — and the focused panel's border glows violet.
Mouse support — Click header tabs to switch pages, click list items to select, double-click to activate, click the progress bar to seek, and click the controls row to play/pause, adjust volume, or toggle shuffle/repeat.
| Key | Action |
|---|---|
Tab |
Cycle focus: search → results → queue → search |
↑↓ / jk |
Navigate lists |
Enter |
Search: add to queue / Queue: play track |
Space |
Play / Pause |
n / → |
Next track |
p / ← |
Previous track |
h / Ctrl+B |
Seek backward 5s |
l / Ctrl+F |
Seek forward 5s |
+ / = |
Volume up |
- / _ |
Volume down |
d / Delete |
Remove from queue |
D |
Clear entire queue |
C |
Clear play history |
f |
Toggle favorite on selected track |
s |
Toggle shuffle |
r |
Cycle repeat: OFF → ONE → ALL |
x |
Download selected track immediately |
R |
Refresh recommendations |
U |
Check for updates / confirm install |
1 / 2 / 3 / 4 |
Switch page: Stream / Favorites / Library / Settings |
Ctrl+↑ / Ctrl+↓ |
Move item up/down in queue |
o |
Open download directory |
? |
Show keyboard shortcuts |
esc |
Cancel / back |
q / Ctrl+C |
Quit |
- Bubble Tea — TUI framework
- Bubbles — TUI components
- Lipgloss — Terminal styling
- mpv — Media player backend
- yt-dlp — YouTube Music streaming and downloads
- ffmpeg — Audio extraction for downloads
- TIDAL HiFi Proxy API — Track search and recommendations
- modernc.org/sqlite — Embedded SQLite (no CGO)
MIT