Introducing histy-cli: An Interactive TUI for Shell History

•Pate Bryant

I just published histy-cli — an interactive terminal UI for browsing and searching your shell history. It supports zsh, bash, and fish out of the box, and can replace your Ctrl+R workflow entirely.

histy-cli demo

Why I Built It

The built-in Ctrl+R reverse search in most shells is clunky. You type a few characters, it shows you one match, and if that's not the one you wanted you keep hitting Ctrl+R hoping to stumble onto it. I wanted something where I could actually see my history, filter it, and pick the command I need.

How It Works

histy-cli reads your shell history file directly. It auto-detects your shell by checking $HISTFILE, then $SHELL, then falling back to checking for common history file paths (~/.zsh_history, ~/.bash_history, ~/.local/share/fish/fish_history). It parses each format correctly — including zsh's extended format with timestamps and durations, bash's #EPOCH timestamped format, and fish's YAML-like structure with multiline command support.

After parsing, entries are deduplicated by command string, keeping the most recent timestamp and accumulating a frequency count. The result is a clean, navigable list in a full-screen terminal UI built with React and Ink.

Key Features

  • Three view modes — toggle with Tab between recent (by timestamp), frequent (by count), and unique
  • Search filtering — press / to filter commands by substring match
  • Execute commands — press Enter to run the selected command directly in your shell (with your aliases and rc config loaded via -i flag)
  • Copy to clipboard — press c to copy the selected command
  • Ctrl+R integration — run histy --setup to get a shell snippet that replaces Ctrl+R with histy
  • Limit results — use -n 100 to show only the most recent N entries
  • Print mode — --print outputs the selected command to stdout instead of executing it, enabling shell integration

View Modes

The three view modes give different perspectives on your history:

  • Recent — sorted by most recent timestamp, the default view
  • Frequent — sorted by how many times you've run each command
  • Unique — deduplicated list in recent order

Toggle between them with Tab. The current mode shows in the search bar header.

Shell Integration

Run histy --setup and it prints a snippet for your detected shell. Add it to your .zshrc, .bashrc, or config.fish and Ctrl+R will launch histy instead of the built-in reverse search. When you pick a command, it gets placed on your command line buffer so you can edit it before running.

Quick Start

npx histy-cli

Or install globally:

npm install -g histy-cli
histy

The Stack

  • TypeScript with strict mode
  • React 18 + Ink 4 for the terminal UI
  • esbuild for bundling
  • Vitest for testing (106 tests, 95%+ coverage)

Check out the GitHub repo or find it on npm.