Welcome

datasight lets you look at a data file without leaving the terminal. Point it at a CSV, TSV, Parquet, JSON or NDJSON file and you get a fast, scrollable table: search it, filter it, sort it, group it, chart it, and save what you end up with.

It’s for the moment when you want to see the data. Opening a spreadsheet or starting a notebook is overkill for that.

Try it in 30 seconds

datasight orders.csv

Then:

• j k h l move around, the same keys as vim.
• / searches the current column.
• f filters it, so typing > 100 keeps the rows over 100.
• ? shows every key.
• q quits.

That covers the basics. Each chapter in the sidebar covers one thing you can do, and the cheat sheet lists every key on one page.

More

• Changelog: what’s new in each release
• Contributing: building from source and sending a fix
• Roadmap: what’s planned
• Issues: report a bug or ask for a feature

Install

Download a binary

The quickest way. Grab the archive for your system from the releases page, unpack it, and put datasight somewhere on your PATH:

Note

These downloads can’t browse Azure or S3. For cloud storage, build it yourself as shown below.

Build it with cargo

You need Rust 1.75 or newer (rustup installs it).

cargo install datasight

With cloud storage

Cloud support is optional, so it’s switched on when you build:

cargo install datasight --features azure        # Azure Blob Storage
cargo install datasight --features aws          # Amazon S3
cargo install datasight --features azure,aws    # both

How to log in to each is covered in Files and the cloud.

Check it works

datasight --version

Opening data

A file

datasight sales.csv
datasight events.parquet

datasight goes by the file extension:

A file with no extension is read like piped input (below).

Other separators

Use -d for anything that isn’t a comma. It also opens files with any other extension as delimited text:

datasight -d ';' european.csv
datasight -d '|' export.psv
datasight -d '\t' data.txt

Piping data in

Leave the file name off and datasight reads whatever you pipe to it:

curl -s https://api.example.com/orders | datasight
gzip -dc sales.csv.gz | datasight
psql -c "\copy (SELECT * FROM orders) TO STDOUT CSV HEADER" | datasight

