📺 television

A blazingly fast general purpose fuzzy finder TUI.

The revolution will (not) be televised.

About

Television is a blazingly fast general purpose fuzzy finder TUI.

It is inspired by the neovim telescope plugin and is designed to be fast, efficient, simple to use and easily extensible. It is built on top of tokio, ratatui and the nucleo matcher used by the helix editor.

Installation

Homebrew

brew install television

Arch Linux

pacman -S television

Debian-based (Debian, Ubuntu, Pop!_OS, Linux Mint, etc.)

curl -LO https://github.com/alexpasmantier/television/releases/download/0.7.0/television_0.7.0-1_amd64.deb
sudo dpkg -i television_0.7.0-1_amd64.deb

Conda-forge (cross-platform)

pixi global install television

Binary

From the latest release page:

• Download the latest release asset for your platform (e.g. tv-vX.X.X-linux-x86_64.tar.gz if you're on a linux x86 machine)
• Unpack and copy to the relevant location on your system (e.g. /usr/local/bin on macos and linux for a global installation)

Cargo

Setup the latest stable Rust toolchain via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update

Install television:

cargo install --locked television

Shell integration (currently only zsh)

To enable shell integration, run:

echo 'eval "$(tv init zsh)"' >> ~/.zshrc

And then restart your shell.

Usage

tv [channel] #[default: files] [possible values: env, files, gitrepos, text, alias]

# e.g. to search through files
tv files

# e.g. to search through environment variables
tv env

# piping into tv (e.g. logs)
my_program | tv

# piping into tv with a custom preview command
fd -t f . | tv --preview 'bat -n --color=always {0}'

By default, television will launch with the files channel on.

tv's files channel running on the curl codebase

📺 Built-in Channels

The following built-in channels are currently available:

• files: search through files in a directory tree.
• text: search through textual content in a directory tree.
• gitrepos: search through git repositories anywhere on the file system.
• env: search through environment variables and their values.
• alias: search through shell aliases and their values.
• stdin: search through lines of text from stdin.

🍿 Cable channels

Tired of broadcast television? Want to watch your favorite shows on demand? television has you covered with cable channels. Cable channels are channels that are not built-in to television but are instead provided by the community.

You can find a list of cable channels ideas on the wiki.

Installing cable channels

Installing cable channels is as simple as creating provider files in your configuration folder.

A provider file is a *channels.toml file that contains cable channel prototypes defined as follows:

my-custom-channels.toml

[[cable_channel]]
name = "git-log"
source_command = 'git log --oneline --date=short --pretty="format:%h %s %an %cd" "$@"'
preview_command = 'git show -p --stat --pretty=fuller --color=always {0}'

[[cable_channel]]
name = "my-dotfiles"
source_command = 'fd -t f . $HOME/.config'
preview_command = 'bat -n --color=always {0}'

This would add two new cable channels to television available:

• using the remote control mode
• through the cli (e.g. tv git-log, tv my-dotfiles)

Deciding which part of the source command output to pass to the previewer:

By default, each line of the source command can be passed to the previewer using {}.

If you wish to pass only a part of the output to the previewer, you may do so by specifying the preview_delimiter to use as a separator and refering to the desired part using the corresponding index.

Example:

[[cable_channel]]
name = "Disney channel"
source_command = 'echo "one:two:three:four" && echo "five:six:seven:eight"'
preview_command = 'echo {2}'
preview_delimiter = ':'
# which will pass "three" and "seven" to the preview command

Keybindings

Default keybindings are as follows:

Key	Description
↑ / ↓	Navigate through the list of entries
Ctrl + u / d	Scroll the preview pane up / down
Enter	Select the current entry
Ctrl + y	Copy the selected entry to the clipboard
Ctrl + r	Toggle remote control mode
Ctrl + s	Toggle send to channel mode
Ctrl + g	Toggle the help panel
Esc	Quit the application

These keybindings are all configurable (see Configuration).

Configuration

Default (may be overriden) locations where television expect the configuration files to be located for each platform:

Platform	Value
Linux	$HOME/.config/television/config.toml
macOS	$HOME/.config/television/config.toml
Windows	{FOLDERID_LocalAppData}\television\config

Or, if you'd rather use the XDG Base Directory Specification, tv will look for the configuration file in $XDG_CONFIG_HOME/television/config.toml if the env variable is set.

Default configuration: config.toml

Themes

Builtin themes are available in the themes directory. Feel free to contribute your own.

A few examples:

catppuccin	gruvbox-dark
solarized-dark	nord

You may use your own custom themes by adding files to the themes directory in your configuration folder and then referring to them by file name through the configuration file.

config_location/
├── themes/
│   └── my_theme.toml
└── config.toml

Matcher behavior

television uses a fuzzy matching algorithm to filter the list of entries. The algorithm that is used depends on the input pattern that you provide.

Matcher	Pattern
Fuzzy	foo
Substring	'foo / !foo to negate
Prefix	^foo / !^foo to negate
Suffix	foo$ / !foo$ to negate
Exact	^foo$ / !^foo$ to negate

For more information on the matcher behavior, see the nucleo-matcher documentation.

Design (high-level)

Channels

Television's design is primarily based on the concept of Channels. Channels are just structs that implement the OnAir trait.

As such, channels can virtually be anything that can respond to a user query and return a result under the form of a list of entries. This means channels can be anything from conventional data sources you might want to search through (like files, git repositories, remote filesystems, environment variables etc.) to more exotic implementations that might inclue a REPL, a calculator, a web browser, search through your spotify library, your email, etc.

Television provides a set of built-in Channels that can be used out of the box (see Built-in Channels). The list of available channels will grow over time as new channels are implemented to satisfy different use cases.

Transitions

When it makes sense, Television allows for transitions between different channels. For example, you might want to start searching through git repositories, then refine your search to a specific set of files in that shortlist of repositories and then finally search through the textual content of those files.

This can easily be achieved using transitions.

Previewers

Entries returned by different channels can be previewed in a separate pane. This is useful when you want to see the contents of a file, the value of an environment variable, etc. Because entries returned by different channels may represent different types of data, Television allows for channels to declare the type of previewer that should be used. Television comes with a set of built-in previewers that can be used out of the box and will grow over time.

Terminal Emulators Compatibility

Here is a list of terminal emulators that have currently been tested with television and their compatibility status.

Terminal Emulator	Tested Platforms	Compatibility
Alacritty	macOS, Linux	✅
Kitty	macOS, Linux	✅
iTerm2	macOS	✅
Wezterm	macOS, Linux, Windows	✅
macOS Terminal	macOS	functional but coloring issues
Konsole	Linux	✅
Terminator	Linux	✅
Xterm	Linux	✅
Cmder	Windows	✖️
Foot	Linux	✅
Rio	macOS, Linux, Windows	✅
Warp	macOS	✅
Hyper	macOS	✅

Contributions

Contributions, issues and pull requests are welcome.

See CONTRIBUTING.md and good first issues for more information.