🦇 batless

A fast, non-blocking `cat`/`bat` alternative

No pager, no highlighting, no waiting — just fast, predictable file viewing for scripts, pipelines, and terminals alike

🎯 Why batless?

bat is great, but it uses a pager and syntax highlighting — both of which are wrong for scripts, CI, and automated pipelines. cat never blocks, but it's plain-text only with no structure. batless sits between them: it never blocks, never pages, and adds exactly two things cat doesn't have — a --mode=json output for scripting and a --mode=index symbol table for a quick structural map of a file, without loading or parsing the whole thing yourself.

# Drop-in cat replacement, never blocks
batless large-file.log

# cat -n / cat -b compatible line numbering
batless -n --plain file.py

# Structured JSON for scripts
batless --mode=json file.py | jq '.total_lines'

# Symbol table — functions, structs, classes, with line ranges
batless --mode=index src/main.rs | jq '.symbols[] | "\(.line_start): \(.kind) \(.name)"'

Core guarantee: batless will NEVER wait for user input or block your pipeline.

🚀 Quick Start

Installation

Option A: Pre-built Binaries (Fastest)

# Linux (x86_64)
curl -L https://github.com/docdyhr/batless/releases/latest/download/batless-x86_64-unknown-linux-gnu.tar.gz | tar xz

# macOS (Intel)
curl -L https://github.com/docdyhr/batless/releases/latest/download/batless-x86_64-apple-darwin.tar.gz | tar xz

# macOS (Apple Silicon)
curl -L https://github.com/docdyhr/batless/releases/latest/download/batless-aarch64-apple-darwin.tar.gz | tar xz

Option B: Via Cargo

cargo install batless

Option C: Homebrew (macOS/Linux)

brew tap docdyhr/batless
brew install batless

Basic Usage

# Plain text (default mode — no pager, no highlighting)
batless file.py

# Structured JSON output
batless --mode=json file.py

# Symbol index — functions, structs, classes with line ranges
batless --mode=index src/main.rs

# Multi-file symbol index — walk a directory, one NDJSON line per file
batless --mode=index src/ | jq -c 'select(.symbol_count > 0) | {file, symbol_count}'

# Line numbers (cat -n / cat -b compatible — requires --plain or --mode=plain)
batless -n --plain file.py
batless -b --plain file.py

# Limit output
batless --max-lines=50 large-file.py
batless --max-bytes=10000 huge-file.log

# Get version info as JSON
batless --version-json

🌟 What Makes batless Different

🏆 Feature Comparison

Feature	`batless`	`bat`	`cat`
Never Blocks	✅ Guaranteed	❌ Uses pager	✅
Symbol Index (`--mode=index`)	✅	❌	❌
JSON Output	✅ First-class	❌	❌
`cat -n`/`cat -b` compatible	✅	❌	✅
Predictable in scripts/CI	✅ Same output every time	❌ Pager varies by terminal	✅
Syntax Highlighting	❌ Use `bat`	✅ Rich	❌
Interactive Human Use	❌ Not the goal	✅	✅

🚀 Core Capabilities

Non-Blocking Guarantees

🚫 NEVER uses a pager — no less, no more, no blocking
⚡ NEVER waits for input — always streams output immediately
🔄 NEVER hangs in pipes — safe for |, >, and subprocess calls
📊 ALWAYS returns quickly — bounded reads via --max-lines/--max-bytes

Language Support

🔍 Language auto-detection with manual override (--language)
🌐 Universal plain output — works with any text-based file format
🗂️ Symbol extraction for Rust, Python, JavaScript, TypeScript, and a broad set of others via a lightweight heuristic extractor (functions, classes, structs, imports)

Output Modes

📊 Three output modes: plain (default), json, index
📏 Smart limiting by lines (--max-lines) and/or bytes (--max-bytes)
🎯 Predictable behavior — identical output in terminal or pipe
✂️ Content stripping — --strip-comments/--strip-blank-lines for a denser view of a file
📦 Single <2MB binary with minimal dependencies (no bundled parser toolchains)

🚫 What batless is NOT

batless has a focused design philosophy. It intentionally does NOT provide:

Features We Don't Implement (By Design)

Feature	Why Not?	Use Instead
Pattern Search	That's `grep`'s job	`grep -rn "pattern" path/`
Arbitrary Line Ranges	Beyond our scope	`sed -n '10,50p' file`
File Globbing	Shell handles this	`batless *.py` (shell expands)
Interactive Paging	We're non-blocking	Use `bat` or `less`
Syntax Highlighting	Adds weight for no automation benefit	Use `bat`
Git Integration	Keep it simple	Use `git diff` or `bat`
File Management	Not a file browser	`ls`, `find`, `fd`
Text Editing	Viewer only	Use your editor

Common Misconceptions

❌ "batless is a drop-in replacement for bat" ✅ Reality: batless is purpose-built for scripts, CI, and automation — for interactive human reading, bat is the better tool.

❌ "batless should add grep-like search" ✅ Reality: Unix philosophy — do one thing well. Use grep for searching.

