luffy

README

LUFFY

Spiritual successor of flix-cli and mov-cli.

---

---

Overview

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

[!NOTE] Before creating an issue, make sure to update luffy

Installation

1. Arch Linux

paru -S luffy-bin

2. MacOS

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

3. Windows

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

[!IMPORTANT] On windows if you want to use the --show-image, you need to use the wezterm terminal emulator. It is installed as a dependency on windows.

4. Go Install

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

go install github.com/demonkingswarn/luffy@latest

5. Build from Source

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.

6. Android Installation

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

Dependencies

• 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)

Usage

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.

Flags

Flag	Alias	Description
--action	-a	Action to perform: play (default) or download.
--season	-s	(Series only) Specify the season number.
--episodes	-e	(Series only) Specify a single episode (5) or a range (1-5).
--best	-b	Auto-select the best available quality (skips fzf quality prompt).
--provider	-p	Select provider (e.g. sflix, braflix). Overrides config.
--history	-H	Browse watch history and resume a previous title.
--recommend	-r	Get personalised recommendations based on watch history.
--show-image	NA	Show poster previews in fzf (requires chafa and a supported terminal).
--debug	-d	Print debug information (URLs, decryption steps, etc.).
--help	-h	Show help message and exit.

Playback Controls

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

Action	Description
Next	Kill the player and move to the next episode.
Previous	Kill the player and move to the previous episode.
Replay	Restart the current episode from the beginning.
Quit	Kill the player and exit.

Examples

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

Configuration

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: ""

[!IMPORTANT] To see poster images, your terminal emulator must support a graphics protocol. Supported terminals include kitty, ghostty, WezTerm, and foot (sixel).

If you use kitty or ghostty, set image_backend: kitty in your config.

Providers

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

Provider	provider: value	Notes
FlixHQ	flixhq	Default
Sflix	sflix
Braflix	braflix
Movies4u	movies4u	Bollywood only
YouTube	youtube	Streams/downloads via yt-dlp
HDRezka	hdrezka	Experimental — may not always work

Example config:

provider: sflix