tess(1)

NAME
tess - A less-style terminal pager.

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

DESCRIPTION
A less-style terminal pager.

OPTIONS

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

-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`

--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]`

--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`

-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`

--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

--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`

--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

--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-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`

--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 '^\['`

-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`

-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`

-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`

-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

-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`

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

--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`

-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-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`

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

-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

-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

--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

--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`

--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)

--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 '^\['

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

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

-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

-h, --help
    Print help

-V, --version
    Print version

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

VERSION
v0.30.0