❌ "batless needs more output modes" ✅ Reality: Less is more. plain, json, and index cover what people actually use — usage data backs this up (see below).

When NOT to Use batless

👤 Interactive code review: Use bat — it has syntax highlighting and paging built for human reading
🔍 Searching code: Use grep, rg (ripgrep), or ag (silver searcher)
📝 Editing files: Use your favorite editor
📊 Complex analysis: Use language-specific tools (pylint, rust-analyzer, etc.)

Our Philosophy

Do ONE thing well: view files without ever blocking. For everything else —
highlighting, searching, editing, interactive paging — there's already a
better tool. Add features only when real usage justifies the weight.

batless's own scope decisions are usage-driven, not guesswork: --mode=plain accounts for 84% of real invocations, --mode=index for another 10% — everything else in the CLI is either free (line limits, color control) or has demonstrated real use. See docs/PHILOSOPHY_AND_SCOPE.md for the full reasoning.

📖 Usage Examples

Basic File Viewing

# Plain text (default — no pager, no highlighting, no colors unless piped to a terminal)
batless main.rs

# Force no color even in a terminal
batless --color=never main.rs

# With line numbers
batless -n --plain main.rs

# Limit output
batless --max-lines=50 large-file.py
batless --max-bytes=10000 huge-file.log

JSON & Scripting Workflows

# JSON output for downstream processing
batless --mode=json src/main.rs | jq '.total_lines'

# Pretty-printed JSON
batless --mode=json --json-pretty src/main.rs

# JSON lines as {"n": N, "text": "..."} objects instead of plain strings
batless --mode=json --with-line-numbers src/main.rs

# CI/CD context: capture a bounded slice of a failing test file
batless --mode=json --max-lines=100 failing-test.rs > context.json

# Machine-readable version metadata
batless --version-json

Symbol Index

# Symbol table for one file
batless --mode=index src/main.rs

# Walk a directory — one compact NDJSON line per file
batless --mode=index src/ | jq -c 'select(.symbol_count > 0) | {file, symbol_count}'

# Find every public function across a Rust crate
find src -name "*.rs" -exec batless --mode=index {} \; \
  | jq -c '.symbols[] | select(.kind=="function" and .visibility=="pub")'

Pipeline Integration

# Use as PAGER replacement
PAGER="batless --plain" gh pr view 42

# Process multiple files
find src -name "*.rs" -exec batless --mode=index {} \;

