Search
The suv search command opens an interactive fuzzy search TUI that lets you find, filter, and re-execute commands from your entire shell history. It supports Smart mode with frecency ranking, a detail preview pane, and a rich set of keyboard shortcuts.
Basic Usage
Launch the interactive search TUI:
suv searchStart typing to fuzzy-filter your history. Use the arrow keys to navigate, and press Enter to select and execute a command.
Command-Line Flags
You can pre-filter results before the TUI opens by passing flags:
| Flag | Description | Example |
|---|---|---|
-q / --query | Pre-fill the search query | suv search -q "docker build" |
-u / --unique | Show only unique commands (deduplicate) | suv search -u |
--after | Show commands after a date or relative time | suv search --after "3 days ago" |
--before | Show commands before a date or relative time | suv search --before "2024-01-01" |
--tag | Filter by session tag | suv search --tag deploy |
--exit-code | Filter by exit code (0 = success, 1+ = failure) | suv search --exit-code 1 |
--executor | Filter by executor (e.g., claude-code, cursor, user) | suv search --executor claude-code |
--here | Only show commands run in the current directory | suv search --here |
--field | Specify which field(s) to display or search | suv search --field command,cwd |
Keyboard Shortcuts
These shortcuts are available inside the search TUI:
| Key | Action |
|---|---|
| Type any text | Fuzzy search / filter results |
| Up / Down | Navigate through results |
| Tab | Toggle detail preview pane |
| Enter | Select and execute the highlighted command |
| Esc | Exit search without selecting |
| Ctrl+S | Toggle Smart mode (context-aware frecency ranking) |
| Ctrl+L | Toggle directory filter (show only current directory) |
| Ctrl+U | Toggle unique / deduplicate mode |
| Ctrl+F | Open filter panel (date, exit code, executor, tag) |
| Ctrl+B | Toggle bookmark on the highlighted command |
| Ctrl+N | Add or edit a note on the highlighted command |
| Ctrl+T | Tag the current session |
| Ctrl+Y | Copy the highlighted command to clipboard |
| Ctrl+D | Delete the highlighted entry |
| Ctrl+G | Go to a specific page number |
| Left / Right | Previous / next page of results |
| F1 / ? | Show help overlay with all shortcuts |
Smart Mode
Toggle Smart mode with Ctrl+S. When enabled, search results are ranked using frecency — a combination of frequency and recency:
- Commands you run often rank higher
- Recently run commands rank higher than old ones
- Commands run in the same directory as your current working directory get a significant boost
- Commands with a successful exit code (0) are slightly preferred over failed ones
Smart mode is context-aware: if you are in ~/projects/myapp, it will prioritize commands you previously ran in that directory or its subdirectories. This makes it especially useful when you work across multiple projects.
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.)
- Git branch (if applicable)
- 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.
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 --hereFilters 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.
Unique commands only
suv search -uDeduplicates results so each unique command text appears only once, showing the most recent execution.
Filter by session tag
suv search --tag deployShows only commands from sessions tagged "deploy". Tags can be applied with suv tag or Ctrl+T in the search TUI.