Getting Started

This guide will help you install and start using youtube-music-cli.

Prerequisites

Before installing youtube-music-cli, you need to install:

mpv (Required)

mpv is the media player used for audio playback.

Windows:

# Scoop
scoop install mpv

# Chocolatey
choco install mpv

macOS:

brew install mpv

Linux:

# Ubuntu/Debian
sudo apt install mpv

# Arch
sudo pacman -S mpv

# Fedora
sudo dnf install mpv

yt-dlp (Required)

yt-dlp extracts audio streams from YouTube.

Windows:

scoop install yt-dlp
# or
choco install yt-dlp

macOS:

brew install yt-dlp

Linux:

pip install yt-dlp
# or
sudo apt install yt-dlp

Installation

npm (Recommended)

npm install -g @involvex/youtube-music-cli

Bun

bun install -g @involvex/youtube-music-cli

Homebrew

brew install involvex/youtube-music-cli/youtube-music-cli

GitHub Releases

https://github.com/involvex/youtube-music-cli/releases

Install Script (bash)

curl -fssl https://raw.githubusercontent.com/involvex/youtube-music-cli/main/scripts/install.sh | bash

Install Script (PowerShell)

iwr https://raw.githubusercontent.com/involvex/youtube-music-cli/main/scripts/install.ps1 | iex

From Source

git clone https://github.com/involvex/youtube-music-cli.git
cd youtube-music-cli
bun install
bun run build
bun link

First Run

Launch the TUI:

youtube-music-cli

You should see the main player interface. Press ? for help or / to search.

Basic Usage

Search for Music

Press / to open search
Type your query
Press Enter to search
Use ↑/↓ to navigate results
Press Enter to play

Playback Controls

Space - Play/Pause
n or → - Next track
b or ← - Previous track
= - Volume up
- - Volume down

? - Help screen
, - Settings
p - Plugins
g - Suggestions
Esc - Go back
q - Quit

CLI Commands

You can also use youtube-music-cli from the command line:

# Search
youtube-music-cli search "lofi beats"

# Play a specific video
youtube-music-cli play dQw4w9WgXcQ

# Headless mode (no TUI)
youtube-music-cli search "music" --headless