VisiData CLI Skill
VisiData is a terminal multiplexer for investigating and manipulating tabular data. It reads CSV, TSV, JSON, Excel, SQLite, and dozens of other formats, and provides vim-like keybindings for interactive exploration.
High-Value Patterns
- Convert unfamiliar datasets between formats with
vd -b input -o output.
- Generate
.vdj command logs for guided interactive exploration or repeatable cleanup.
- Triage unknown data: inspect columns, set types, find nulls/outliers, summarize categories.
- Clean messy CSV/Excel exports with quoting, Unicode, dates, currencies, and mixed types.
- Join, diff, append, or reconcile two datasets interactively before saving.
- Use
vd in pipelines when a human should visually select/filter rows.
Installation
macOS (Homebrew — recommended)
brew install visidata
All platforms (pip)
Requires Python 3.8+.
pip3 install visidata
If vd is not found after pip install, check that ~/.local/bin (Linux) or the Python scripts directory is on $PATH.
Conda
conda install --channel conda-forge visidata
Linux (distribution package managers)
# Debian/Ubuntu
sudo apt install visidata
# Fedora
sudo dnf install visidata
# Arch Linux
sudo pacman -S visidata
# NixOS
nix-env -i visidata
Windows
Use Windows Subsystem for Linux (WSL) or MSYS2's Python, then install via pip inside that environment.
Upgrade
pip install --upgrade visidata
# or
brew upgrade visidata
Verify
vd --version
CLI Usage
Basic launch
vd data.csv # open a file
vd a.tsv b.json c.xlsx # open multiple files (last one displayed on top)
vd . # open DirSheet to browse filesystem
Piping data
ps aux | vd # pipe into vd
vd - < data.tsv # redirect from file
cat query.sql | mysql | vd # chain with other tools
Key CLI flags
| Flag |
Purpose |
-f TYPE |
Force input filetype (e.g. -f csv, -f sqlite, -f fixed) |
-o FILE |
Output to FILE (extension determines format) |
-of TYPE |
Force output filetype |
-b |
Batch mode (non-interactive, for scripts) |
-p FILE.vdj |
Replay a command log |
-d |
Dump format (output to stdout on quit) |
--header N |
Number of header rows (default: 1; use --header=0 for headerless) |
-f "" |
Reset to extension-based detection after a -f flag |
Important: -f applies to all subsequent input paths on the command line, not just the one immediately following. Use -f "" to reset.
Format conversion
vd -b input.csv -o output.json # convert csv → json
vd -b data.fixed -of csv -o data.txt # force output format
Not all loader formats support saving. Check vd --help or the formats reference for supported output types.
Core Keybindings
Navigation
| Key |
Action |
↑↓←→ / PgUp/PgDn / Home/End |
Move cursor |
h j k l |
Move one cell (vim-style) |
gh gj gk gl |
Move to edge of sheet |
< / > |
Jump to next different value in column |
{ / } |
Jump to next/prev selected row |
Ctrl+^ |
Jump to previous sheet |
q |
Quit current sheet |
gq |
Quit all sheets (global quit) |
Search
| Key |
Action |
/ / ? |
Search current column (regex, forward/back) |
g/ / g? |
Search all visible columns |
n / N |
Next/previous match |
z/ / z? |
Search by Python expression |
Selection
| Key |
Action |
s / t / u |
Select / toggle / unselect current row |
gs / gt / gu |
Select / toggle / unselect all rows |
| / \ |
Select/unselect rows matching regex in current column |
g| / g\ |
Select/unselect rows matching regex in any visible column |
z| / z\ |
Select/unselect by Python expression |
, |
Select rows matching current cell |
g, |
Select rows matching entire current row |
Sorting
| Key |
Action |
[ / ] |
Sort ascending/descending by current column |
g[ / g] |
Sort by all key columns |
z[ / z] |
Add to existing sort criteria |
! |
Toggle key column status |
Column Operations
| Key |
Action |
- |
Hide current column |
gv |
Unhide all columns |
H / L |
Slide column left/right |
^ |
Rename column |
! |
Pin column as key column |
Shift+C |
Open Columns sheet |
Column Types
| Key |
Type |
~ |
string |
# |
int |
% |
float |
$ |
currency |
@ |
date |
z# |
vlen (value length) |
z~ |
anytype |
Editing
| Key |
Action |
e |
Edit current cell |
ge TEXT |
Set current column for selected rows to TEXT |
g* regex TAB subst |
Find/replace in selected rows |
g= expr |
Evaluate Python expression on selected rows |
Enter |
Accept input |
Ctrl+C / Esc |
Abort input |
Ctrl+O |
Open cell in external $EDITOR |
Derived Columns
| Key |
Action |
= |
Create column from Python expression (name=expr or just expr) |
g= |
Set column value for selected rows |
z= |
Set column value for current row |
Available variables in expressions: column names (typed value), vd, sheet, col, row, curcol, cursorCol, currow.
Aggregation & Grouping
| Key |
Action |
+ agg |
Add aggregator to current column |
z+ agg |
Show aggregator result for selected rows |
Shift+F |
Open frequency table for current column |
g Shift+F |
Frequency table by all key columns |
Shift+I |
Open describe sheet (descriptive stats) |
Shift+W |
Open pivot table |
Available aggregators: min, max, avg/mean, mode, median, sum, distinct, count, stdev, list, q3/q4/q5/q10.
Sheets
| Key |
Action |
Shift+S |
Open Sheets sheet (all opened sheets) |
z Shift+S |
Open Sheets stack (active sheets) |
o |
Open a file from within vd |
Enter |
Jump to sheet from Sheets sheet |
Joining & Combining
| Key |
Action |
& |
Open join chooser (inner, outer, full, diff, extend, merge, append, concat) |
" |
Open duplicate sheet with selected rows |
g" |
Duplicate sheet with all rows, selected ones stay selected |
z" |
Copy of sheet with copies of selected rows (no source link) |
Saving
| Key |
Action |
Ctrl+S |
Save current sheet |
Shift+D |
Open CommandLog sheet |
Ctrl+D |
Save command log |
Graphs
| Key |
Action |
. |
Graph current column (requires numeric x-axis set with !) |
g. |
Graph all visible numeric columns |
Other
| Key |
Action |
Shift+A |
New blank sheet |
za / gza N |
Add 1 / N blank columns |
a / ga N |
Add 1 / N blank rows |
v |
Toggle multi-line rows |
Ctrl+H |
Help / Commands sheet |
Shift+O |
Options sheet |
z Ctrl+S |
Save options to config |
Space longname |
Execute command by longname |
Typical Workflows
Explore → filter → save
vd data.csv
! on a column to mark it as key/ or z| to filter/select rows" to open a duplicate with selected rowsCtrl+S to save
Format conversion (batch)
vd -b input.csv -o output.json
vd -b data.fixed -of tsv -o data.txt
Batch replay a command log
vd -b -p transform.vdj input.csv -o output.csv
The .vdj file records keystrokes. To make it file-independent, remove the open-file line and blank all "sheet" values in the .vdj.
Pipe processing
ps aux | vd | awk '{print $2}' # visually inspect processes, then print selected PIDs
mysql < query.sql | vd | awk '{print $1}' # manually filter/query results
Use Ctrl+Q to output current sheet to stdout (keeps top sheet on stack). Use q/gq to quit without outputting.
Gotchas
q vs gq: q quits the current sheet. gq quits all sheets. If you just want to output data via pipe, use Ctrl+Q.-f scope: -f csv data.txt applies csv parsing to ALL subsequent input paths until you reset with -f "".- File format inference: Unknown extensions load as Text sheets. Use
-f to force a loader.
- Column types matter: Sorting/filtering numerical data requires setting the column type first (
# for int, % for float, @ for date). Default is anytype (string-like).
- Edits propagate: Changes to rows on derived sheets (duplicates, frequency tables) propagate back to source sheets. Use
z" for an independent copy.
-b is non-interactive: Batch mode disables all UI. Use for scripted conversion and replay only.- Selection is global: Selecting rows on a frequency table also selects them on the source sheet.
Ctrl+Q vs q in pipes: Ctrl+Q outputs the current sheet to stdout. q/gq outputs nothing.- No undo for some operations: Column hiding, sort changes, and some edits cannot be undone.
Reference Files
For deep dives on specific topics, load the relevant reference from references/. See references/INDEX.md for a topic-grouped index.
cbrunnkvist