Home screen

datui with no path opens the home screen, where you find and open a dataset: recent files, directories, cloud storage, your catalog and a catalog of public data.

datui

Ctrl+O returns here from anywhere, on the dataset you left. A filter typed before comes back selected: typing replaces it, and ~ opens the path prompt. Typing narrows the list; Esc clears the filter and selects the first dataset; Enter does what the footer names for the row. Every key is in the keyboard reference.

Open a file or directory

1. Type part of a name to narrow the list.
2. Select the row and press Enter, or double-click it.
3. To browse a directory rather than read it as one table, press →.

To type a path or URL, press ~ with the filter empty. The list shows the directory being typed, narrowed by the name after the last /, with the first name picked.

s3://, gs:// and az:// complete from names datui already knows (listed sources and prefixes, recents, the example datasets); nothing is asked of the store, so s3://noaa Tab gives s3://noaa-ghcn-pds/.

The footer names where the list is, how many rows the filter matches and the order, and at the right Enter, named for what it does on the selected row (Open, Open all, Inside, Look), what Ctrl+D does there (^D Add to catalog.toml, or ^D Forget on its own rows), ^E Docs on a catalog row, then ? keys (F1 keys once a filter is typed, since ? then types). Letters type into the filter, so q types q; Ctrl+C quits.

Sections

Folds last between runs. A heading says why its section is listed and how it stands: catalog.toml, catalog or built in for a catalog; nfs4, listing (then 1,200 so far as a slow share answers), unavailable, or first 5,000 when a listing stops there.

Recent

Recent ranks datasets by frecency, as zoxide ranks directories: an open counts four times within the hour, twice within the day, half within the week and a quarter after. A place (a directory) ranks with its best dataset, and entering it shows all its files, opened or not. The cursor starts on the dataset opened last, so Enter reopens it. Places fill up to a third of the list at first; … more in … places shows the rest.

Add to your catalog

Opening a dataset adds its directory to Recent. To keep a dataset or a directory on the home screen, press Ctrl+D on its row: it goes into catalog.toml, listed under MY DATASETS. Ctrl+D again on that row forgets it. A directory there is a row to step into.

Catalogs has the file’s keys, team catalogs and datui catalog check. [home] desktop_recents = false drops ELSEWHERE; datui never writes the desktop’s file, and lists a place there only when you enter it.

Search below the current directory

Typing narrows every section and searches below the working directory in the background. Found lists matches by their path from there.

[home.search] sets the depth, time, results and exclusions; cross_filesystems = false stays off network shares and automounts.

The details pane

What is NOAA daily weather, and who publishes it? ↓ to it: an S3 dataset from NOAA, CC0, no login, with notes on its columns. Ctrl+E shows them all.

Below about 100 columns the pane hides, and the first rows show in a strip at the bottom when the list leaves four lines free.

What a row’s label says

A row reads its name, / for a directory, two spaces, and a label: data/ 3 dirs, events/ hive, Palmer penguins csv.

A SQLite database with several tables lists them inside, a row each. A workbook, an NMEA log or an ELF file opens its first worksheet, fixes or symbols on Enter, and a file a format spec reads as several record types opens whole; → lists the record types, and Enter on one opens it alone. A Hugging Face cache lists its splits, as tables, above its files.

Names starting _ or . and _$folder$ markers are passed over, except partitions such as _date=2025-01-01.

A file not read lazily says how, dim beside its name:

The … files with no reader row, or Ctrl+A, shows files no reader takes, dimmed; [home] show_unreadable = true shows them always. Enter on a local one, or Ctrl+X on any local file, shows its bytes in the hex view. Inside a SQLite database the same row shows its internal tables.

Opening a directory

→ always goes inside. Enter does what the bar says: Open all (one table), Inside, Open (a file), or Look (find out first). Inside, the first row reads the directory as one table and says how:

On a mixed directory the pane names what is read and what is skipped. Delta, Iceberg and Hudi files are read without the transaction log, so deleted rows and old versions may show. How files combine is in Open files and directories.

Storage markers

Catalogs

A catalog is a file of named datasets, local and remote, shown as a section under its label: catalog.toml (MY DATASETS), each file in catalogs/ or listed in catalogs, and EXAMPLE DATASETS. Catalogs has the keys.

▾ MY DATASETS  5   catalog.toml  ─────────────────────────────────
  ▪ Sales                                          6.8 KB   now
  ▪ Archive/ 1 csv                                          now
  ◦ Gone missing
  ≈ Weather/ dataset
  ≈ Penguins                                      ~16.1 KB

Nothing else remote is asked for until you open or enter a dataset. Inside one, the title reads My datasets › Weather › by_year, and the pane gives its description, publisher, license, homepage, URL and login.

Documentation view

Ctrl+E on a catalog row, on a place inside one, or on a file whose format spec documents it, shows what the catalog and the spec say of it, full screen. The Info panel’s Documentation tab shows the same page for the open dataset.