# Combine with grep
grep -l "TODO" src/*.py | xargs batless -n --plain

# Stream stdin
cat file.rs | batless --language=rust

🎨 Configuration

Language Detection

# Auto-detect (default)
batless file.txt

# Force specific language
batless --language=python unknown.file

# List supported languages
batless --list-languages

Content Stripping

# Strip comment-only lines
batless --strip-comments src/main.rs

# Strip blank lines
batless --strip-blank-lines src/main.rs

# Combine both — JSON output includes a compression_ratio field
batless --mode=json --strip-comments --strip-blank-lines src/main.rs | jq '.compression_ratio'

Shell Completions

batless includes built-in shell completion support for bash, zsh, fish, and PowerShell.

Bash

# Generate and install completions
batless --generate-completions bash > ~/.local/share/bash-completion/completions/batless

# Or for system-wide installation
sudo batless --generate-completions bash > /usr/share/bash-completion/completions/batless

# Then reload your shell or source the completion file
source ~/.local/share/bash-completion/completions/batless

Zsh

# Generate and install completions
batless --generate-completions zsh > ~/.zsh/completions/_batless

# Add to your ~/.zshrc (if not already present)
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

# Then reload your shell
exec zsh

Fish

# Generate and install completions
batless --generate-completions fish > ~/.config/fish/completions/batless.fish

# Completions are automatically loaded in new fish shells

PowerShell

# Generate and add to your profile
batless --generate-completions power-shell | Out-String | Invoke-Expression

# Or save to your profile for persistence
batless --generate-completions power-shell >> $PROFILE

🔧 CLI Options

Output Modes

--mode <MODE> — Output mode: plain (default), json, index
--plain — Plain text output (equivalent to --mode=plain, also used for PAGER compatibility)
--mode=json — Structured JSON output
--mode=index — Machine-readable symbol table (kind, name, line range, visibility); pass a directory to walk it and emit one NDJSON line per file

Limiting Output

--max-lines <N> — Limit output to N lines
--max-bytes <N> — Limit output to N bytes

Display Options

-n, --number — Show line numbers (cat -n compatibility; requires --plain/--mode=plain)
-b, --number-nonblank — Number non-blank lines only (cat -b compatibility; requires --plain/--mode=plain)
--language <LANG> — Force specific language detection
--color <MODE> — Color control: auto (default), always, never
--strip-ansi — Strip ANSI escape codes from output

JSON Output Options

--json-pretty — Pretty-print JSON output
--with-line-numbers — JSON lines array uses {"n": N, "text": "..."} objects instead of plain strings
--strip-comments — Strip comment-only lines from output (adds compression_ratio to JSON output)
--strip-blank-lines — Strip blank lines from output (adds compression_ratio to JSON output)

JSON Output Fields

When using --mode=json, the output includes:

Field	Type	Description
`file`	string	File path
`language`	string\|null	Detected language
`lines`	array	File lines (strings, or `{"n","text"}` objects with `--with-line-numbers`)
`mode`	string	`"json"`
`processed_lines`	integer	Number of lines actually in `lines`
`total_lines`	integer	Line count in original file
`total_lines_exact`	boolean	Whether `total_lines` covers the full file
`total_bytes`	integer	File size in bytes
`truncated`	boolean	Whether output was truncated
`truncated_by_lines`	boolean	Whether truncation was due to `--max-lines`
`truncated_by_bytes`	boolean	Whether truncation was due to `--max-bytes`
`encoding`	string	Detected encoding
`syntax_errors`	array	Encoding/processing errors encountered, if any
`compression_ratio`	number\|null	original/stripped line ratio (present only with `--strip-comments`/`--strip-blank-lines`)

When using --mode=index, the output includes:

Field	Type	Description
`file`	string	File path
`language`	string\|null	Detected language
`mode`	string	`"index"`
`symbol_count`	integer	Number of symbols found
`symbols`	array	Symbol table entries
`symbols[].kind`	string	`function`, `struct`, `class`, `impl`, `trait`, `import`, etc.
`symbols[].name`	string	Symbol identifier name
`symbols[].line_start`	integer	1-based start line
`symbols[].line_end`	integer (key omitted if unset)	1-based end line; the field exists in the schema but the current regex/heuristic extractor never populates it, so the key is always omitted from the JSON object today, not present as `null`
`symbols[].signature`	string	Declaration line, trimmed
`symbols[].visibility`	string\|null	`pub`, `private`, `export`, `local`, depending on language
`total_lines`	integer	Line count
`total_bytes`	integer	File size in bytes

Utility

--list-languages — Show all supported languages
--config <PATH> — Configuration file path (defaults to auto-discovery of .batlessrc/batless.toml)
--debug — Enable debug mode with detailed processing information
--generate-completions <SHELL> — Generate shell completions (bash, zsh, fish, power-shell)
--version — Show version information
--version-json — Machine-readable version metadata
--help — Show detailed help information

🏗️ Architecture

batless is built with:

Rust — memory safety and performance
A small, focused dependency set — clap for argument parsing, serde/serde_json for JSON, encoding_rs for encoding detection; no bundled parser toolchains
Bounded reads — --max-lines/--max-bytes cap memory use on large files
Modular design — clean separation between config parsing, file processing, and output formatting

See docs/ARCHITECTURE.md for technical details.

🤝 Contributing

We welcome contributions! Please see:

CONTRIBUTING.md - Contribution guidelines
CODE_OF_CONDUCT.md - Community standards
docs/PHILOSOPHY_AND_SCOPE.md - Project philosophy

Development Setup

# Clone repository
git clone https://github.com/docdyhr/batless.git
cd batless

# Build
cargo build

# Run tests
cargo test

# Run with example
cargo run -- src/main.rs

📊 Performance

Startup time: <5ms typical on modern hardware
Binary size: <2MB stripped (1.5MB measured on macOS arm64, down from 8.0MB before the v0.7.0 scope reduction)
Memory usage: Bounded by --max-lines/--max-bytes
Throughput: Limited only by disk I/O

Note: Performance varies by hardware. Benchmarks on typical developer workstation.

📜 License

MIT License - see LICENSE for details.

🔗 Links

Documentation: docs/
Changelog: CHANGELOG.md
Releases: GitHub Releases
Issues: GitHub Issues
Crates.io: crates.io/crates/batless

🙏 Acknowledgments

Inspired by bat by @sharkdp
Community feedback and contributions

Built for scripts, CI, and pipelines that can't afford to block

⭐ Star on GitHub | 📦 Install Now | 📖 Read the Docs

batless 0.7.0

🦇 batless

A fast, non-blocking cat/bat alternative

🎯 Why batless?

🚀 Quick Start

Installation

Option A: Pre-built Binaries (Fastest)

Option B: Via Cargo

Option C: Homebrew (macOS/Linux)

Basic Usage

🌟 What Makes batless Different

🏆 Feature Comparison

🚀 Core Capabilities

Non-Blocking Guarantees

Language Support

Output Modes

🚫 What batless is NOT

Features We Don't Implement (By Design)

Common Misconceptions

When NOT to Use batless

Our Philosophy

📖 Usage Examples

Basic File Viewing

JSON & Scripting Workflows

Symbol Index

Pipeline Integration

🎨 Configuration

Language Detection

Content Stripping

Shell Completions

Bash

Zsh

Fish

PowerShell

🔧 CLI Options

Output Modes

Limiting Output

Display Options

JSON Output Options

JSON Output Fields

Utility

🏗️ Architecture

🤝 Contributing

Development Setup

📊 Performance

📜 License

🔗 Links

🙏 Acknowledgments

A fast, non-blocking `cat`/`bat` alternative