Quickstart
Welcome to Television! This guide will get you up and running in under 5 minutes.
What is Television?
Television (tv) is a fast, portable fuzzy finder for the terminal. Think of it as a universal search tool that can search through:
- Files and directories
- Text content (like grep, but interactive)
- Git repositories, branches, logs
- Environment variables
- Docker containers
- And anything else you can pipe to it
Basic Usage
Your First Search
After installing tv, open a terminal and run:
tv
This launches tv with the default channel (usually files). You'll see:
- An input bar at the top for typing your search
- A results panel showing matching entries
- A preview panel (if configured) showing content
Try it: Type a few characters and watch results filter in real-time.
Using Built-in Channels
Channels are predefined search configurations. Try these common ones:
tv files # Browse files (default)
tv text # Search file contents with ripgrep
tv git-repos # Find git repositories
tv env # Search environment variables
To see all available channels:
tv list-channels
Piping Data
Pipe any command's output into tv:
# Search through logs
cat /var/log/syslog | tv
# Filter git history
git log --oneline | tv
# Search command output
ps aux | tv
Navigation and Selection
Keyboard Shortcuts
| Key | Action |
|---|---|
| ↑ / ↓ | Navigate results |
| Ctrl+j / k | Navigate results (vim-style) |
| Enter | Select current entry |
| Tab | Toggle selection (multi-select) |
| Ctrl+y | Copy entry to clipboard |
| PageUp / PageDown | Scroll preview |
| Ctrl+o | Toggle preview panel |
| Ctrl+h | Show help panel |
| Esc or Ctrl+c | Quit |
Multi-Select
Select multiple entries with Tab, then press Enter to output all selected items:
# Select multiple files, then open in editor
nvim $(tv files)
Remote Control (Channel Switching)
Press Ctrl+t to open the "remote control" - a channel picker that lets you switch between channels without restarting tv.
Ad-hoc Channels
Create temporary channels on the fly with CLI flags:
# Custom source command
tv --source-command "find . -name '*.rs'"
# With preview
tv --source-command "fd -t f" --preview-command "bat -n --color=always '{}'"
# Adjust preview size
tv --source-command "ls -la" --preview-command "file '{}'" --preview-size 70
Search Patterns
Tv supports multiple search patterns:
| Pattern | Type | Example |
|---|---|---|
foo | Fuzzy match | Matches "foo", "foobar", "folder_foo" |
'foo | Substring (exact) | Contains "foo" exactly |
^foo | Prefix | Starts with "foo" |
foo$ | Suffix | Ends with "foo" |
!foo | Negate | Doesn't match "foo" |
Combine patterns with spaces (AND logic):
# Files containing "test", starting with "src", not ending with ".bak"
test ^src !.bak$
Output and Integration
Tv outputs selected entries to stdout:
# Open selected file in editor
vim $(tv files)
# Change to selected directory
cd $(tv dirs)
# Copy selected file
cp $(tv files) /destination/
Shell Integration
To enable shell integration:
# Zsh
echo 'eval "$(tv init zsh)"' >> ~/.zshrc
# Bash
echo 'eval "$(tv init bash)"' >> ~/.bashrc
# Fish
tv init fish | source # Add to config.fish
This enables:
- Ctrl+T: Smart autocomplete based on current command
- Ctrl+R: Search shell history
Updating Channels
Get the latest community channels:
tv update-channels