Search

The suv search command opens an interactive search TUI that lets you find, filter, and re-run commands from your recorded shell history. It supports literal-word matching with ranked results, a directory-aware Smart mode, a detail preview pane, and a rich set of keyboard shortcuts.

Basic Usage

Launch the interactive search TUI:

suv search

Start typing to filter your history. Use the arrow keys to navigate, and press Enter to recall a command into your prompt for review.

How Matching Works

Each word you type must appear as a literal substring in the searched field (in any order) — so results always contain what you typed. Matching uses smart case: an all-lowercase query matches any case, while including an uppercase letter makes the match case-sensitive. Results are ranked by match quality: the query as a prefix first, then as a contiguous phrase, then your words in order, then in any order. Recall and search show your own (human-typed) commands by default; press Ctrl+A to include AI-agent commands. See How results are ranked for the full ordering.

Since 0.4.0, database-level substring queries on the command field use an FTS5 trigram index. That applies to the initial query passed with -q/--query (which the Ctrl+R widget uses for any text already on your prompt). Text you type or edit inside the open TUI is matched in memory against a candidate set, as described below.

Command-Line Flags

You can pre-filter results before the TUI opens by passing flags:

Keyboard Shortcuts

These shortcuts are available inside the search TUI:

Smart Mode

Smart mode is on by default (context_boost = true under [search]). Press Ctrl+S to toggle it; the footer badge shows the mode you would switch to (Recent while Smart is on, Smart while it is off). When Smart mode is on:

• For a typed query, entries whose recorded directory is exactly your current working directory get the directory boost described below. Commands run in subdirectories or parent directories are not boosted.
• The directory column is highlighted for rows recorded in the current directory.

With an empty query, results are listed newest first in both modes. Smart mode does not weigh how often you ran a command or whether it succeeded. To see only commands from the current directory instead of boosting them, use the directory filter (Ctrl+L or --here).

How results are ranked

When you type a query in the TUI, each candidate entry is scored and sorted by these keys, in order:

1. Literal-token requirement. Entries where any typed word is missing as a literal substring are dropped, even if they would match as a fuzzy subsequence (for example, gco does not match git checkout).
2. Match tier. Query as a prefix of the field, then the query as a contiguous substring, then all words in query order, then all words in any order. A better tier always ranks first, regardless of boosts.
3. Boosted matcher score. Within a tier, entries are ordered by a fuzzy-matcher score (from the nucleo matcher) adjusted by:
   • Long-command penalty — fields longer than length_threshold characters (default 80) have their score scaled by √(threshold ÷ length).
   • Human boost — entries from a human terminal or with an unknown executor have their score raised by human_boost_percent (default 33%).
   • Directory boost — in Smart mode only, entries from exactly the current directory have their score raised by cwd_boost_percent (default 50%).
4. Interactive tiebreak. On an equal score, commands from a terminal, an IDE terminal, or an unknown executor rank above agent, bot, CI, and script commands.

Remaining ties keep the database order, newest first. The three scoring values can be changed in Settings. This ranking applies only to queries typed in the TUI; see the known limitation above for which entries are considered.

Detail Preview Pane

Press Tab to toggle the detail preview pane. When visible, it shows full metadata for the highlighted command:

• Full command text (unwrapped)
• Working directory where it was run
• Timestamp (date and time)
• Duration
• Exit code
• Executor (user, claude-code, cursor, etc.)
• Session ID
• Bookmark and note status

This is useful when multiple similar commands appear in results and you need to identify the exact one you want.

Vim Bindings

Enable vim-style modal navigation with vim_mode = true in your config (suv settings → Search tab), or in config.toml:

[search]
vim_mode = true

When enabled, the search TUI starts in Insert mode (typing searches as usual). Press Esc to switch to Normal mode for navigation:

The current mode is shown in the status bar as NORMAL or INSERT. All Ctrl+key shortcuts (filters, bookmarks, notes, etc.) work in both modes.

Examples

Find failed commands from the last 3 days

suv search --exit-code 1 --after "3 days ago"

Opens the search TUI pre-filtered to show only commands that exited with code 1, from the last 3 days.

See what an AI agent ran in the current directory

suv search --executor claude-code --here

Filters to commands executed by Claude Code in your current working directory. Useful for reviewing what an AI agent did in a project.

Search with a pre-filled query

suv search -q "git rebase"

Opens the TUI with "git rebase" already typed into the search box. The first list comes from a database query for that phrase across all recorded history, newest first.

Unique commands only

suv search -u

Deduplicates results so each unique command text appears only once, showing the most recent execution.

Filter by session tag

suv search --tag deploy

Shows only commands from sessions tagged "deploy". Tags can be applied with suv tag associate <name> or Ctrl+T in the search TUI.