What does ELEMENT hold? Ctrl+E on NOAA daily weather, ↓ to ELEMENT, Enter: TMAX is the maximum temperature in tenths of a degree C.

When a catalog lists a file a spec documents, the catalog’s description and documentation link stand. Where both note a column, the catalog’s description, unit and legend each stand when it gives one, and the spec’s fill the rest: a catalog description of price keeps the spec’s unit. The columns only the spec notes, and its record types, stay.

o opens only the page’s links (homepage, documentation, url), and only http:// and https:// ones, without a user name or password. It first asks Open <URL>? with the whole URL, a host that is not ASCII in its xn-- form; Enter opens it, Esc does not. Over SSH, or on Linux and the BSDs without DISPLAY or WAYLAND_DISPLAY, the browser would not open in front of you, so o is not offered: y copies the link.

Ctrl+E takes the place of readline’s end of line: the filter has no cursor, and is edited at its end.

Example datasets

Don’t want them? [home] hide = ["examples"] in config.toml hides them for good; Delete on the heading hides them until datui cache clear; an examples.toml of your own, in catalogs/, replaces them.

Example datasets is the catalog that comes with datui: data its publishers host, read with no login, listed after your own. datui ships none of the data; datui catalog show examples prints the catalog. Selecting its heading shows how many datasets it lists, where it comes from, and how to hide it; a heading of your own catalog shows its file and its [home] hide id.

• A web file’s row gives its format and size, ~ until measured. One under 50 MB downloads without a question; if it passes 50 MB while downloading, it stops and asks once. A URL typed at ~ is always asked about.
• Once opened, a dataset comes back under Recent by its catalog name.
• The pane gives the publisher, license and homepage; check the license before you use the data.
• NYC flights, NOAA daily weather, NYC yellow taxis and Earthquakes carry their publisher’s documentation: the pane lists what the columns mean under COLUMNS, Ctrl+E shows the whole Documentation view, and the Info panel and the inspector explain them once the data is open.
• NOAA daily weather lists two bookmarks under it, Daily highs, 2024 and Central Park, NY. Enter opens one whole; the dataset’s own row still steps inside.
• A build without the http or cloud feature leaves out the rows it cannot open.
• A catalog file named examples.toml, in catalogs/ or listed, replaces this one, even after Delete hid it; [home] hide = ["examples"] hides either, and ["examples/nyc-taxis"] one entry. An empty examples.toml hides the section.

The guides use them:

Cloud sources

CLOUD lists a row per store: logins found on this machine and connections you configure. For private storage, sign in first; for a first try with no login, use Example datasets.

▾ CLOUD  5  ──────────────────────────────────────────────────────
  ≈ Amazon S3         s3      3 buckets     datui config
  ≈ Google Cloud      gcs     4 projects    project: example-project · gcloud
  ≈ Lab MinIO         s3      1 bucket      127.0.0.1:9000 · datui config
  ≈ onprem            s3      403           minio.corp.example:9000 · datui config

Enter goes down a level: S3 source › bucket › directory › object; Google Cloud source › project › bucket › …; Azure source › account › container › …. The title shows the trail (cloud › Lab MinIO › data › 2024); Backspace goes up one level and Esc back to where you started.

Loading

The rows show at once, with the buckets an earlier run listed. Nothing is listed, and no credential command (aws, gcloud, az, a credential_process) runs, until you ask:

A slow endpoint holds up only its own row. A level lists 1,000 names at a time (3,000 so far) and stops at 5,000 (first 5,000); typing past them asks the bucket for the names the filter starts, and the heading adds + 1,907 STATION=USW*. Backspace or Esc stops a listing. Typing also matches bucket names listed before, from every source.

When listing fails, the row says why in a word and the pane gives the whole message:

Delete on a source hides it until datui cache clear. To hide one for good:

[cloud]
hide = ["gcs-default"]

Which sources appear

datui adds the logins it finds and the connections you configure; detected sources lists where each is found, its id and the discover setting. Listing a bucket does not mean its objects can be read. Catalogs, public or yours, have sections of their own.

What a cloud row shows

A listing shows name, size and modification time, and labels directories as local ones are (hive, 12 parquet, dir); job files such as _SUCCESS and empty folder objects are left out. Row counts and schemas are read when a dataset opens.

Loading

Enter shows the load’s progress; Ctrl+O cancels it. A file that fails to open shows the error here, and Esc returns to the dataset open before. A network location that does not answer reads unavailable; Ctrl+R tries again.

What datui remembers

The cache holds recent paths, how often and how lately each was opened, what was measured (counts, column names, size, modification time), query history, section folds, bucket listings, hidden cloud sources and each terminal’s last answer about its background, never the data. Your catalog is in the config directory, not the cache. Local facts are measured again when a file’s size or time changes.

datui cache clear --recents

Limits

Narrow and plain terminals

Without UTF-8, markers and borders are ASCII; display.unicode overrides the guess.

Linux packages install a desktop entry for application menus and file managers’ “Open with”; launched from a menu, datui opens here.