This page provides a comprehensive reference for all command-line options, subcommands, and arguments supported by bat. It covers the syntax, behavior, and relationships between different CLI parameters defined via clap.
bat utilizes a clap-based CLI definition src/bin/bat/clap_app.rs21-37 It supports two primary command patterns: the main file processing command and the cache management subcommand.
Sources: src/bin/bat/clap_app.rs21-49 src/bin/bat/clap_app.rs271-324 doc/long-help.txt3-4 doc/short-help.txt3-4
| Option | Short | Description | Example |
|---|---|---|---|
[FILE]... | - | Input files to process, or - for stdin src/bin/bat/clap_app.rs41-49 | bat file1.txt file2.py |
--file-name <name> | - | Override displayed filename for stdin input src/bin/bat/clap_app.rs152-164 | cat data.json | bat --file-name data.json |
--map-syntax <glob:syntax> | -m | Map file patterns to syntax definitions src/bin/bat/clap_app.rs217-230 | --map-syntax '*.build:Python' |
--ignored-suffix <suffix> | - | Ignore file extension suffixes src/bin/bat/clap_app.rs231-240 | --ignored-suffix .dev |
Sources: src/bin/bat/clap_app.rs41-49 src/bin/bat/clap_app.rs152-164 src/bin/bat/clap_app.rs217-240
Sources: src/bin/bat/clap_app.rs111-133 src/bin/bat/clap_app.rs241-270
| Option | Short | Values | Description |
|---|---|---|---|
--language <language> | -l | Name or extension | Explicitly set syntax highlighting language src/bin/bat/clap_app.rs111-122 |
--fallback-syntax <syntax> | - | Name or extension | Fallback for undetected syntaxes src/bin/bat/clap_app.rs124-133 |
--theme <theme> | - | Theme name | Set color theme src/bin/bat/clap_app.rs241-255 |
--theme-dark <theme> | - | Theme name | Theme for dark backgrounds src/bin/bat/clap_app.rs264-270 |
--theme-light <theme> | - | Theme name | Theme for light backgrounds src/bin/bat/clap_app.rs257-263 |
--list-languages | -L | - | Display supported languages src/bin/bat/clap_app.rs415-420 |
--list-themes | - | - | Display available themes src/bin/bat/clap_app.rs409-414 |
| Option | Short | Values | Description |
|---|---|---|---|
--style <components> | - | Comma-separated | Configure displayed elements src/bin/bat/clap_app.rs374-389 |
--plain | -p | - | Alias for --style=plain src/bin/bat/clap_app.rs97-109 |
--number | -n | - | Alias for --style=numbers src/bin/bat/clap_app.rs188-195 |
--show-all | -A | - | Show non-printable characters src/bin/bat/clap_app.rs51-63 |
--nonprintable-notation | - | caret, unicode | Notation style src/bin/bat/clap_app.rs65-79 |
Sources: src/bin/bat/clap_app.rs51-109 src/bin/bat/clap_app.rs374-389
| Option | Short | Values | Description |
|---|---|---|---|
--color <when> | - | auto, never, always | Colorized output src/bin/bat/clap_app.rs197-205 |
--decorations <when> | - | auto, never, always | Show decorations src/bin/bat/clap_app.rs207-215 |
--paging <when> | - | auto, never, always | Pager behavior src/bin/bat/clap_app.rs336-344 |
--pager <command> | - | Command string | Specify pager src/bin/bat/clap_app.rs346-353 |
--wrap <mode> | - | auto, never, character, word | Text wrapping src/bin/bat/clap_app.rs175-186 |
--terminal-width <width> | - | Number/Offset | Override width src/bin/bat/clap_app.rs326-334 |
Sources: src/bin/bat/clap_app.rs175-215 src/bin/bat/clap_app.rs326-353
The cache subcommand manages the binary syntax and theme assets src/bin/bat/clap_app.rs271-324
Sources: src/bin/bat/clap_app.rs284-315 assets/completions/bat.zsh.in8-21
| Option | Short | Description |
|---|---|---|
--build | -b | Initialize or update the syntax/theme cache src/bin/bat/clap_app.rs284-291 |
--clear | -c | Remove the cached syntax definitions and themes src/bin/bat/clap_app.rs292-299 |
--source <dir> | - | Directory to load syntaxes and themes from src/bin/bat/clap_app.rs300-307 |
--target <dir> | - | Directory to store the cached set in src/bin/bat/clap_app.rs308-315 |
bat features a unique help system where it uses its own highlighting engine to render the help text.
-h. Renders cmd.render_help() src/bin/bat/app.rs167--help. Renders cmd.render_long_help() src/bin/bat/app.rs168display_help function creates a virtual Input from the clap-generated help text and passes it to the Controller with language: Some("help") src/bin/bat/app.rs171-194Sources: src/bin/bat/app.rs104-136 src/bin/bat/app.rs145-197
bat includes a --completion <SHELL> flag to generate completion scripts for various shells src/bin/bat/clap_app.rs421-429
| Shell | Script Template |
|---|---|
| Bash | assets/completions/bat.bash.in |
| Zsh | assets/completions/bat.zsh.in |
| Fish | assets/completions/bat.fish.in |
| PowerShell | assets/completions/_bat.ps1.in |
The Zsh completion script includes dynamic logic to fetch languages and themes directly from the bat binary using --list-languages and --list-themes assets/completions/bat.zsh.in91-115
Sources: src/bin/bat/clap_app.rs421-429 assets/completions/bat.zsh.in1-134 assets/completions/bat.bash.in52-256 assets/completions/bat.fish.in143-220