wtwitch - terminal user interface for Twitch


wtwitch [COMMAND] [streamer, search term, game, player, quality]


Wtwitch is a terminal program that uses the Twitch API and the streamlink package to provide Twitch browsing, subscription, and playback functionality without signing up for a Twitch account and without loading or executing Twitch's proprietary JavaScript.


Viewing and browsing streams

w streamer, watch streamer

Watch the specified streamer.
e.g. wtwitch w dratnos

v streamer [optional VOD number], vod streamer [optional VOD number]

List the latest VODs from a streamer. Optionally, supply the number of the VOD you want to watch to open it in your default player.
e.g. wtwitch v dratnos
e.g. wtwitch v dratnos 5

t, top

View the top games and streams on Twitch.
e.g. wtwitch t

g game, game game

View the top streamers for a specified game. Game names with spaces must be quoted, or the spaces must be escaped with \.
e.g. wtwitch g "world of warcraft"
e.g. wtwitch g world\ of\ warcraft

e search-term

Search games and categories for search-term. Search terms with spaces must be quoted, or the spaces must be escaped with \.
e.g. wtwitch e warcraft

n search-term

Search streamers and channels for search-term. Search terms with spaces must be quoted, or the spaces must be escaped with \.
e.g. wtwitch n warcraft

b streamer, block streamer

Block a specified streamer, preventing them from being listed in any output. If the streamer is already blocked, blocking them again will remove them from the blocklist. Use b without specifying a streamer to show your blocklist.
You can block or unblock multiple streamers at once, by separating them with a space.
e.g. wtwitch b dratnos
e.g. wtwitch b dratnos emongg sleepy
e.g. wtwitch b


s streamer, sub streamer

Subscribe to a specific streamer.
You can subscribe to multiple streamers at once, by separating them with a space.
e.g. wtwitch s dratnos
e.g. wtwitch s dratnos emongg sleepy

u streamer, unsub streamer

Unsubscribe from a specified streamer.
You can unsubscribe from multiple streamers at once, by separating them with a space.
e.g. wtwitch u dratnos
e.g. wtwitch u dratnos emongg sleepy

c, check

View your player/quality settings and the status of the streamers you are subscribed to.
e.g. wtwitch c

Configuration options

p player, player player

Change the default player that gets passed to Streamlink.
e.g. wtwitch p vlc

q quality, quality quality

Change the default quality that gets passed to Streamlink. 1080p60, 720p60, 720p, 480p, 360p, 160p, best, worst, and audio_only are acceptable qualities. You can specify fallback qualities separated by a comma.
e.g. wtwitch q 720p60,720p,best


Toggle the printing of offline subscriptions with wtwitch c.
e.g. wtwitch f


Toggle the usage of colors in wtwitch output.
e.g. wtwitch l


h, help

Print a short usage guide.
e.g. wtwitch h


Print the current version of wtwitch.
e.g. wtwitch v


Wtwitch will try its best to complete your input. When tabbing after wtwitch u, wtwitch will list/fill in your current subscriptions, since it only makes sense to unsubscribe from someone you're subscribed to.

When tabbing after wtwitch w, wtwitch will get a list of your subscriptions that are online, and only list/fill in your subscribed streamers that are currently streaming (even though these are not the only streamers you can watch with w).



Wtwitch will tell Streamlink to use mpv by default. Wtwitch favors mpv because mpv supports Wayland and custom window titles, such as "Watching dratnos on Twitch (1080p 60.000fps)". Wtwitch will use VLC automatically if you have VLC installed and don't have mpv installed.

You can set which video player you'd like wtwitch to pass to Streamlink with wtwitch p player. You can pass any player you'd pass to Streamlink, and wtwitch will make sure the player you're trying to set as the default player is installed.


Wtwitch tells Streamlink to choose the "best" quality by default. You can set which quality you'd like wtwitch to pass to Streamlink with wtwitch q quality. You can pass any quality you'd pass to Streamlink, including fallback qualities (like "720p,480p,worst"), and wtwitch will make sure your input is valid.


Wtwitch tells Streamlink to bypass Twitch ads. If you want to support a streamer, consider donating to them directly rather than subscribing to them on Twitch, as Twitch takes 50% of the subscription fee.


Wtwitch supports the XDG Base Directory specification. If your $XDG_CONFIG_HOME and $XDG_CACHE_HOME are their default values (~/.config and ~/.cache respectively), the configuration and blocklist files are at ~/.config/wtwitch/config.json, and cache files are kept in ~/.cache/wtwitch.

You should never need to edit these files manually; you should use the commands listed under COMMANDS above.


This file exists in wtwitch's config directory, and wtwitch will source this file before running. You can put commands or variables here for wtwitch to source. This is useful on macOS, for example, to set a custom $PATH or $PYTHONPATH to support non-standard dependency locations specifically for wtwitch.


Wtwitch does not natively support syncing subscriptions across computers, but syncing subscriptions can be achieved easily using Syncthing and a utility already installed on your GNU/Linux computer. Syncthing is a powerful synchronization program for multiple operating systems licensed under the Mozilla Public License v2, which is FSF approved. You can look at Syncthing's homepage for more information, as well as their user documentation:


After setting up Syncthing on the computers on which you wish to sync subscriptions, copy your subscriptions file from ~/.config/wtwitch/config.json to a directory that you are syncing with Syncthing. Then link the file to the previous location. For example, if you copied your subscriptions file to ~/Documents/Config, you can link it to the correct location with the command:

ln -sf ~/Documents/Config/config.json ~/.config/wtwitch/config.json


View the changes/additions for the latest installed version of wtwitch with the command:

pacman -Qc wtwitch


Full support:

Partial support:

User-contributed translations are welcome!


Please file requests and report any bugs at: https://github.com/krathalan/wtwitch/issues

If you are reporting a bug, please attach a debug log.

To start wtwitch in debug mode, set the environment variable WTWITCH_DEBUG=on. You should also redirect all output to a log file. You can run wtwitch in debug mode in a one-off command like so:

WTWITCH_DEBUG=on wtwitch [command] &> debug.log


Wtwitch itself is licensed under the GPLv3.


jq is licensed under the MIT license.

Streamlink is licensed under the 2-clause BSD license.

cURL is licensed under the MIT license.

VLC and mpv, should you choose either as your player, are both licensed under both the GPLv2 and LGPLv2.1 licenses.

All licenses, for wtwitch itself and its dependencies, are FSF approved: https://www.gnu.org/licenses/license-list.html