YouTube in your terminal. Clean and distraction-free.
- Syncplay support – watch videos together in sync
- Audio-only playback & downloads
- Download videos or audio
- Interactive format/quality selection when playing or downloading
- External config file
- Playback history and quick re-play
- Adjustable search result limit
- Custom download directory
- Self-update (--update) for manual installations only
- Copy short YouTube URLs to clipboard or print them
- Channel subscriptions with a personalized feed
| Selector | Features | Best For |
|---|---|---|
| fzf (default) | Terminal-based, thumbnail previews, lightweight | Most users (fast + previews) |
| rofi | GUI menu, keyboard-driven, clean look | Users who prefer a graphical menu |
| sentaku | Very minimal, no previews | Systems without Go/fzf support |
yay -S ytsurf
# or
paru -S ytsurfbrew tap stan-breaks/ytsurf https://github.com/stan-breaks/ytsurf
brew install stan-breaks/ytsurf/ytsurfmkdir -p ~/.local/bin
curl -o ~/.local/bin/ytsurf https://raw.githubusercontent.com/Stan-breaks/ytsurf/main/ytsurf.sh
chmod +x ~/.local/bin/ytsurfMake sure ~/.local/bin is in your PATH.
- Required:
bash,yt-dlp,jq,curl,mpv,fzf,chafa,ffmpeg - Optional:
rofi,sentaku,syncplay
Arch Linux install:
sudo pacman -S yt-dlp jq curl mpv fzf chafa rofi ffmpegUSAGE:
ytsurf [OPTIONS] [QUERY]
OPTIONS:
--audio Play/download audio-only version
--download Download instead of playing
--format Interactively choose format/resolution
--rofi Use rofi instead of fzf for menus
--syncplay Watch youtube with friend from the terminal
--subscribe, -s Add a channel to the subs.txt
--feed,-F View videos from your feed
--sentaku Use sentaku instead of fzf or rofi(for system that can't compile go)
--history Show and replay from viewing history
--limit <N> Limit number of search results (default: in the config)
--edit, -e edit the configuration file
--help, -h Show this help message
--version Show version info
--copy-url Copy or display the video link
EXAMPLES:
ytsurf lo-fi study mix
ytsurf --audio orchestral soundtrack
ytsurf --download --format jazz piano
ytsurf --historyRun ytsurf without arguments to enter interactive mode.
Defaults check for default config in ~/.config/ytsurf/config.
CLI flags always override config values.
Example config:
# ~/.config/ytsurf/config
# Set a higher default search limit
limit=25
# Always use audio-only mode
audio_only=true
# Set a custom download directory
download_dir="$HOME/Videos/YouTube"MPV doesn't play the selected video
Some systems have mpv configured to prefer youtube-dl instead of yt-dlp, which causes ytsurf to show “playing…” without actually starting playback.
Fix: Rename your yt-dlp binary so that MPV uses it automatically:
sudo mv /usr/bin/yt-dlp /usr/bin/youtube-dlOr create a symlink instead (safer):
sudo ln -s /usr/bin/yt-dlp /usr/local/bin/youtube-dlMPV will now correctly pick up yt-dlp for streaming.
Contributions are welcome! Please see CONTRIBUTING.md. Check out FUTURE_FEATURES.md for upcoming ideas.
Released under the GNU General Public License v3.0.