BATTY(1)

NAME
batty - a cat clone with syntax highlighting, git diff markers, and a TUI

SYNOPSIS
batty [OPTIONS] [FILE...]

DESCRIPTION
batty is a from-scratch Rust reimplementation of bat(1) — cat(1) with syntax highlighting, git diff markers in the gutter, pager integration, relative line numbers, Markdown rendering, tail/follow mode, and an interactive TUI. Targets macOS and Linux.

When no FILE is given, batty reads from standard input. Pass - explicitly to mix stdin into a multi-file invocation.

OPTIONS
Flags are listed alphabetically by long name. Short forms ride along.

--color=WHEN
    When to use colors: always, auto (default), never.

--decorations=WHEN
    Decoration mode override: always, auto (default), never. never collapses to plain output like --plain.

-d, --diff
    Show git diff markers vs HEAD in the gutter.

--diff-context=N
    Lines of context for diff (default 2). Currently parsed but not yet used to filter output.

--encoding=ENC
    Input file encoding: auto (default; UTF-8 with ISO-8859-1 fallback), utf-8, iso-8859-1 / latin1.

--examples
    Print colorized, copy-pasteable usage examples and exit. Complements --help.

-f, --follow
    Tail mode: tail(1)-style follow with syntax highlighting. Single file only; no stdin.

--gutter
    Show the left-side gutter (line numbers, diff markers, grid bar). Cancels --no-gutter from config.

-H, --highlight-line N
    Highlight line N. Repeatable. The first occurrence acts as the cursor reference for relative line numbering in static mode.

-i, --interactive
    Enter the interactive TUI. See INTERACTIVE MODE below.

-l, --language LANG
    Set the language for syntax highlighting (overrides extension detection).

--line-numbers=STYLE
    Line numbering style: absolute (default), relative (vim-style, centered on the cursor).

--line-range=RANGE
    Display only the specified range. Forms: A:B, :B (head), A: (tail-to-end), N (single line).

-L, --list-languages
    List supported languages and exit.

--list-themes
    List supported themes and exit.

--live
    Live mode: alt-screen TUI that re-renders the file whenever its contents change. Same keybindings as --interactive. Single file only; no stdin. Mutually exclusive with --interactive and --follow.

-m, --markdown
    Render Markdown files instead of showing the raw source. Works for any file.

--markdown-on-extension
    Auto-render .md / .markdown / .mdown / .mkd files as Markdown; leave other files raw. Lower priority than --markdown and --no-markdown.

--no-follow
    Disable follow mode. Overrides follow = true in the config.

--no-gutter
    Hide the gutter regardless of --style. Header / rule / snip stay on — a cleaner-reading preset less aggressive than --plain.

--no-interactive
    Disable interactive mode. Overrides interactive = true in the config.

--no-live
    Disable live mode. Overrides live = true in the config file.

--no-markdown
    Disable Markdown rendering. Overrides markdown = true in the config.

-n, --number
    Show line numbers (equivalent to --style=numbers).

--paging=WHEN
    When to use the pager: always, auto (default), never. never also disables interactive mode.

-p, --plain
    Plain output (no decorations, equivalent to --style=plain).

-A, --show-all
    Show non-printable characters.

--style=COMPONENTS
    Comma-separated style components: full, plain, numbers, grid, header, rule, changes, snip. Default full.

--tabs=N
    Tab width (default 4).

--tail-lines=N
    Number of trailing lines to show in follow mode (default 10).

--theme=NAME
    Set the color theme. Use --list-themes to see available names.

--top-pad=N
    Reserve N rows at the top of the screen in interactive mode. Useful for terminals (e.g. Warp) that overlay UI on the alternate screen's top rows.

--wrap=MODE
    Wrap mode: never, character, word, auto (default). auto wraps when stdout is a terminal and behaves as never otherwise, so piped output keeps its original line structure. character always wraps at the terminal-width boundary. word breaks at whitespace boundaries instead, best for prose; words longer than the wrap width fall back to character -style breaks so output never overflows. Forced to never in interactive mode.

-h, --help
    Print short help.

-V, --version
    Print version and exit.

INTERACTIVE MODE
Launched with -i/--interactive. Single file only.

Keybindings:

    j / k
        Scroll one line down / up.

    g / G
        Jump to top / bottom.

    Ctrl-d / u
        Half-page down / up.

    PgDn / PgUp
        Full page.

    m   Toggle Markdown rendering (raw ←> rendered). Available when the file is Markdown by extension or --markdown is set.

    n   Toggle the gutter.

    + / -
        Adjust --top-pad live (useful for terminals with shifting top overlays).

    q   Quit.

The same keybindings apply in --live mode; the only difference is that the file is automatically reloaded when its contents change on disk.

CONFIG
batty reads a TOML config at ~/.config/batty/config.toml (XDG-style, even on macOS). Top-level keys map to CLI long-flag names with hyphens preserved. Example:

    theme            = "Dracula"
    tabs             = 2
    top-pad          = 2
    line-numbers     = "relative"
    markdown-on-extension = true
    highlight-line   = [10, 20]
    live             = false       # autoreload TUI

Boolean true maps to the flag being set; arrays expand to repeated --key=item flags; unknown keys are forwarded to clap, which rejects them with a clear error.

Override the config path with BATTY_CONFIG_PATH (set to /dev/null to opt out entirely).

ENVIRONMENT

BATTY_CONFIG_PATH
    Override the default config file path. Set to /dev/null for hermetic runs (used by the integration tests).

PAGER, LESS
    Honored by the pager step. The default pager is less with -FRX.

NO_COLOR
    When set, batty disables colored output (same as --color=never).

FILES

~/.config/batty/config.toml
    Default config file.

EXIT STATUS

0   Success.

1   Error (file not found, decode failure on --encoding=utf-8, invalid flag combination, etc.).

SEE ALSO
bat(1), cat(1), less(1), tail(1).

AUTHORS
Written by Thomas Björk. See the AUTHORS section of the repository https://github.com/codedeviate/batty for the full contributor list.

LICENSE
MIT. See the LICENSE file in the source distribution.