github/television
1
1
Fork 0
mirror of https://github.com/alexpasmantier/television.git synced 2025-07-29 06:11:37 +00:00
Code Issues 1 Packages Projects Releases Wiki Activity
television/man/tv.1
Alex Pasmantier 098f3f4fe4
feat: ansi-styled results with --ansi or corresponding channel option (#655) 
# Examples:
## ripgrep
```toml
[metadata]
name = "text"
description = "A channel to find and select text from files"
requirements = ["rg", "bat"]

[source]
command = "rg . --no-heading --line-number --colors 'match:fg:white' --colors 'path:fg:blue' --color=always"
ansi = true
output = "{strip_ansi|split:\\::..2}"

[preview]
command = "bat -n --color=always '{strip_ansi|split:\\::0}'"
env = { BAT_THEME = "ansi" }
offset = '{strip_ansi|split:\::1}'

[ui]
preview_panel = { header = '{strip_ansi|split:\::..2}' }
```

<img width="2880" height="1620" alt="Screenshot From 2025-07-19
20-56-53"
src="https://github.com/user-attachments/assets/67055fd1-d03e-4c4b-ad82-dbc3ba8c80d4"
/>

## git-log

```toml
[metadata]
name = "git-log"
description = "A channel to select from git log entries"
requirements = ["git", "delta"]

[source]
command = "git log --graph --pretty=format:'%C(yellow)%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --color=always"
output = "{strip_ansi|split: :1}"
ansi = true

[preview]
command = "git show -p --stat --pretty=fuller --color=always '{strip_ansi|split: :1}' | delta"
```

<img width="2880" height="1620" alt="Screenshot From 2025-07-19
19-17-15"
src="https://github.com/user-attachments/assets/be97ff35-8a35-4d26-ad14-afd5ece3fed6"
/>
2025-07-19 22:52:12 +02:00

389 lines
16 KiB
Groff
Raw Blame History

.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.TH television 1 "television 0.12.5"
.SH NAME
television \- Cross\-platform, fast and extensible general purpose fuzzy finder TUI.
.SH SYNOPSIS
\fBtelevision\fR [\fB\-\-preview\-offset\fR] [\fB\-\-no\-preview\fR] [\fB\-\-hide\-preview\fR] [\fB\-\-show\-preview\fR] [\fB\-\-no\-status\-bar\fR] [\fB\-\-hide\-status\-bar\fR] [\fB\-\-show\-status\-bar\fR] [\fB\-t\fR|\fB\-\-tick\-rate\fR] [\fB\-\-watch\fR] [\fB\-k\fR|\fB\-\-keybindings\fR] [\fB\-i\fR|\fB\-\-input\fR] [\fB\-\-input\-header\fR] [\fB\-\-input\-prompt\fR] [\fB\-\-preview\-header\fR] [\fB\-\-preview\-footer\fR] [\fB\-s\fR|\fB\-\-source\-command\fR] [\fB\-\-ansi\fR] [\fB\-\-source\-display\fR] [\fB\-\-source\-output\fR] [\fB\-\-source\-entry\-delimiter\fR] [\fB\-p\fR|\fB\-\-preview\-command\fR] [\fB\-\-layout\fR] [\fB\-\-autocomplete\-prompt\fR] [\fB\-\-exact\fR] [\fB\-\-select\-1\fR] [\fB\-\-take\-1\fR] [\fB\-\-take\-1\-fast\fR] [\fB\-\-no\-remote\fR] [\fB\-\-hide\-remote\fR] [\fB\-\-show\-remote\fR] [\fB\-\-no\-help\-panel\fR] [\fB\-\-hide\-help\-panel\fR] [\fB\-\-show\-help\-panel\fR] [\fB\-\-ui\-scale\fR] [\fB\-\-preview\-size\fR] [\fB\-\-config\-file\fR] [\fB\-\-cable\-dir\fR] [\fB\-\-global\-history\fR] [\fB\-\-height\fR] [\fB\-\-width\fR] [\fB\-\-inline\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fICHANNEL\fR] [\fIPATH\fR] [\fIsubcommands\fR]
.SH DESCRIPTION
Cross\-platform, fast and extensible general purpose fuzzy finder TUI.
.SH OPTIONS
.TP
\fB\-\-preview\-offset\fR=\fISTRING\fR
A preview line number offset template to use to scroll the preview to for each
entry.
When a channel is specified: This overrides the offset defined in the channel prototype.
When no channel is specified: This flag requires \-\-preview\-command to be set.
This template uses the same syntax as the `preview` option and will be formatted
using the currently selected entry.
.TP
\fB\-\-no\-preview\fR
Disable the preview panel entirely on startup.
This flag works identically in both channel mode and ad\-hoc mode.
When set, no preview panel will be shown regardless of channel configuration
or preview\-related flags.
.TP
\fB\-\-hide\-preview\fR
Hide the preview panel on startup (only works if feature is enabled).
This flag works identically in both channel mode and ad\-hoc mode.
The preview remains functional and can be toggled visible later.
.TP
\fB\-\-show\-preview\fR
Show the preview panel on startup (only works if feature is enabled).
This flag works identically in both channel mode and ad\-hoc mode.
This overrides any channel configuration that might have it disabled.
.TP
\fB\-\-no\-status\-bar\fR
Disable the status bar on startup.
This flag works identically in both channel mode and ad\-hoc mode.
.TP
\fB\-\-hide\-status\-bar\fR
Hide the status bar on startup (only works if feature is enabled).
This flag works identically in both channel mode and ad\-hoc mode.
.TP
\fB\-\-show\-status\-bar\fR
Show the status bar on startup (only works if feature is enabled).
This flag works identically in both channel mode and ad\-hoc mode.
.TP
\fB\-t\fR, \fB\-\-tick\-rate\fR=\fIFLOAT\fR
The application\*(Aqs tick rate.
This flag works identically in both channel mode and ad\-hoc mode.
The tick rate is the number of times the application will update per
second. This can be used to control responsiveness and CPU usage on
very slow machines or very fast ones but the default should be a good
compromise for most users.
.TP
\fB\-\-watch\fR=\fIFLOAT\fR
Watch mode: reload the source command every N seconds.
When a channel is specified: Overrides the watch interval defined in the channel prototype.
When no channel is specified: Sets the watch interval for the ad\-hoc channel.
When set to a positive number, the application will automatically
reload the source command at the specified interval. This is useful
for monitoring changing data sources. Set to 0 to disable (default).
.TP
\fB\-k\fR, \fB\-\-keybindings\fR=\fISTRING\fR
Keybindings to override the default keybindings.
This flag works identically in both channel mode and ad\-hoc mode.
This can be used to override the default keybindings with a custom subset.
The keybindings are specified as a semicolon separated list of keybinding
expressions using the configuration file formalism.
Example: `tv \-\-keybindings=\*(Aqquit="esc";select_next_entry=["down","ctrl\-j"]\*(Aq`
.TP
\fB\-i\fR, \fB\-\-input\fR=\fISTRING\fR
Input text to pass to the channel to prefill the prompt.
This flag works identically in both channel mode and ad\-hoc mode.
This can be used to provide a default value for the prompt upon
startup.
.TP
\fB\-\-input\-header\fR=\fISTRING\fR
Input field header template.
When a channel is specified: Overrides the input header defined in the channel prototype.
When no channel is specified: Sets the input header for the ad\-hoc channel.
The given value is parsed as a `MultiTemplate`. It is evaluated against
the current channel name and the resulting text is shown as the input
field title. Defaults to the current channel name when omitted.
.TP
\fB\-\-input\-prompt\fR=\fISTRING\fR
Input prompt string
When a channel is specified: This overrides the prompt defined in the channel prototype.
When no channel is specified: Sets the input prompt for the ad\-hoc channel.
The given value is used as the prompt string shown before the input field.
Defaults to ">" when omitted.
.TP
\fB\-\-preview\-header\fR=\fISTRING\fR
Preview header template
When a channel is specified: This overrides the header defined in the channel prototype.
When no channel is specified: This flag requires \-\-preview\-command to be set.
The given value is parsed as a `MultiTemplate`. It is evaluated for every
entry and its result is displayed above the preview panel.
.TP
\fB\-\-preview\-footer\fR=\fISTRING\fR
Preview footer template
When a channel is specified: This overrides the footer defined in the channel prototype.
When no channel is specified: This flag requires \-\-preview\-command to be set.
The given value is parsed as a `MultiTemplate`. It is evaluated for every
entry and its result is displayed below the preview panel.
.TP
\fB\-s\fR, \fB\-\-source\-command\fR=\fISTRING\fR
Source command to use for the current channel.
When a channel is specified: This overrides the command defined in the channel prototype.
When no channel is specified: This creates an ad\-hoc channel with the given command.
Example: `find . \-name \*(Aq*.rs\*(Aq`
.TP
\fB\-\-ansi\fR
Whether tv should extract and parse ANSI style codes from the source command output.
This is useful when the source command outputs colored text or other ANSI styles and you
want `tv` to preserve them in the UI. It does come with a slight performance cost but
which should go mostly unnoticed for typical human interaction workloads.
Example: `tv \-\-source\-command="echo \-e \*(Aq\\x1b[31mRed\\x1b[0m\*(Aq" \-\-ansi`
.TP
\fB\-\-source\-display\fR=\fISTRING\fR
Source display template to use for the current channel.
When a channel is specified: This overrides the display template defined in the channel prototype.
When no channel is specified: This flag requires \-\-source\-command to be set.
The template is used to format each entry in the results list.
Example: `{split:/:\-1}` (show only the last path segment)
.TP
\fB\-\-source\-output\fR=\fISTRING\fR
Source output template to use for the current channel.
When a channel is specified: This overrides the output template defined in the channel prototype.
When no channel is specified: This flag requires \-\-source\-command to be set.
The template is used to format the final output when an entry is selected.
Example: "{}" (output the full entry)
.TP
\fB\-\-source\-entry\-delimiter\fR=\fISTRING\fR
The delimiter byte to use for splitting the source\*(Aqs command output into entries.
This can be useful when the source command outputs multiline entries and you want to
rely on another delimiter to split the entries such a null byte or a custom character.
.TP
\fB\-p\fR, \fB\-\-preview\-command\fR=\fISTRING\fR
Preview command to use for the current channel.
When a channel is specified: This overrides the preview command defined in the channel prototype.
When no channel is specified: This enables preview functionality for the ad\-hoc channel.
Example: "cat {}" (where {} will be replaced with the entry)
Parts of the entry can be extracted positionally using the `delimiter`
option.
Example: "echo {0} {1}" will split the entry by the delimiter and pass
the first two fields to the command.
.TP
\fB\-\-layout\fR=\fILAYOUT\fR
Layout orientation for the UI.
When a channel is specified: Overrides the layout/orientation defined in the channel prototype.
When no channel is specified: Sets the layout orientation for the ad\-hoc channel.
Options are "landscape" or "portrait".
.br
.br
[\fIpossible values: \fRlandscape, portrait]
.TP
\fB\-\-autocomplete\-prompt\fR=\fISTRING\fR
Try to guess the channel from the provided input prompt.
This flag automatically selects channel mode by guessing the appropriate channel.
It conflicts with manually specifying a channel since it determines the channel automatically.
This can be used to automatically select a channel based on the input
prompt by using the `shell_integration` mapping in the configuration
file.
.TP
\fB\-\-exact\fR
Use substring matching instead of fuzzy matching.
This flag works identically in both channel mode and ad\-hoc mode.
This will use substring matching instead of fuzzy matching when
searching for entries. This is useful when the user wants to search for
an exact match instead of a fuzzy match e.g. to improve performance.
.TP
\fB\-\-select\-1\fR
Automatically select and output the first entry if there is only one
entry.
This flag works identically in both channel mode and ad\-hoc mode.
Note that most channels stream entries asynchronously which means that
knowing if there\*(Aqs only one entry will require waiting for the channel
to finish loading first.
For most channels and workloads this shouldn\*(Aqt be a problem since the
loading times are usually very short and will go unnoticed by the user.
.TP
\fB\-\-take\-1\fR
Take the first entry from the list after the channel has finished loading.
This flag works identically in both channel mode and ad\-hoc mode.
This will wait for the channel to finish loading all entries and then
automatically select and output the first entry. Unlike `select_1`, this
will always take the first entry regardless of how many entries are available.
.TP
\fB\-\-take\-1\-fast\fR
Take the first entry from the list as soon as it becomes available.
This flag works identically in both channel mode and ad\-hoc mode.
This will immediately select and output the first entry as soon as it
appears in the results, without waiting for the channel to finish loading.
This is the fastest option when you just want the first result.
.TP
\fB\-\-no\-remote\fR
Disable the remote control.
This flag works identically in both channel mode and ad\-hoc mode.
This will disable the remote control panel and associated actions
entirely. This is useful when the remote control is not needed or
when the user wants `tv` to run in single\-channel mode (e.g. when
using it as a file picker for a script or embedding it in a larger
application).
.TP
\fB\-\-hide\-remote\fR
Hide the remote control on startup (only works if feature is enabled).
This flag works identically in both channel mode and ad\-hoc mode.
The remote control remains functional and can be toggled visible later.
.TP
\fB\-\-show\-remote\fR
Show the remote control on startup (only works if feature is enabled).
This flag works identically in both channel mode and ad\-hoc mode.
.TP
\fB\-\-no\-help\-panel\fR
Disable the help panel entirely on startup.
This flag works identically in both channel mode and ad\-hoc mode.
When set, no help panel will be shown regardless of channel configuration
or help panel\-related flags.
.TP
\fB\-\-hide\-help\-panel\fR
Hide the help panel on startup (only works if feature is enabled).
This flag works identically in both channel mode and ad\-hoc mode.
The help panel remains functional and can be toggled visible later.
.TP
\fB\-\-show\-help\-panel\fR
Show the help panel on startup (only works if feature is enabled).
This flag works identically in both channel mode and ad\-hoc mode.
This overrides any channel configuration that might have it disabled.
.TP
\fB\-\-ui\-scale\fR=\fIINTEGER\fR
Change the display size in relation to the available area.
This flag works identically in both channel mode and ad\-hoc mode.
This will crop the UI to a centered rectangle of the specified
percentage of the available area.
.TP
\fB\-\-preview\-size\fR=\fIINTEGER\fR
Percentage of the screen to allocate to the preview panel (1\-99).
When a channel is specified: This overrides any `preview_size` defined in configuration files or channel prototypes.
When no channel is specified: This flag requires \-\-preview\-command to be set.
.TP
\fB\-\-config\-file\fR=\fIPATH\fR
Provide a custom configuration file to use.
This flag works identically in both channel mode and ad\-hoc mode.
.TP
\fB\-\-cable\-dir\fR=\fIPATH\fR
Provide a custom cable directory to use.
This flag works identically in both channel mode and ad\-hoc mode.
.TP
\fB\-\-global\-history\fR
Use global history instead of channel\-specific history.
This flag only works in channel mode.
When enabled, history navigation will show entries from all channels.
When disabled (default), history navigation is scoped to the current channel.
.TP
\fB\-\-height\fR=\fIINTEGER\fR
Height in lines for non\-fullscreen mode.
This flag works identically in both channel mode and ad\-hoc mode.
When specified, the picker will be displayed as a non\-fullscreen interface.
.TP
\fB\-\-width\fR=\fIINTEGER\fR
Width in columns for non\-fullscreen mode.
This flag can only be used in combination with \-\-inline or \-\-height.
When specified, the picker will be constrained to the specified width.
.TP
\fB\-\-inline\fR
Use all available empty space at the bottom of the terminal as an inline interface.
This flag works identically in both channel mode and ad\-hoc mode.
When enabled, the picker will be displayed as an inline interface that uses
all available empty space at the bottom of the terminal. If there is insufficient
space to meet the minimum height the terminal will scroll.
.TP
\fB\-h\fR, \fB\-\-help\fR
Print help (see a summary with \*(Aq\-h\*(Aq)
.TP
\fB\-V\fR, \fB\-\-version\fR
Print version
.TP
[\fICHANNEL\fR]
Which channel shall we watch?
When specified: The application operates in \*(Aqchannel mode\*(Aq where the selected
channel provides the base configuration, and CLI flags act as overrides.
When omitted: The application operates in \*(Aqad\-hoc mode\*(Aq where you must provide
at least \-\-source\-command to create a custom channel. In this mode, preview
and source flags have stricter validation rules.
A list of the available channels can be displayed using the
`list\-channels` command. The channel can also be changed from within
the application.
.TP
[\fIPATH\fR]
The working directory to start the application in.
This flag works identically in both channel mode and ad\-hoc mode.
This can be used to specify a different working directory for the
application to start in. This is useful when the application is
started from a different directory than the one the user wants to
interact with.
.SH SUBCOMMANDS
.TP
television\-list\-channels(1)
Lists the available channels
.TP
television\-init(1)
Initializes shell completion ("tv init zsh")
.TP
television\-update\-channels(1)
Downloads the latest collection of default channel prototypes from github and saves them to the local configuration directory
.TP
television\-help(1)
Print this message or the help of the given subcommand(s)
.SH VERSION
v0.12.5
.SH AUTHORS
Alexandre Pasmantier <alex.pasmant@gmail.com>
Reference in New Issue View Git Blame Copy Permalink