Skip to main content

Tips and Tricks

This guide covers advanced features and lesser-known capabilities.

Source Cycling​

Switch between multiple source commands within a single channel.

Configuration​

[source]
command = ["fd -t f", "fd -t f -H", "fd -t f -H -I"]
# 1. Normal files
# 2. Include hidden files
# 3. Include hidden + ignored files

Usage​

Press Ctrl+S (default) to cycle through source commands.

Use Cases​

  • Toggle hidden files on/off
  • Switch between different search depths
  • Alternate sorting methods

Preview Cycling​

Similar to source cycling, but for preview commands.

Configuration​

[preview]
command = ["bat -n --color=always '{}'", "cat '{}'", "head -50 '{}'"]

Usage​

Press Ctrl+F (default) to cycle through preview commands.

Use Cases​

  • Switch between syntax highlighting and raw view
  • Toggle between full file and head/tail
  • Different preview tools for different file types

Watch Mode​

Automatically reload the source at regular intervals.

CLI Usage​

tv files --watch 5.0  # Reload every 5 seconds

Channel Configuration​

watch is a top-level key in the channel file, so it must come before the first table:

watch = 2.0  # Reload every 2 seconds

[source]
command = "docker ps"

Use Cases​

  • Monitor running processes
  • Watch file changes
  • Track container status
  • Live log monitoring

Minimal UI​

tv defaults to a minimal, color-only UI in every viewport: no borders, no prompt, a single-line input with a dimmed result count, and a thin hairline in front of the preview. Any explicit UI flag (e.g. --input-prompt "> ", --results-border rounded) or non-default UI value from the channel [ui] config or your config.toml takes precedence over these minimal defaults.

Restoring the Classic Chrome​

tv --input-border rounded --results-border rounded --preview-border rounded --input-prompt "> "

Inline Mode​

Display tv as an inline element rather than fullscreen.

Non-fullscreen modes additionally hide the status bar and show the channel name next to the result count instead.

When the viewport is too small to fit a useful preview pane next to (or below) the results, the preview is hidden automatically (pass --show-preview or an explicit --preview-size to keep it).

Basic Inline​

tv --inline

Uses available space at the bottom of the terminal.

Fixed Height​

tv --height 15  # 15 lines tall

Fixed Width​

tv --height 15 --width 80  # 15 lines, 80 columns

Restoring the Full UI​

tv --height 15 --show-status-bar --input-border rounded --results-border rounded --preview-border rounded

Use Cases​

  • Embed in scripts without taking over the terminal
  • Quick selections without fullscreen disruption
  • Integration with tmux panes

UI Scaling​

Control how much screen space tv uses.

CLI Usage​

tv --ui-scale 80  # Use 80% of available space

Configuration​

[ui]
ui_scale = 70  # 70% of terminal

The UI is centered within the scaled area.

Frecency Sorting​

Entries are ranked by a combination of frequency and recency of use. Items you select often and recently appear higher in results.

Frecency is enabled by default and works automatically. The more you use tv, the smarter it gets at predicting what you want.

Action Picker​

Browse and execute available actions for the current entry.

Usage​

Press Ctrl+X to open the action picker, which shows all available actions for the current channel.

Expect Keys​

Define additional keys that can confirm selection, with the key name output first.

CLI Usage​

tv files --expect "ctrl-e,ctrl-v,ctrl-x"

If you press Ctrl+E, output is:

ctrl-e
selected_file.txt

Use Cases​

Useful for shell scripts that need to know how an item was selected:

output=$(tv files --expect "ctrl-e,ctrl-v")
key=$(echo "$output" | head -1)
file=$(echo "$output" | tail -1)

case "$key" in
  ctrl-e) nvim "$file" ;;
  ctrl-v) code "$file" ;;
  "") cat "$file" ;;  # Regular enter
esac

Entry Selection Strategies​

Control how tv handles single-result scenarios.

Select If Only One (--select-1)​

Auto-select and exit if there's exactly one match:

tv files --input "unique_file" --select-1

Take First (--take-1)​

Wait for loading, then auto-select the first entry:

tv files --take-1  # Always returns first result

Take First Fast (--take-1-fast)​

Return the first entry as soon as it appears (no waiting):

tv files --take-1-fast  # Fastest, returns immediately

Use Cases​

  • Script automation
  • Quick file selection
  • Default value fallback

Multiple Actions Per Key​

Bind multiple actions to a single key:

[keybindings]
ctrl-r = ["reload_source", "copy_entry_to_clipboard"]

Actions execute in sequence.

Exact/Substring Matching​

Disable fuzzy matching for exact substring search:

tv files --exact

Bare patterns then match as substrings, while the search-pattern operators (^foo, foo$, !foo, ...) keep working.

When to Use​

  • Better performance on very large datasets
  • When you know the exact string you're looking for
  • Log searching where fuzzy matching creates noise

Global vs Channel History​

Channel-Specific (Default)​

History is scoped to each channel:

tv files  # Shows files history
tv text   # Shows text history

Global History​

Share history across all channels:

tv files --global-history

Or in config:

global_history = true

Custom Input Prefill​

Start with pre-filled search text:

tv files --input "src/"

Use Cases​

  • Shell integration context
  • Scripted searches
  • Default filter patterns

Panel Toggles​

Control panel visibility at startup:

# Hide on startup (can toggle later)
tv --hide-preview
tv --hide-status-bar
tv --hide-remote

# Show on startup (overrides channel config)
tv --show-preview
tv --show-help-panel

# Disable entirely (can't toggle)
tv --no-preview
tv --no-remote
tv --no-help-panel

Layout Control​

Switch orientation at startup or runtime:

tv --layout portrait  # Preview below results
tv --layout landscape # Preview beside results (default)

Toggle with Ctrl+L at runtime.

Custom Borders and Padding​

Fine-tune panel appearance:

tv --preview-border thick --results-border none
tv --preview-padding "top=1;left=2;bottom=1;right=2"

Border options: none, plain, rounded, thick

Source Entry Delimiter​

Use custom delimiters for source output:

tv --source-command "find . -print0" --source-entry-delimiter "\0"

Useful for handling filenames with newlines or special characters.

Preview Word Wrap​

Enable word wrapping in the preview panel:

tv --preview-word-wrap

Configuration File Override​

Use a different config file:

tv --config-file ~/.config/television/minimal.toml

Custom Cable Directory​

Load channels from a different location:

tv --cable-dir ~/my-channels/

Environment Variables​

VariablePurpose
TELEVISION_CONFIGOverride config directory
TELEVISION_DATAOverride data directory
XDG_CONFIG_HOMEXDG config base
XDG_DATA_HOMEXDG data base

Combining Features​

These features compose well together:

# Watch docker containers, inline, with fast selection
tv docker-containers --watch 2.0 --inline --height 10

# File picker with preview, expect keys for different actions
tv files --preview-size 70 --expect "ctrl-e,ctrl-o" --ui-scale 80

# Quick exact search with auto-selection
tv files --input "config" --exact --select-1

Performance Tips​

  1. Use --exact for large datasets when fuzzy isn't needed
  2. --take-1-fast for fastest scripted selections
  3. --no-preview when you don't need preview
  4. Limit source output with flags like fd --max-results 10000

What's Next?​