Skip to content
FrostyBee Docs LogoFrostyBee Docs

Terminal UI

vaste-tui is the terminal app for Vaste. It opens one large file per run, in Text view, Hex view, the table view, or the NDJSON view, and reads it with the same engine as the desktop app. Like the desktop app, it never changes the file it opens. Use it over SSH, on a server without a desktop, or when you prefer the keyboard.

Build and install

Section titled “Build and install”

vaste-tui is built from the Vaste source code. There are no ready-made downloads, and no license is needed: the terminal app is free. You need Rust 1.93 or later.

In the root of the Vaste source, run either command:

Terminal window
# Build the program into target/release/vaste-tui
cargo build --release -p vaste-tui


# Or build it and install it on your PATH
cargo install --path apps/tui

The program builds on Linux, macOS, and Windows.

Run vaste-tui

Section titled “Run vaste-tui”

Pass the file to open:

Terminal window
vaste-tui app.log
Option What it does
--index-dir <INDEX_DIR> Index storage directory. See TUI configuration.
--entry <ENTRY> Entry to open when FILE is a zip archive with several files
--delimiter <DELIMITER> Read the file as CSV with this delimiter (a character or tab); also turns a plaintext file into a table
--quote <QUOTE> CSV quote character (default: detected, usually ")
--header <HEADER> Whether the first CSV record is a header row: auto, yes, or no. The default is auto.
-h, --help Print the help
  • A file name is required, and vaste-tui opens one file at a time. It cannot read from standard input, and it has no --version option.
  • If the file cannot be opened, vaste-tui prints Failed to open file: followed by the reason and exits with code 1. Errors with a compressed file have their own messages, such as Decompression failed: followed by the reason. A wrong option exits with code 2.
  • --delimiter and --quote take one printable character. --quote and --header apply only to CSV and TSV files, or to a text file you open with --delimiter. The CSV options are not saved: pass them each time.

To quit, press q or Ctrl + C.

Compressed files

Section titled “Compressed files”

vaste-tui opens gzip, zstd, xz, bzip2, and zip files, recognized by their first bytes. It decompresses the file before the screen opens, and shows the progress in the terminal, for example Decompressing app.log.gz [gz] 45% (512 MiB written). It reuses a copy it has already decompressed. See Compressed files.

A zip archive with one file opens that file. For an archive with several files, pass the name with --entry. Without it, vaste-tui lists the names in its error: app.zip has several entries; pass --entry <name>: a.log, b.log.

The screen

Section titled “The screen”

The screen has three parts:

  • The title line shows the file name, the compressed format if any, for example [gz], and the current view on the right: [TEXT], [HEX], [CSV], or [JSON].
  • The content area shows the file. After a search in Text or Hex view, the lower part lists the matches.
  • The footer shows your position, the file size, the encoding, and the line endings, for example L 1,204/250,000 and 12.4 MB | UTF-8 | LF. (detected) after the encoding means vaste-tui guessed it from the content. While a search, a count, or a reload runs, the footer shows its progress instead.

Press ? to show the help screen, and any key to close it. The help screen does not scroll and needs a tall terminal, about 75 rows, to show all of it. The full list of keys is in TUI keybindings. vaste-tui does not use the mouse.

Compared with the desktop app

Section titled “Compared with the desktop app”
In vaste-tui Desktop app only
Text, Hex, table, and NDJSON views SQL queries, Find in files, saved filters, pinned results
Literal, regular expression, and hex byte search, with grep mode Combining searches, capture groups, copying and exporting matches
Go to a line, a byte offset, or a time; count matches; file statistics The scratchpad, highlighters, the time histogram
Marks for the current session Bookmarks kept between sessions, sessions, recent files
Encoding choice, saved per file The NDJSON Schema panel, data quality, hex analysis tools
Table sort, one column filter, column statistics Several column filters, column layout, Record view, the CSV dialect dialog
Auto reload and compressed files Settings dialog, themes, custom shortcuts, mouse and clipboard

The two apps keep their indexes and settings in separate folders, unless you point the index_dir setting at the desktop app’s indexes/ folder to share indexes. See TUI configuration.

Next steps

Section titled “Next steps”