It looks at the first character to work out the format: [ means JSON, { means NDJSON, and anything else is treated as CSV. Piped tab-separated data needs -d '\t', because there’s no extension to say so.

You can also pass a command’s output as if it were a file:

datasight <(head -n 1000 huge.csv)

Dates

Text columns that hold dates are turned into real dates automatically, so they sort and chart properly. Recognised formats:

A column is only converted when every value matches. Something like 03/04/2024 could mean 3 April or 4 March. If every value in a column could be read either way, datasight leaves it as text rather than guess.

How big a file?

The whole file is loaded into memory. A 1-million-row, 42 MB CSV opens in under a tenth of a second and uses about 115 MB of RAM. After that, scrolling and filtering stay fast no matter how many rows there are.

Moving around

Getting around the table

Most keys act on the current column, the one under the cursor. Searching, filtering, sorting and the popups below all use it.

Column widths

A column never grows wider than the screen, so it can’t push everything else off to the side.

A quick look at a column

e opens a small box with the current column’s count, min, max, mean and median. Press e again to close it.

Every column at once

i opens the column inspector: one line per column with its type, how many values are filled in, how many are empty, how many are distinct, and min, max, mean and median. Move with j / k, press Enter to jump to that column in the table, or Esc to go back. In a wide file, press / and type part of a column’s name to find it.

It’s the fastest way to get to know a file you’ve never seen.

Help

? shows every key without leaving the app. q quits.

Empty cells show as ∅.

Finding rows

There are three ways to find rows. Search jumps between matches and keeps every row. Filter hides the rows that don’t match. Unique values lets you pick a value from a list.

Search: jump to a match

Press /, type, and press Enter to jump to the first row in the current column that contains it. Case doesn’t matter. n goes to the next match and N to the previous one. Esc clears the search.

Filter: keep only matching rows

Press f on a column and type a condition. The table updates as you type. Enter keeps the filter and Esc throws it away.

Some details:

• >, <, >= and <= only work on number columns.
• Plain text is case-sensitive: lap won’t find Laptop. Put (?i) in front to ignore case: (?i)lap.
• Plain text is actually a regular expression, so ^North means “starts with North”. A . matches any character, which is why 3.5 also finds 305.

Filters add up. Filter region to = North, then move to amount and filter > 500, and you see northern orders over 500. F removes every filter.

Unique values: pick from a list

u lists every distinct value in the current column, the most common first, with a count next to each. Move with j / k and press Enter to filter the table to that value. Esc closes the list.

Long list? Press / and type to narrow it, then ↑ / ↓ and Enter as before. Esc stops typing.

It’s the easy way to filter when you don’t know exactly how a value is spelled. Columns with more than 500 distinct values show the top 500, and the title says [top 500].

Sort and group

Sort

Press s on a column to sort by it. Press again to reverse, and a third time to turn it off: ▲ → ▼ → off.

To sort by more than one column, press s on another column. It becomes the tie-breaker. Sorting by region and then amount puts the regions in order and, within each region, the amounts in order. The header shows the order with ①▲ and ②▼.

S clears every sort.

Group

Grouping turns rows into a summary, like a pivot table. To get total sales per region:

1. Go to region and press b. It’s now a group key.
2. Go to amount and press a until it shows Σ (sum).
3. Press B.

You get one row per region, with a column called amount_sum.

a cycles through these:

You can group by several keys, and summarise several columns at once. Columns that are neither a key nor summarised are left out of the result.

Filters and sorts still apply once the rows are grouped. Press B again to go back to the full table.

Plots

datasight draws charts right in the terminal. A chart takes two choices: what goes up the side (Y) and what goes along the bottom (X).

Make a chart

1. Go to the column you want to chart and press p. It’s already picked as a Y column.
2. To compare, move with h / l and press Space on each extra column. Space on a picked column un-picks it.
3. Press Enter, move to the X column (a date, say), and press Enter again.

There’s a shortcut for step 3: press i instead of Enter to plot against the row number and skip choosing an X.

Esc backs out one step. Once the chart is up, Esc or p closes it.

Chart types

t switches the chart type:

• One Y column: line → bar → histogram.
• Several Y columns: line ↔ bar.

A histogram shows how a single column’s values are spread out, so it doesn’t use an X column.

Two charts, one above the other

When two series have very different scales (revenue in millions, order count in hundreds), one shared chart squashes the smaller one flat. While choosing Y columns, press 2 instead of Space on a column to put it in a second chart below the first. Both charts share the same X. 2 won’t move the top chart’s last column, and Enter needs at least one column in the top chart.

X columns that aren’t numbers

Numbers along the bottom are plotted to scale. Text and dates are placed evenly, in row order, and their values are printed sideways under the chart. When there are too many to fit, an even sample is shown. Sort by the date column first if you want the line to read left to right in time.

Copy and export

Copy to the clipboard

Your terminal does the copying, so it works over SSH too. It works in Windows Terminal, WezTerm, kitty, iTerm2, Alacritty, Ghostty and Konsole. A few need a setting turned on:

• GNOME Terminal has it switched off by default.
• tmux needs set -g set-clipboard on in your config.

If your terminal doesn’t support it, nothing happens. There’s no error.

Save the view as CSV

Press w. You’ll be asked for a file name, already filled in for you: orders.csv becomes orders.export.csv. Edit it if you like, then press Enter. Esc cancels.

You get what you see. The file has your filters, sorts and grouping applied, not the original data.

Good to know:

• The file is saved in the current directory unless you type a path. ~/exports/ and /tmp/x.csv both work.
• .csv is added if you leave it off.
• Folders that don’t exist yet are created.
• If the file already exists you get a warning first. A failed save never damages the file it was going to replace.
• Empty cells are saved as empty fields, not ∅.
• Saving always goes to your machine. When you’re viewing a file from Azure or S3, the name is suggested locally, and typing an az:// or s3:// destination is refused.

Files and the cloud

datasight browse opens a file browser beside the table. Pick a file and it opens on the right. Pick another and it replaces the first. No need to quit and restart.

datasight browse                    # the current directory
datasight browse ~/data/exports     # a local folder
datasight browse az://my-container  # Azure Blob Storage
datasight browse s3://my-bucket     # Amazon S3

Getting around

Once you Tab into an open table, every key from the rest of this manual works as usual.

Find a file

Press / and start typing. The letters only have to appear in order, so ordcsv finds orders.csv. Best matches come first, and the matching letters are highlighted.

• Lowercase ignores case. One capital letter makes the whole search case-sensitive.
• ↑ / ↓ (or ctrl+p / ctrl+n) move through the matches.
• Enter opens the highlighted match.
• ctrl+u clears what you typed. Esc brings the full list back.

What opens where

• Data files (.csv, .tsv, .parquet, .json, .ndjson, .jsonl) open as a table.
• Binary files (images, archives, executables, PDFs and the like) are greyed out and won’t open.
• Everything else (.txt, .md, .log, .yaml, files with no extension) opens in a plain text viewer.

The text viewer has its own small set of keys:

Download a cloud file

On a file in an az:// or s3:// listing, press d. You’ll be asked where to save it, with the file’s own name already filled in.

• Type a folder ending in /, like ~/Downloads/, to keep the original name.
• The full destination is shown as you type, with a warning if a file is already there.
• Missing folders are created.
• Enter saves and Esc cancels.

If a download fails, no half-written file is left behind. d does nothing on local files, since they’re already on your disk.

Cloud storage

Cloud support has to be built in. See Install. Then datasight logs in using environment variables.

Azure: either a connection string:

export AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=…;AccountKey=…"

or an account name and key:

export AZURE_STORAGE_ACCOUNT_NAME=myaccount
export AZURE_STORAGE_ACCOUNT_KEY=…

Amazon S3: the standard AWS variables:

export AWS_ACCESS_KEY_ID=…
export AWS_SECRET_ACCESS_KEY=…
export AWS_REGION=eu-west-1

Cloud files are downloaded into memory when you open them. Nothing is written to disk unless you press d.

Themes

datasight comes with 9 colour themes:

Try them live

Press T. Move with j / k and the screen changes as you go. Enter keeps the theme for next time too. Esc puts back the one you had.

Set one from the command line

datasight --theme nord sales.csv
DATASIGHT_THEME=dracula datasight sales.csv

Which one wins

If you set more than one, the first in this list is used:

1. --theme
2. DATASIGHT_THEME
3. The theme you last kept with T, saved in ~/.config/datasight/state.toml
4. mocha

Agents and scripts

datasight can be driven from another terminal. While you look at a table, an AI agent or a script can read what’s on your screen and change it: add a filter, sort a column, move the cursor, save the view. You see each change as it happens.

Note

This is new and ships in the release after v0.10.1. Until then, build from the latest code: cargo install --git https://github.com/SpollaL/datasight

Try it

Open a file in one terminal:

datasight orders.csv

and in a second terminal, run:

datasight ctl state
datasight ctl filter '{"column":"region","query":"= North"}'
datasight ctl rows '{"limit":5}'

The first command prints the columns and what’s currently applied. The second filters the table in the first terminal, and the status bar there says ✓ ctl: filter region = North. The third prints the first five rows that are left, as JSON.

Use it with Claude Code

datasight comes with a skill that teaches Claude Code how to use ctl. Install it once:

mkdir -p ~/.claude/skills/datasight
datasight --skill > ~/.claude/skills/datasight/SKILL.md

Now keep datasight open in one pane and Claude Code in another, and ask about what you’re looking at:

Which region has the most orders over 500? Filter the table so I can see them.

Claude reads the columns, filters your table, and answers from the rows it finds. The skill tells it to change your view only when you ask. Reading the table is always allowed.

Re-run the --skill command after upgrading datasight to pick up any changes.

What it can do

Filters use the same conditions as the f key: see Finding rows. For the full reference, run datasight ctl --help.

Answers and errors

A successful command prints JSON and exits with 0. Commands that change the table print the new state.

A failed command prints {"code": …, "message": …} to stderr and exits with 1, so scripts can check it. The code you’re most likely to see is busy: you were in the middle of typing (a filter, a search, a file name), and datasight won’t change the table under you. Wait a second and try again.

More than one datasight open

With one datasight running, ctl finds it by itself. With several, say which one:

datasight ctl --socket /run/user/1000/datasight/48213.sock state
# or
export DATASIGHT_SOCKET=/run/user/1000/datasight/48213.sock

Each running datasight has a socket named after its process ID, <pid>.sock. It lives in $XDG_RUNTIME_DIR/datasight/ on Linux and ~/Library/Caches/datasight/ on macOS. Only your user can open it.

Driving datasight works on Linux and macOS. On Windows, datasight runs normally but can’t be driven this way.

Cheat sheet

Every key on one page. Press ? inside datasight for the same list.

Table

Unique values and column inspector

Charts

File browser

Text viewer

Command line

datasight [FILE]                 open a file, or read from a pipe
datasight -d ';' FILE            use another separator
datasight --theme nord FILE      pick a theme
datasight browse [PATH]          file browser: a folder, az://… or s3://…
datasight ctl METHOD [JSON]      drive a running datasight (see Agents and scripts)
datasight --skill                print the Claude Code skill
datasight --version

Troubleshooting

The screen looks garbled

Your terminal may not handle colours or box-drawing characters. Use a modern terminal (kitty, Alacritty, WezTerm, iTerm2, Windows Terminal) and make sure TERM is set to xterm-256color.

“Unsupported file format”

datasight doesn’t recognise the extension. Give it the separator and it reads the file as delimited text: datasight -d ',' export.dat.

Everything is in one column

The separator is wrong. Tell datasight which one it is: -d ';' for semicolons, -d '\t' for tabs. Piped tab-separated data always needs -d '\t'.

A date column stayed as text

Either some values don’t match a supported format, or every value works as both day-first and month-first (03/04/2024), and datasight won’t guess which one you meant.

> 100 says it only works on numbers

>, <, >= and <= need a number column. For text, use = value, != value, or just type part of the value.

A filter finds nothing, but the value is there

Filters are case-sensitive: north won’t match North. Use (?i)north, or press u and pick the value from the list.

The unique values list seems short

It shows the 500 most common values. The title says [top 500] when there are more.

Columns are too narrow or too wide

= fits every column. _ fits the current one, and pressing it again resets it. - and + adjust by hand. A column is never fitted wider than the screen. For very long values, widen the terminal and fit again.

Copy does nothing

Your terminal doesn’t support clipboard access, or has it switched off. See Copy and export.

az:// or s3:// says it needs a feature

Downloaded binaries don’t include cloud support. Build it in: cargo install datasight --features azure,aws.

datasight ctl says “no running datasight found”

Nothing is open to drive, or it’s running as another user. Start datasight in another terminal first. On Windows, ctl isn’t available.

A Parquet file won’t open

Make sure it’s a valid Parquet file. Encrypted Parquet isn’t supported.

Still stuck?

Open an issue with your datasight version (datasight --version), your OS and terminal, and a small file that shows the problem.