An ad-free YouTube Music player for your terminal.
Note: music-cli currently supports macOS and Linux only.
music-cli got both TUI and CLI; both of them are in sync, allowing agent controls (you can play music though CLI without the TUI and keeping it run in the background).
curl -fsSL https://raw.githubusercontent.com/Igidn/music-cli/main/install.sh | shRequires Python 3.10+ To install manually:
git clone https://github.com/Igidn/music-cli.git ~/music-cli &&
cd ~/music-cli &&
uv tool install .On Linux, you also need GStreamer MP4/AAC plugins:
# Debian / Ubuntu
sudo apt install gst-plugins-good1.0 gst-libav1.0
# Fedora / RHEL
sudo dnf install gstreamer1-plugins-good gstreamer1-libav
# Arch
sudo pacman -S gst-plugins-good gst-libavLogin to YouTube Music:
music-cli login| Command | Description |
|---|---|
play <query> |
Play a search result |
play --video-id <id> |
Play a specific video |
play --playlist <id> |
Play a playlist |
download <id> |
Download a track for offline listening |
pause / resume / toggle |
Transport control |
next / stop |
Skip ahead / halt playback |
seek +30 / seek 120 |
Skip forward or jump to a position |
volume 50 / volume +10 |
Set or adjust the volume |
mute on / loop on / auto-next on |
Toggle settings |
status / queue |
Current track and up-next list |
queue add <query> / queue add --video-id <id> |
Queue a track to play next |
search "..." |
Search YouTube Music |
playlists list / playlists play <id> |
List and play playlists |
playlists downloaded |
List offline downloads |
history |
Recently played tracks |
| Key | Action |
|---|---|
/ |
Search |
Space |
Play / Pause |
Alt+← / Alt+→ |
Seek ±5s |
n |
Next track |
Ctrl+n |
Queue selected track next |
a / l / m |
Auto-next / Loop / Mute |
+ / - |
Volume |
Ctrl+d |
Download current track |
q |
Quit, music keeps playing in the background |
Ctrl+q |
Quit and stop playback |
On macOS, music-cli integrates with Control Center, the Now Playing widget, media keys, and AirPods controls. The background daemon publishes the current track and responds to transport commands even when the TUI is closed.
| Control | Action |
|---|---|
| Play / Pause | Resume or pause the current track |
| Next | Skip to the next track |
| Previous | Restart the current track |
| Seek | Jump to a position in the track |
The integration uses Apple's public MediaPlayer framework. It needs no .app bundle or extra permissions and starts automatically with the daemon. Other platforms are unaffected.
MIT. See LICENSE.