Television (tv): a Rust fuzzy finder driven by TOML channels

What Television replaces, and for whom

Fuzzy finding in a terminal usually arrives attached to something else. Telescope comes with Neovim, fzf comes with a shell function you write yourself, and each editor ships its own picker. Television is a standalone binary that searches any command's output. The README lists the sources it already understands: files, text, git repositories, environment variables and docker containers. The default channel is files, so running tv with no argument is the shortest path to a picker. The intended user is someone who moves between editors and shells and does not want a different fuzzy finder in each one. The README points to integrations for Neovim, Vim, VSCode, Zed and JetBrains IDEs, which is the clearest signal that the project wants to sit underneath the editor rather than inside it.

How channels turn a shell command into a picker

The core abstraction is the channel. A channel is a TOML file that names a source command, an optional preview command, keybindings and actions. Television runs the source command, streams its lines into the match list, and renders the highlighted line through the preview command. The README's TLDR example shows the whole shape: [metadata] carries a name and description, [source] holds command = "tldr --list", [preview] holds command = "tldr '{}'", and [actions.open] holds command = "tldr '{}'" with mode = "execute". The {} placeholder is substituted with the selected line. That is the entire data flow, and it is why the project can search things it has never heard of: anything that prints lines to stdout is a candidate source. The repository layout backs this up. There is a cable/ directory at the top level, which is where the bundled channels live, and the README tells users to put their own files under ~/.config/television/cable/. The Cargo.toml lists frizbee for matching, ratatui for the interface, tokio for the async runtime and walkdir for the default file channel, so the matching engine is a separate crate rather than something written in-tree.

Installing Television and running a first search

The README calls the install script the recommended path. It downloads and runs a shell script from the project's documentation site, which is a reasonable default for a single binary but means you are trusting a script rather than a package signature.

curl -fsSL https://alexpasmantier.github.io/television/install.sh | bash

If you would rather have the package manager own the binary, the README lists Arch, Homebrew, Cargo, Scoop, WinGet and Nix. The Cargo route is the one that pins the build:

cargo install --locked television

Once the binary is on your PATH, the README's quick start is four commands. tv alone searches files, tv text searches file contents, tv git-repos finds git repositories, and tv --help lists the rest. Run tv first and you should see a list of files under the current directory with a preview pane; type to filter and the list narrows as you go.

Shell integration is a separate step and it is what gives you the two keybindings most people associate with a fuzzy finder. The README shows the Zsh and Bash lines:

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

After sourcing that file, Ctrl+T opens smart autocomplete and Ctrl+R opens history search. The README points to the shell integration page for other shells, so the two lines above are not the full list.

The first genuinely useful thing to write is your own channel. The README's example lives at ~/.config/television/cable/tldr.toml and uses tldr --list as the source. Copy that file, change the source command to something you actually run, and restart tv. If the command prints lines, the channel should appear in the picker list.

Where the channel format is thinner than it looks

The README gives one channel example and a link to a first-channel guide. It does not document the full schema. There is no reference for what keys [metadata] accepts beyond name and description, no list of valid mode values beyond the execute shown in the example, and no explanation of how multiple keybindings interact or what happens when two channels claim the same key. The [actions.open] block is named open in the example, but the README does not say whether action names are free-form or drawn from a fixed set. That matters as soon as you write a channel more complex than the TLDR one, because you are guessing at the shape of the file from a single sample. The documentation site is the place to check, and the README links to a channels page under the user guide, but the repository README alone is not enough to author a non-trivial channel with confidence. A second limitation is inherent to the design: the source is a shell command, so the quality of your picker depends on the quality of that command's output. A command that buffers its output before printing will not stream, and the finder will sit empty until it finishes. The README does not describe how buffering is handled.

Television against fzf, and what changes

fzf is the obvious comparison and the difference is architectural. fzf is a filter: it reads stdin, matches, and prints the selection to stdout. You compose it with pipes and shell functions, and the picker's behaviour is whatever your shell script does. Television inverts that. The picker is configured, not piped. A channel is a declarative file that bundles the source, the preview and the actions, so the same picker can be launched by name from any editor integration. The cost is that Television needs its own config directory and its own file format, while fzf works with a one-line pipe. If your workflow is already a set of shell functions, fzf fits without a new concept. If you want the same picker available from Neovim, VSCode and the terminal without rewriting the glue each time, Television's channel model is the reason to switch. The README credits telescope.nvim as an influence, which is visible in the preview-pane layout.

Build requirements, licence and what upgrading costs

Television is MIT licensed, stated in the README badge and in Cargo.toml. That permits commercial and closed-source use, but the repository does not carry a separate contributor licence agreement or a NOTICE file, and I am not giving legal advice: if your organisation has a policy on bundled dependencies, check the licences of the crates in Cargo.lock rather than only the top-level MIT declaration. Building from source requires Rust 1.98 or newer, per the rust-version field, and the crate uses edition 2024. The justfile shows the maintainer's own loop: just setup installs git hooks and runs cargo build, just test runs the suite with a four-thread limit, and just test-fast sets TV_TEST_DELAY_MS=50 to shorten test delays. That last variable is worth knowing if you plan to contribute, because the default test run is slower by design. Upgrading is a binary swap if you installed through a package manager. The release history shows patch releases roughly a month apart through mid-2026, so a pinned version will drift. The last push to the repository was on 2026-09-19, which is recent, but the README does not document a migration path or a deprecation policy for the channel format, so a channel you write today has no stated compatibility guarantee across minor versions.

Editorial conclusion

Adopt Television if you spend your day in a terminal, want a fuzzy finder that is not tied to one editor, and are comfortable writing a TOML file to add a data source. Do not adopt it if you need a stable, documented plugin API: the channel schema is shown by example, not specified. Before committing, run the install script or cargo install --locked television, open tv --help to confirm the channels you need exist, and write one custom channel against your own command to see whether the preview and action keys behave as you expect.

Frequently asked questions

Official sources

1. alexpasmantier/television on GitHub
2. License: MIT
3. Project website
4. README
5. Releases