• Installation
  • Arch Linux
  • MacOS
  • Windows
  • Go Install
  • Build from Source
  • Android Installation
• Dependencies
• Usage
• Configuration
• Hooks & MpvArgs
• Providers

paru -S luffy-bin

brew tap gamedevCloudy/tools
brew install --cask iina
brew install luffy

Make sure you have scoop.sh installed on your system.

scoop bucket add demon-apps https://github.com/DemonKingSwarn/flix-cli-bucket.git
scoop bucket add extras
scoop install luffy

If you have Go installed, you can easily install Luffy:

go install github.com/demonkingswarn/luffy@latest

1. Clone the repository:

   git clone https://github.com/demonkingswarn/luffy.git
   cd luffy

2. Build and install:

   go install .

   Ensure your $GOPATH/bin is in your system's PATH.

Install termux (Guide)

pkg up -y
pkg in fzf python-yt-dlp
curl -sL "https://github.com/DemonKingSwarn/luffy/releases/download/v1.1.0/luffy-android-arm64" -o $PREFIX/bin/luffy
chmod +x $PREFIX/bin/luffy

• mpv - Video Player for Linux and Windows
• vlc - Alternate video player for Linux and Windows
• iina - Video Player for MacOS
• vlc-android - Video Player for Android
• yt-dlp - Download manager
• fzf - For selection menus
• chafa & libsixel - For poster previews (--show-image)

luffy [query] [flags]

[query] is the title you want to search for (e.g., "breaking bad", "dune", "one piece"). The query is optional when using --history or --recommend.

When watching a TV series, an fzf menu appears alongside the player with four options:

Search & Play a Movie

luffy "dune"

Download a Movie

luffy "dune" --action download

Play a TV Episode

luffy "breaking bad" -s 1 -e 1

Download a Range of Episodes

luffy "stranger things" -s 2 -e 1-5 -a download

Auto-select Best Quality

luffy "dune" --best

Use a Different Provider

luffy "breaking bad" --provider sflix

Resume from Watch History

luffy --history

Get Personalised Recommendations

luffy --recommend

Recommendations with Poster Previews

luffy --recommend --show-image

The config file lives at ~/.config/luffy/config.yaml. All fields are optional; defaults are shown below.

# Path to the fzf binary. Set to an absolute path if fzf is not on PATH.
fzf_path: fzf

# Video player: "mpv" (default) or "vlc". IINA is used automatically on macOS.
player: mpv

# chafa rendering backend for poster previews.
# Options: sixel (default), kitty, iterm, symbols
image_backend: sixel

# Default search provider.
provider: flixhq

# Directory where downloaded files are saved. Defaults to home directory.
dl_path: ""

# Quality selection: leave empty to show an fzf prompt, or set to "best"
# to always auto-select the highest available quality.
quality: ""

# Extra arguments appended to every mpv invocation (ignored on VLC/IINA/Android).
# mpv_args:
#   - "--hwdec=auto"
#   - "--volume=80"

# Lifecycle hooks — shell commands run at key playback events.
# LUFFY_TITLE, LUFFY_URL, LUFFY_SEASON, LUFFY_EPISODE, LUFFY_EP_NAME,
# LUFFY_PROVIDER, LUFFY_ACTION, LUFFY_STREAM_URL, and LUFFY_POSITION
# are set in the environment for every hook.
# hooks:
#   on_play: 'notify-send "Now playing" "$LUFFY_TITLE"'
#   on_exit: 'echo "$LUFFY_TITLE stopped at ${LUFFY_POSITION}s" >> ~/luffy.log'
#   on_download: 'notify-send "Downloading" "$LUFFY_TITLE"'

Shell commands can be run at three lifecycle points, and extra mpv flags can be injected via config. See docs/hooks.md for the full reference.

Extra arguments appended verbatim to every mpv invocation (ignored on VLC / IINA / Android):

mpv_args:
  - "--hwdec=auto"
  - "--volume=80"

hooks:
  on_play: 'notify-send "Now playing" "$LUFFY_TITLE"'
  on_exit: 'echo "$LUFFY_TITLE stopped at ${LUFFY_POSITION}s" >> ~/luffy.log'
  on_download: 'notify-send "Downloading" "$LUFFY_TITLE"'

Every hook receives LUFFY_TITLE, LUFFY_URL, LUFFY_SEASON, LUFFY_EPISODE, LUFFY_EP_NAME, LUFFY_PROVIDER, LUFFY_ACTION, LUFFY_STREAM_URL, and LUFFY_POSITION as environment variables.

You can set the default provider in the config file (~/.config/luffy/config.yaml) or override it per-run with --provider.

Example config:

provider: sflix