Fast Table Viewer for Terminal

A fast, feature-rich CSV/TSV/delimited file viewer for the command line

Demo

Table of Contents

• Features
• Installation
• Quick Install (Linux/macOS)
• Package Managers
• Build from Source
• Quick Start
• Command Line Flags
• Key Bindings
• Features in Detail
• Progressive Loading
• Data Types and Sorting
• Statistics and Visualization
• Search
• Column Filter
• Text Wrapping
• Filter Operators Guide
• Advanced Examples
• Biological Data Formats

Features

ftv brings spreadsheet-like functionality to your terminal with vim-inspired controls.

• Spreadsheet interface - Navigate and view tabular data with frozen headers
• Smart parsing - Automatically detects delimiters (CSV, TSV, custom separators)
• Progressive loading - Start viewing large files immediately while they load
• Gzip support - Read compressed files directly
• Powerful search - Find text across all cells with highlighting and regex pattern matching support
• Advanced filtering - Filter rows with complex regex queries
• Flexible sorting - Sort by any column with intelligent type detection
• Text wrapping - Wrap long cell content for better readability
• Statistics & plots - View column statistics with visual distribution charts
• Vim keybindings - Navigate naturally with h/j/k/l and more
• Mouse support - Click to select cells, scroll with mouse wheel, interact with dialogs
• Pipe support - Read from stdin for seamless integration with shell pipelines

Installation

Recommended: Install Script (Linux/macOS)

curl -sSL https://raw.githubusercontent.com/codechenx/FastTableViewer/master/install.sh | bash
sudo mv ftv /usr/local/bin/

Package Managers

macOS (homebrew)

brew tap codechenx/tap
brew install codechenx-ftv

Debian/Ubuntu (.deb)

# Download from releases page
wget https://github.com/codechenx/FastTableViewer/releases/download/v0.8.1/FastTableViewer_0.8.1_linux_amd64.deb
sudo dpkg -i FastTableViewer_*.deb

CentOS/Fedora (.rpm)

# Download from releases page
wget https://github.com/codechenx/FastTableViewer/releases/download/v0.8.1/FastTableViewer_0.8.1_linux_amd64.rpm
sudo rpm -i FastTableViewer_*.rpm

Arch Linux (AUR)

yay -S ftv-bin

Snap (Linux)

sudo snap install codechenx-tv
sudo snap alias codechenx-tv ftv

Go Install

go install github.com/codechenx/FastTableViewer@latest

Manual Download

Download pre-built binaries from releases for: - Linux (x86_64, ARM, ARM64) - macOS (Intel, Apple Silicon) - Windows (x86_64, i386)

Build from Source

Requires Go 1.21 or later:

git clone https://github.com/codechenx/FastTableViewer.git
cd FastTableViewer
go build -ldflags="-s -w" -o ftv

Quick Start

View a CSV file:

ftv data.csv

View a TSV file (tab-separated):

ftv data.tsv

Read from stdin:

cat data.csv | ftv
ps aux | ftv

Specify a custom delimiter:

ftv data.txt -s "|"

View only specific columns:

ftv data.csv --columns 1,3,5

Skip header lines (e.g., for VCF files):

ftv file.vcf --skip-prefix "##"

Command Line Flags

Syntax: ftv [FILE] [flags]

Flag	Short	Description
--separator	-s	Delimiter character (use \t for tab)
--lines	-n	Display only first N lines
--skip-prefix		Skip lines starting with prefix (comma-separated)
--skip-lines		Skip first N lines
--columns		Show only specified columns (comma-separated)
--hide-columns		Hide specified columns (comma-separated)
--freeze	-f	Freeze mode: -1=none, 0=row+col, 1=row only, 2=col only
--strict		Strict mode: fail on missing/inconsistent data
--async		Progressive rendering while loading (default: true)
--memory	-m	Memory limit in MB (0=unlimited, >0=set limit)
--help	-h	Show help
--version	-v	Show version

Examples:

# Use custom delimiter
ftv data.txt -s ","

# View only columns 1, 3, and 5
ftv data.csv --columns 1,3,5

# Skip lines starting with "#"
ftv data.txt --skip-prefix "#"

# Disable header freezing
ftv data.csv -f -1

# Disable async loading for slow systems
ftv large.csv --async=false

# Set memory limit to 500 MB
ftv large.csv --memory 500
ftv large.csv -m 500

Key Bindings

ftv uses vim-inspired keybindings for intuitive navigation.

Navigation

Key	Action
h / ←	Move left
l / →	Move right
j / ↓	Move down
k / ↑	Move up
w	Jump to next column
b	Jump to previous column
gg	Go to first row
G	Go to last row
0	Go to first column
$	Go to last column
Ctrl-d	Page down (half page)
Ctrl-u	Page up (half page)

Operations

Key	Action
/	Search
n	Next search result
N	Previous search result
Esc	Clear search highlighting / Close dialogs
f	Filter by column
r	Remove filter for current column
s	Sort ascending
S	Sort descending
t	Toggle column type (String → Number → Date)
W	Toggle text wrapping
i	Show column statistics
?	Show help
Esc	Close dialogs / clear search
q	Quit

Mouse Support

Action	Behavior
Left Click	Select cell at click position
Scroll Wheel Up	Scroll up one row
Scroll Wheel Down	Scroll down one row
Click on Buttons	Activate buttons in dialogs (Search, Filter, Stats)
Click on Checkboxes	Toggle checkboxes in forms (e.g., "Use Regex")

Note: Mouse support works in most modern terminals. If your terminal doesn't support mouse events, you can still use keyboard navigation exclusively.

Features in Detail

Progressive Loading

