peertube-viewer-rs is a small utility to enable you to browse videos available on any PeerTube instances, without having to launch a web browser. It is heavily inspired from youtube-viewer.


Here is a screenshot of a basic usage of peertube-viewer-rs. When launching you are prompted with a search input. Once a search is done, you can either select one of the results by writing the corresponding number or do another search by typing anything else. When you chose to play a video, it will be launched in a video player (mpv by default)

peertube-viewer-rs interface

peertube-viewer and peertube-viewer-rs

peertube-viewer-rs is a rewrite in rust of peertube-viewer. Though the implementation language doesn't matter for the end user, the name has been changed since breaking changes have been introduced, mainly in the configuration.

cli interface

This section describes the cli interface for peertube-viewer-rs The interface features :

  • searching videos
  • launching videos
  • extracting video information

To learn how to use it see :


When launching peertube-viewer-rs you will be prompted to enter a search. search_prompt

You can then enter a search and will be displayed the results with:

  • the name of the video
  • the name of the channel
  • the host instance
  • the duration of the video
  • the view count of the video
  • the time since the video was posted
  • a nsfw tag for video tagged as such

The white/bold results are those that you have already been watched. select_prompt

You can either play one of the results by typing its ID or get more results with :n next

At any moment you can quit with :q

Here is a list of all the command that can be ran during a session:

  • :q quit (ctrl-D and ctrl-C have the same effect)
  • :n get more results for the same search or get more trending results when browsing trending
  • :p go back to the previous results (the opposite of :n)
  • :trending start browsing trending results
  • :channels <query> search channels by name
  • :chandle list videos from a channel
  • :info <id> give information on the current item (channel or video)
  • :comments <id> Lists the comments of a video
  • :browser <id> Open an item in the browser
  • :help get help

Command line arguments

