tess(1)

NAME
tess - A less-style terminal pager.

SYNOPSIS
tess [--blocks] [-S|--chop-long-lines] [--clipboard] [--content-type] [--dim] [--display] [--examples] [--exit-follow-on-close] [--filter] [-f|--follow] [--follow-name] [--follow-suspend-on-motion] [--format] [--from-clipboard] [--grep] [--head] [--header] [--hex] [--hex-group] [-i|--ignore-case] [-I|--IGNORE-CASE] [--image-protocol] [--image-width] [--incsearch] [-N|--LINE-NUMBERS] [--list-formats] [--live] [--manual] [--mouse] [--no-animate] [--no-color] [-G|--no-hilite-search] [--no-image] [-X|--no-init] [--no-preprocess] [--or-filter] [--or-grep] [--or-group] [-o|--output] [--preprocess] [--prettify] [--prompt] [--prompt-style] [-e|--quit-at-eof] [-E|--QUIT-AT-EOF] [-F|--quit-if-one-screen] [-K|--quit-on-intr] [-r|--raw-control-chars] [-R|--RAW-CONTROL-CHARS] [--record-start] [--rscroll] [--scroll-lock] [-#|--shift] [--split] [-s|--squeeze-blank-lines] [-J|--status-column] [--status-style] [--stdout] [--tab-width] [-x|--tabs] [-t|--tag] [-T|--tag-file] [--tail] [--to-clipboard] [--truecolor] [--wheel-lines] [-z|--window] [--wordwrap] [-h|--help] [-V|--version] [FILES]

DESCRIPTION
A less-style terminal pager.

OPTIONS

--blocks
    Render images with Unicode half-blocks (▀, fg=top pixel, bg=bottom pixel) for ~2× vertical detail instead of the default character ramp

-S, --chop-long-lines
    Chop long lines instead of wrapping

--clipboard
    Enable interactive clipboard yank: `:yank` copies the current line to the system clipboard. Bind a key via `clipboard-yank-line` in keys.toml (unbound by default, so it never clobbers existing keys)

--content-type <TYPE>
    Force the content type for `--prettify` (otherwise auto-detected from the filename extension and the first bytes). Values: `auto`, `raw`, `json`, `yaml`, `toml`, `xml`, `html`, `csv`. Setting this implies `--prettify` (unless the value is `raw`/`auto`)

--dim
    With `--filter`, dim non-matching lines instead of hiding them. Keeps surrounding context visible

--display <TEMPLATE>
    Render each parsed line through this template instead of showing the raw line. Syntax: `<fieldname>` placeholders, `\<` for literal `<`, `\\` for literal `\`. Example: `--display '[<time>] <status> <msg>'`. Overrides the format's `display` key (if set). Requires `--format`. Search still matches against the raw line

--examples
    Print a curated list of usage examples and exit

--exit-follow-on-close
    In follow mode with piped stdin, exit when the upstream writer closes the pipe. Default behavior (off): tess remains open on the captured content after stdin EOF. Mirrors `less --exit-follow-on-close`

--filter <FIELD<op>VALUE>
    Filter visible lines by parsed field. Repeatable; multiple filters AND. Operators: `=` (exact), `!=` (exact ≠), `~` (regex), `!~` (regex ≠), `<`, `<=`, `>`, `>=` (numeric if both sides parse as numbers, else lexicographic). Examples: `--filter status=500`, `--filter ip~^10\.`, `--filter 'status>=500'` (quote `<` and `>` to avoid shell redirection). Requires `--format`

-f, --follow
    Follow mode: keep watching the source for new bytes (like `tail -f`). Jumps to the bottom on startup. Toggle with Shift-F at runtime

--follow-name
    Follow the file by path rather than by descriptor (matches `tail -F` / `less --follow-name`). `tess` already does this — rotation and truncation are detected on every poll and the source re-opens by path (since 0.25.0). This flag is accepted for compatibility and currently has no behavioral effect

--follow-suspend-on-motion
    In follow mode, any user motion (scroll, page, goto-line) suspends following. Re-engage with Shift-F. Default off: today's behavior (movement keeps follow on; auto-scroll suspended while the viewport is not at bottom). Matches `less +F` semantics when enabled

--format <NAME>
    Apply a named log format (built-in or user-defined in ~/.config/tess/formats.toml). Required by `--filter`

--from-clipboard
    Use the system clipboard contents as input (like `pbpaste | tess`). Mutually exclusive with file arguments and piped stdin

--grep <PATTERN>
    Filter visible lines by regex against the raw line. Repeatable; multiple `--grep` arguments AND. Works on any input — no `--format` required. Composes with `--filter` (both must match) and with `--dim` (non-matches stay visible but faded). Example: `--grep error --grep '^\['`

--head <N>
    Show only the first N lines of the source. Mutually exclusive with --tail

--header <L[,C]>
    Pin the top L source lines (and the left C columns, when horizontal scroll is supported) at the top of the viewport. Form: `L` or `L,C`. Default `0,0` (off). Mirrors `less --header`. Runtime adjustment: `:header L [C]`

--hex
    Render the source as an xxd-style hex dump instead of byte-faithful text. 16 bytes per row, offset prefix, ASCII gutter. Mutually exclusive with parsing- and rendering-oriented flags

--hex-group <N> [default: 4]
    Hex characters per group in `--hex` mode. One of 2, 4, 8, 16, 32 (default 4, matching `xxd`). 32 means the whole row as a single group with no spacing between hex pairs. Requires `--hex`. Can be changed at runtime with `:hex N`

-i, --ignore-case
    Smart-case search. `/`, `?`, `--grep`, and `--filter`'s `~` / `!~` operators match case-insensitively unless the pattern contains an uppercase character. Mirrors `less -i` / ripgrep / vim smartcase. Mutually exclusive with `-I`. Runtime toggle: `:case`

-I, --IGNORE-CASE
    Force case-insensitive search regardless of pattern case. Mirrors `less -I`. Mutually exclusive with `-i`

--image-protocol <MODE> [default: auto]
    Image rendering protocol: `auto` (detect terminal graphics support and fall back to ASCII), `kitty`, `sixel`, or `ascii`

--image-width <N>
    Target width in columns for image rendering. Defaults to the terminal width interactively, or 80 when exporting to a file/stdout

--incsearch
    Incremental search: in the `/`/`?` prompt, jump to and highlight the first match as you type (from where the prompt opened). Esc restores the original position; Enter commits. Default off. Mirrors `less --incsearch`. Runtime toggle: `:incsearch`

-N, --LINE-NUMBERS
    Show line numbers

--list-formats
    Print available log formats and their named fields, then exit

--live
    Live mode: re-read the file when its on-disk content changes (mtime, size, or inode). Use this for files rewritten in place — source files being edited, files saved by an editor or AI agent. Different from `--follow` (which watches for *appended* bytes); the two are mutually exclusive. Press `R` inside the pager to force a reload

--manual
    Print the full user manual and exit

--mouse
    Enable mouse capture: click rows in the file picker / help overlay, and scrollwheel scrolls the body. Trade-off: most terminals disable their native text selection while mouse capture is on

--no-animate
    Show only the first frame of an animated image (GIF/APNG/WebP) instead of playing it. No effect on static images or non-image input

--no-color
    Show raw control bytes as `^X` glyphs (pre-0.18 default). Disables SGR / OSC interpretation. Honoured also by the `NO_COLOR` environment variable (any non-empty value) and `CLICOLOR=0`

-G, --no-hilite-search
    Disable search-match highlighting by default. Search still navigates (`n` / `N` jump to matches); the visual reverse-video highlight is suppressed. Runtime toggle: `:hlsearch` / `:nohlsearch`. Mirrors `less -G`

--no-image
    Treat a detected image file as raw/normal text instead of rendering it as ASCII art. Has no effect on non-image inputs

-X, --no-init
    Don't enter the alt-screen on startup. Content remains in terminal scrollback after exit. Crucial for piped use and debugging. Mirrors `less -X` / `--no-init`

--no-preprocess
    Ignore $LESSOPEN. Useful when LESSOPEN is exported but not wanted for one invocation

--or-filter <FIELD<op>VALUE>
    OR-filter: a field condition where matching ANY condition in its OR-group is enough (the group is satisfied). AND'd with the required --filter/--grep. Joins the group set by the most recent --or-group, or `default` if none. Requires --format. Repeatable

--or-grep <PATTERN>
    OR-grep: a raw-regex condition where matching ANY condition in its OR-group is enough. Works on any input. Joins the group set by the most recent --or-group, or `default` if none. Repeatable

--or-group <NAME>
    Open an OR-group: subsequent --or-filter/--or-grep join NAME until the next --or-group. Conditions before any marker form the `default` group. Every non-empty group must have ≥1 match (groups are AND'd). Repeatable

-o, --output <FILE>
    Non-interactive batch mode: apply --filter / --grep / --head / --tail / --prettify to the source and write the resulting raw bytes to FILE, then exit. Use `-` for stdout (`--stdout` is a synonym). Skips the alt-screen and raw mode entirely. With `--follow`, doesn't exit — keeps appending matching new bytes to FILE as they arrive (Ctrl-C to stop). Not compatible with `--live`

--preprocess <CMD>
    Pipe the source file through this command before rendering. Must start with `|`; `%s` is substituted with the file path. Example: `--preprocess '|pdftotext %s -'`. Overrides $LESSOPEN

--prettify
    Pretty-print structured content (JSON, YAML, TOML, XML, HTML, CSV). Detects the type from the filename extension or the first bytes; use `--content-type=NAME` to override. Static files only — not allowed with `--follow`, `--live`, or `--filter`. Toggle interactively with `Shift-P`; force a type with `-P` then a letter (j/y/t/x/h/c)

--prompt <TEMPLATE>
    Replace the hardcoded status format with a templated string. Uses the same `<field>` syntax as `--display`. Available fields: label, top, bottom, total, pct, rec-top, rec-bottom, rec-total, rec-block, wrap-offset, format-tag, filter-tag, grep-tag, hide-tag, search-tag, pretty-tag, live-tag, follow-tag. Per-format default can be set via `prompt = '...'` in formats.toml. Mutually exclusive with --hex

--prompt-style <SPEC> [default: ]
    Style for `--prompt` output (and per-format `prompt_style`). Same grammar as `--status-style`. Default: empty (no extra styling on top of what the prompt template itself emits)

-e, --quit-at-eof
    Quit when the user tries to scroll forward past end-of-file for the second time. Mirrors `less -e`. Mutually exclusive with `-E`

-E, --QUIT-AT-EOF
    Quit the first time end-of-file is reached. Mirrors `less -E`

-F, --quit-if-one-screen
    Exit immediately (without paging) if the entire source fits on one screen. Ignored with piped stdin in follow mode. Mirrors `less -F`

-K, --quit-on-intr
    Accepted for `less` compatibility. tess always exits on Ctrl-C (Ctrl-C → Command::Quit in the input table), so this flag is a no-op. Provided so existing `less` invocations work unchanged

-r, --raw-control-chars
    Pass every byte to the terminal raw, including cursor moves and non-SGR escape sequences. Risky: scroll math may break on long lines. Less-style -r. Mutually exclusive with --no-color

-R, --RAW-CONTROL-CHARS
    Accept `less -R`: interpret SGR/OSC color escapes, strip other control sequences — which is tess's default. Provided for drop-in `less -R` compatibility. Distinct from `-r` (full raw) and `--no-color`

--record-start <REGEX>
    Treat lines matching REGEX as record boundaries. Lines that don't match are joined to the preceding record. Affects search, filter, grep, and the status line — all operate on whole records when set. Overrides the active --format's record_start if both are present. Without --format, this is the only way to enable records mode for plain text. Example: --record-start '^\['

--rscroll <CHAR> [default: >]
    Character to show at the right edge of a chopped line (`-S` chop mode) indicating "more content right". Default `>`. Pass an empty string to disable. Mirrors `less --rscroll=c`

--scroll-lock
    Start with the split panes scroll-locked together (relative offset captured at launch). Only meaningful with --split; ignored otherwise

-#, --shift <N>
    Column count for the ←/→ horizontal-scroll commands (default: half screen). `0` keeps the half-screen default. Mirrors `less -#`/`--shift`

--split
    Open two files side by side in a vertical split (needs ≥2 file args; with one file, opens a second view of it). Interactive only. Runtime: `:vsplit`

-s, --squeeze-blank-lines
    Collapse runs of two or more consecutive blank lines into a single blank line at display time. Real line numbers, search, and tag jumps are unaffected (they reference the original count). Mirrors `less -s`

-J, --status-column
    Show a 1-column status gutter at the far left: a mark letter on marked lines, else `*` on lines containing a current-search match. Stays fixed under horizontal scroll. No-op in --hex/-r/image modes. Mirrors `less -J`

--status-style <SPEC> [default: reverse]
    Style for the status row. Comma-separated tokens: `bold`, `dim`, `italic`, `underline`, `reverse`, `fg=COLOR`, `bg=COLOR`. COLOR is a named color (`black`..`white`, optional `bright-` prefix), `#RRGGBB`, or an indexed value (0–255). Empty string disables theming. Default: `reverse`

--stdout
    Synonym for `--output -`: write the batch-mode output to stdout

--tab-width <TAB_WIDTH> [default: 8]
    Tab stop width (default 8)

-x, --tabs <LIST>
    Tab stops as a comma-separated column list, e.g. `-x4,8,16`. A single value is equivalent to `--tab-width`. With multiple values, tabs advance to the next listed column; past the last stop the final interval repeats. Overrides `--tab-width`. Mirrors `less -x`

-t, --tag <NAME>
    Jump to the tag NAME at startup (requires a tags file)

-T, --tag-file <PATH>
    Path to the tags file. Default: walk up from CWD looking for `tags`

--tail <N>
    Show only the last N lines of the source. For files this skips most of the index work — useful for huge logs. Combine with `-f` for `tail -f`. Mutually exclusive with --head. Streaming stdin is not supported

--to-clipboard
    Batch sink: apply filters/head/tail/prettify and copy the result to the system clipboard, then exit. Mutually exclusive with -o/--stdout

--truecolor <MODE> [default: auto]
    Truecolor (24-bit RGB) handling. `auto` (default) checks `$COLORTERM` and downsamples when truecolor isn't advertised; `never` always downsamples to the 256-color palette; `always` passes RGB through regardless of terminal capability

--wheel-lines <N>
    Body lines scrolled per mouse-wheel notch under `--mouse` (default 3)

-z, --window <N>
    PageDown / PageUp step size in lines. Default: full screen height (body rows). Half-page commands always advance by half the screen regardless. Mirrors `less -zn` / `--window=n`

--wordwrap
    In wrap mode, break lines on whitespace boundaries instead of mid-character when possible. Falls back to mid-character break when no whitespace fits in the row. Mirrors `less --wordwrap`

-h, --help
    Print help

-V, --version
    Print version

[FILES]
    Files to view (only the first is opened in MVP)

VERSION
v0.42.0