Start viewing large files instantly without waiting for them to fully load. The UI appears immediately and updates as data streams in.

# Default behavior - UI appears instantly
ftv huge_dataset.csv

# Disable if you prefer traditional loading
ftv huge_dataset.csv --async=false

Progress indicators: - Files show percentage: Loading... 45.2% → Loaded 1,000,000 rows - Pipes show row count: Loading... 5,234 rows → Loaded 10,000 rows - Updates at 50 FPS for smooth rendering

Memory limit: Control memory usage when viewing very large files. By default, ftv has no memory limit and will continue loading data until your system runs out of memory. You can set a limit to prevent excessive memory consumption:

# Set memory limit to 500 MB
ftv huge_dataset.csv --memory 500

# Set memory limit to 1 GB (1024 MB)
ftv huge_dataset.csv -m 1024

When the memory limit is reached, ftv will stop loading additional rows and display an error message indicating the limit. The data that was loaded before hitting the limit remains viewable and fully functional. This is useful for: - Previewing extremely large files without loading everything - Running on memory-constrained systems - Preventing out-of-memory crashes when exploring unknown files

Data Types and Sorting

tv automatically detects column types and provides intelligent sorting.

Type Detection: When loading data, ftv analyzes each column to determine if it contains strings, numbers, or dates using a 90% confidence threshold.

Manual Type Toggle: Press t to cycle through types for the current column: - String → Number → Date → String

Sorting Behavior: - Strings: Alphabetical order - Numbers: Numeric order (supports integers, floats, scientific notation, thousands separators) - Dates: Chronological order (supports ISO-8601, US format, EU format, and more)

Statistics and Visualization

Analyze your data with comprehensive statistics and modern ASCII plots.

View Statistics: Press i on any column to open an interactive statistics dialog that displays:

For numeric columns: - Summary stats: count, min, max, range, sum - Central tendency: mean, median, mode - Dispersion: standard deviation, variance - Quartiles: Q1, Q2, Q3, and IQR - Visual distribution: Histogram plot showing data distribution

For categorical/string columns: - Total values, unique values, missing/empty count - Frequency distribution with percentages - Visual distribution: Bar chart of top 15 most frequent values

Important: When column filters are active, statistics are calculated only on the filtered/visible data, not the entire dataset. The dialog title will indicate when statistics are based on filtered data and show the number of active filters.

The statistics dialog features a split-pane layout with numerical stats on the left and an ASCII graph visualization on the right, powered by asciigraph for modern, clean plots.

Search

Find text anywhere in your table with full highlighting support and powerful regex pattern matching.

How to search:

1. Press / to open the search dialog
2. Type your search term.
3. Optional: Press Tab to navigate to the checkboxes, then Space to enable:
   • Use Regex: for pattern matching with regular expressions.
   • Case Sensitive: for case-sensitive matching.
4. Press Enter to execute the search.
5. Navigate results with n (next) and N (previous).
6. Press Esc to clear highlighting.

Search Modes:

• Plain Text (default): Case-insensitive substring matching. Enable Case Sensitive for exact matching.
• Regex: Full regular expression support. By default, regex is case-insensitive. Enable Case Sensitive for case-sensitive regex matching.

Navigation in Search Dialog: - Type your search query in the text field. - Press Tab to move between the search field, checkboxes, and buttons. - Press Space to toggle a checkbox when it is focused. - Press Enter from anywhere in the form to execute the search. - Press Esc to cancel and close the dialog.

Visual feedback: - Current match: bright cyan highlight - Other matches: gray highlight - Footer shows position: Match 3/12 or regex matches 3/12

Example:

# Simple text search (case-insensitive)
/ → type "error" → Enter → n → n → N → Esc

# Case-sensitive text search
/ → check "Case Sensitive" → type "Error" → Enter

# Regex search examples
/ → check "Use Regex" → type "^ERROR" → Enter     # Lines starting with ERROR (case-insensitive)
/ → check "Use Regex" and "Case Sensitive" → type "^Error" → Enter # Lines starting with Error (case-sensitive)
/ → check "Use Regex" → type "\\d{4}-\\d{2}-\\d{2}" → Enter     # Date patterns (YYYY-MM-DD)
/ → check "Use Regex" → type "user(name)?" → Enter           # Match "user" or "username"
/ → check "Use Regex" → type "error|warning|critical" → Enter # Match any of these words
/ → check "Use Regex" → type "@.*\\.(com|org)$" → Enter       # Email domains ending in .com or .org

Common Regex Patterns:

Pattern	Description	Example Match
^start	Match at beginning of cell	^Error matches "Error: failed"
end$	Match at end of cell	\\.txt$ matches "file.txt"
\\d+	Match one or more digits	\\d+ matches "123"
\\w+@\\w+\\.\\w+	Match email pattern	Matches "user@example.com"
word1\\|word2	Match either word (OR)	success\\|complete matches either
[A-Z]+	Match uppercase letters	[A-Z]{3} matches "USA"
.*	Match any characters	start.*end matches "start...end"
\\s+	Match whitespace	\\s{2,} matches 2+ spaces

Note: For case-insensitive regex search, the (?i) flag is automatically added to your pattern. For case-sensitive regex, this flag is omitted.

Column Filter

Show only rows where specific columns match your criteria. Supports filtering on multiple columns simultaneously.

How to filter:

1. Navigate to the column you want to filter
2. Press f to open the filter dialog
3. Use the dropdown to select an operator (e.g., contains, equals, regex, >).
4. Enter the value to filter by.
5. Optionally, check the Case Sensitive box.
6. Press Enter to apply the filter.
7. Repeat on other columns to add more filters
8. Press r on a filtered column to remove that column's filter

**