Skip to content


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation


Deriving its name from the Hebrew word "מבול," meaning flood, deluge, or (loosely) torrent, Mabel is a fancy BitTorrent client for the terminal.

Mabel builds on the excellent work of others in the open source community, including:


Mabel downloading several torrents, default theme

Mabel looking at torrent details, desert theme


  • A Nerd Font installed and enabled in your terminal


Coming soon to a package manager near you!

# Build from source
go install
# Homebrew
brew install mabel

Desktop File

Some systems can install the desktop entry file to get Mabel to appear in the list of applications (and open torrent files with xdg-open):

curl -sSL -o ~/.local/share/applications/mabel.desktop
update-desktop-database ~/.local/share/applications


mabel [OPTIONS] [TORRENT]...

When run without any arguments, Mabel starts a full TUI client.

When passed a single torrent (infohash, magnet link, .torrent file), Mabel starts in "mini" mode.

When multiple torrents are provided as arguments, Mabel opens the full TUI client with the corresponding torrents added.


The mini client downloads a single torrent, displaying its name and download stats. Press q or ctrl+c to close the client.


The full client manages a list of torrents downloading in parallel.

A brief breakdown of the controls:

  • Scroll through the list with hjkl or the arrow keys
  • Press a to add a torrent
  • Get more details about a torrent with return
  • Perhaps most importantly – press ? to expand the help menu at the bottom of the view

Once again, press q or ctrl+c to close the client.

Config and Flags

Mabel can be configured via a TOML file or via flags at runtime. Flags take precedence over the config file.

Config File

Located at $XDG_CONFIG_HOME/mabel/config.toml. A basic example:

# The default torrent download directory.
# Supports expansion of ~ characters
download = "~/movies/buffer"

# The port to which the client will bind
# Default: 42069
port = 126

# Toggle client logging (logs are written to $XDG_STATE_HOME/mabel)
log = false

# Mabel always prefers encrypted connections. If set to true,
# require_encryption will have Mabel ignore unencrypted peers.
require_encryption = false


The theme key is special, as it can be one of two types.

As a string, theme selects one of our default themes. The currently available themes are:

  • default
  • desert
  • purple
  • 8-bit/ansi

As a table [a.k.a (hash)map or dictionary], the theme key can also allow you to customize your colors in-depth. The theme.base key provides a fallback for any unset values in the table, and follows the same rules as the string theme key.

The theme.gradient* keys customize the gradients used in progress bars throughout Mabel. gradient-solid takes precedence over gradient-start and gradient-end. The latter two only work with 24-bit color.

Some examples:

# just the desert theme
theme = "desert"

# default, with a red primary color
base = "default"
primary = "#FF0000"

# the same as previous
primary = "#FF0000"

# 8-bit, with a blue error color
base = "8-bit"
error = "12"

# default, with a gradient from Pink Lightly Toasted to SMMR Software
# Example Color 2 (
gradient-start = "#D52941"
gradient-end = "#990D35"

# a completely custom theme where everything is green
primary = "#00FF00"
light = "#00FF00"
dark = "#00FF00"
error = "#00FF00"
tooltip = "#00FF00"
gradient-solid = "#00FF00"


The keys key allows the user to configure their key bindings in both the home and add torrent screen. To remap a specific key, use the key keys.SCREEN.ACTION. The property key selects the actual key being used (with names and options defined by Bubble Tea), icon defines the icon in the help menu, and desc defines the help text in the help menu.

In the home screen, options for key bindings include up, down, next, previous, add, delete, details, deselect, help, and quit. In the add torrent screen, you can configure the quit, previous, and next keys.

Some examples:

  # keys in the home screen

    # changes the next keybind to tab, with help menu info "↹ next"
      key = "tab"
      icon = ""
      desc = "next"

    # changes the help keybind to b, keeping the icon as default but
    # the description as "sos"
      key = "b"
      desc = "sos"
  # keys in the add torrent screen

    # just changes the quit keybind to return
      key = "return"


Runtime flags are documented in Mabel's help message, which you can view by passing -h on invocation. Flags encompass all the options configurable in the TOML config, plus help and version information messages.



A SMMR Software creation. 🏖