This section documents all the command line arguments available.


  • -c, --config <config-file> Sets a custom config file location. The default is $XDG_CONFIG_HOME/peertube-viewer-rs/config.toml or $HOME/.config/peertube-viewer-rs/config.toml

  • --search-engine <api> search engine to be used to used (default is

  • -i, --instance <instance> instance to be browsed. The search will be made using this instance, and all API request will go through this instance.

  • -p, --player <player> player to play the videos with

  • --chandle <handle> list the videos of a channel from its handle (ex:

  • --player-args <player-args>... arguments to be passed to the player

  • --torrent-downloader <torrent-downloader> choose the torrent software to download the videos with

  • --torrent-downloader-args <torrent-downloader-arguments> arguments to be passed to the torrent downloader

The videos are played with the command: player <player-args> <url>. This is the same with the torrent when --use-torrent is specified.


  • -s, --select-quality When playing a video with this option, the user will be prompted to chose the video quality quality prompt

  • -t, --trending will start browsing trendings videos. If an initial query is passed with it, it will be ignored

  • --channels Search channels instead of videos

  • --local Only browse videos hosted on the instance you are connected to

  • --tag-nsfw Tag nsfw results. This is the default behavior. This flag is only useful to override the config file

  • --block-nsfw Block nsfw search results

  • --let-nsfw Don't tag nsfw results

  • --print-default-config prints the default confing to stdout and exit This is useful to get started on a config file. See configuration for more details

  • --print-full-example-config print an example of all possible config options and exit

  • --use-torrent will download the video via the torrent downloader instead of playing it. This requires a torrent downloader to be set (either via the corresponding option or in the configuration file)

  • --use-raw-urls the url to the video file will be passed to the player instead of the url to the web interface to watch it. It may be necessary for players without native support for PeerTube such as vlc. Some players (ex : mpv) may be able to show the video title in their interface if this option isn't used.

  • --color force coloring of output if it is disabled in the config file

  • --no-color remove coloring of output

  • -h, --help Prints help information

  • -V, --version Prints version information

Initial query

It is possible to launch peertube-viewer-rs with a query.

For example, peertube-viewer-rs mastodon will launch peertube-viewer-rs and immediately search for mastodon. It is also possible to set the instance that way: peertube-viewer-rs mastodon will search for mastodon videos on the instance

You can also play a single video with its url: peertube-viewer-rs will play the video.

Fancy features

peertube-viewer comes with a bunch of fancy but not really necessary features:

  • autocompletion the build systems automatically creates autocompletion for a few shells, available in ./completions
  • preloading peertube-viewer-rs is capable of preloading some info in advance. For example when typing :n, the search happens before you type ENTER, the same happens for video information when typing a video id. This makes peertube-viewer-rs much snappier.


The config file for peertube-viewer-rs can be placed

Linux$XDG_CONFIG_HOME/peertube-viewer-rs/config.toml or $HOME/.config/peertube-viewer-rs/config.toml


The config file is written in TOML An example of config file with all configuration option showed is available lower or can be obtained with peertube-viewer-rs --print-full-example-config



Configuration for peertube-viewer-rs general behavior


Set the behavior for nsfw content. It can be:

  • "block": block all nsfw content
  • "tag": the default, add a red nsfw tag next to the video
  • "let": treat nsfw content the same

This relies on the videos being properly tagged by the instance.


Set whether output should be colored options:

  • "enable": the default
  • "disable"


Set whether the --select-quality flag is enabled by default

  • true
  • false: the default


Set the editing mode. This allows the use of either vi or emacs keybinds. If you don't know what it is you don't need to worry about this option.

  • "emacs": the default
  • "vi"


Set the browser to use when opening items with the :browser command. If this variable isn't set, the BROWSER environment variable is used. If the environment variable isn't available, Firefox is the default


Set the User-Agent string to be used when making http requests. If can be a string, which will be used as is, or a boolean (false means remove the User-Agent header).

Defaults to: peertube-viewer-rs/<version>


nsfw = "block"
colors = "enable"
select-quality = true
edit-mode = "vi"
browser = "qutebrowser"
user-agent = false


Configuration for the player

The videos are played with the command: player <player-args> <url>.


Sets the command for the player, it is expected to be a string


Sets the arguments for the player, it is expected to be an array of strings


Set whether the --use-raw-urls flag is enabled by default

  • true
  • false: the default


Peertube has support for live streaming. Some regular videos are also made available through hls.

This settings tells peertube-viewer which one it should prefer if both are available.

  • false
  • true: the default

Note: this option doesn't do anything if either select-quality is true or if use-raw-urls is false


command = "vlc"
args = ["--no-audio", "-f"]
use-raw-urls = true
prefer-hls = false


Sets the command for the torrent downloader, it is expected to be a string


Sets the arguments for the torrent downloader, it is expected to be an array of strings


command = "transmission-remote"
args = ["-a"]


Instance settings


The search engine to be used ( is the default)


The main instance to be connected to, it is expected to be a string. It is incompatible with the search-engine option. The difference with the search engine option is that all API requests will be made through the same instance.


  • blocklist: an array of strings of instances to be blocked
  • allowlist: an array of strings of instances to be allowed

Both can't be present at the same time. When blocklist is present, no video from the instances listed will be shown. When allowlist is present, only videos from the instances listed will be shown.

Full configuration

This is an example of all configuration options that can be set


# available options: block, tag(add a nswf tag to search results), let(do nothing)
# default is tag
nsfw = "block"

# enable or disable, defaults to enable
colors = "disable"

# can be true or false
select-quality = true

# can be emacs or vi, defaults to emacs
edit-mode = "vi"

# If this option isn't present, the "BROWSER" environment variable is used
# If it isn't set, the default is Firefox
browser = "qutebrowser"

# Change the User-Agent used for requests
# Defaults to peertube-viewer-rs/<verion>
# false instead of a string removes the user agent
user-agent = "Mozilla/5.0 (X11; Linux x86_64; rv:79.0) Gecko/20100101 Firefox/79.0"

command = "mpv"
args = ["--volume=30"]

# can be true or false
use-raw-urls = true

# can be true or false
# When use-raw-urls is true and this is true, peertube-viewer will prioritize hls
# versions of videos instead of the static files for a given resolution
# This option is overrided to false when select-quality is given
prefer-hls = false

main = ""

# peertube-viewer supports using sepiasearch
# search-engine = ""

# allowlist = [""]
blocklist = [""]

command = "transmission-remote"
args = ["-a"]


peertube-viewer-rs is available on the AUR:


The download for the latest releases can be found on the download page of the project: Download

Releases can be found in the release page of the project: releases

Building from source

Building from source is rather easy, a rust toolchain newer than v1.74 is required.

For a debug build (faster to compile), run cargo build.

For a release build, run cargo build --release --locked.

Once compiled, the executable is located at target/release/peertube-viewer-rs. Completion for a variety of shells is also available in completions/. A manpage is available in the file peertube-viewer-rs.1.




  • Migrate away from chrono to use time directly
  • Update dependencies, including Clap to version 3
  • Fix weird behaviors with --channels
  • Remove error warning when default config is missing


  • Update dependencies


  • Fix error when using a local channel url with the configuration being set to a search engine
  • Add support for short frontend urls


  • Update all dependencies
  • Fix some warnings
  • Reduce the size of the binary by removing a dependency


  • Add support for using sepia search

  • Add support for livestreams

  • Add support for giving a link to a channel in the cli args

  • Fix some bugs


  • Support for HLS videos with the --use-raw-url option


  • User agent configuration
  • Fix multiple panics
  • Avoids being stuck in selecting a resolution with no option when no option is available


  • add :help menu


  • Syntax highlighting in the prompt

  • Tab completion in the prompt

  • Halved compile times

  • Halved binary size


  • Some internal changes
  • Better error messages


Replace white/blacklist by allow/blocklist.


Add command :browser to open items in the browser.


Add comments support via the :comments command.


Add edit-mode config option.


Migrate the project to a dedicated group on gitlab.


Add :info to get info on a specific item.


Fix info message displaying Search while browsing trending videos or videos from a channel.


Fix alignment when dealing with most unicode characters.

Add --channels, --chandle, :channels, :chandle features.


Fix trending not working on the first search.

Add --local filtering flag to only browse videos from the instance you are connected to.


Trending browsing.

UI improvements:

  • A total result count is now displayed for the current search.
  • Videos from blacklisted instances are now displayed as blocked (the title and other info isn't shown). Information can be obtained by typing its ID. You will be prompted to check if you are sure you want to play it before playing the video.
  • video information is now displayed before the prompt for quality selection


Small bug fixes in the configuration.


UI improvements:

  • More info displayed in search results:
    • channel
    • host instance
    • view count
  • Switched to elapsed time since publication instead of full date in the search results


Bug fixes:

  • Playing the last search result caused a new search to be launched instead of playing the video


Add commands :n and :p


Initial release, features searching and playing videos.