Usage

Setup

Quick setup (recommended)

ukrop setup

This will:

1. Import shell history — commands, directories and SSH hosts from your shell history and ~/.ssh/config
2. Add shell integration — appends eval "$(ukrop init zsh)" (or bash/fish equivalent) to your rc file
3. Enable the u shortcut — via a shell alias

Each step asks for confirmation, so you can skip anything. On first run with an empty database, ukrop will suggest running setup automatically.

To re-run setup (e.g. after declining on first run):

ukrop setup --force

Manual setup

Add to your shell config:

# ~/.zshrc
eval "$(ukrop init zsh)"

# ~/.bashrc
eval "$(ukrop init bash)"

# ~/.config/fish/config.fish
ukrop init fish | source

# PowerShell profile (run `echo $PROFILE` to find it)
Invoke-Expression (& { (ukrop init powershell | Out-String) })

Restart your shell or source the config file.

The u shortcut is included automatically in the init script as a shell alias. A standalone u binary is also installed, supporting u --help and u --version even without shell integration:

u              # jump to directory (active panel: cd)
u run          # run a command (active panel: run)
u ssh          # connect to SSH host (active panel: ssh)
u add ~/projects/myapp
u --help
u --version

What shell integration installs

• A precmd/prompt hook that records the current directory on every prompt
• A preexec hook that captures each command and its start time; the precmd hook then records it with exit code, working directory, and execution duration via ukrop hook-cmd
• A shell wrapper function ukrop that handles cd, run, and ssh output
• A Ctrl+R binding that opens the TUI with the run panel active; supports all result types (cd/run/ssh)
• An alias u=ukrop for quick access

Commands

Jump to a directory

ukrop          # opens TUI with cd panel active
ukrop cd       # same as above

Run a command from history

ukrop run      # opens TUI with run panel active

Or press Ctrl+R in your shell.

Search with pre-filled query

ukrop search docker    # opens TUI with run panel active, "docker" in search box
u search git push      # same via shortcut

All subcommands (cd, run, ssh) also accept an optional query:

u cd projects          # opens cd panel with "projects" pre-filled
u run make             # opens run panel with "make" pre-filled
u ssh prod             # opens ssh panel with "prod" pre-filled

SSH to a host

ukrop ssh      # opens TUI with ssh panel active

Imports hosts from ~/.ssh/config and shell history (ssh commands you've run).

Import shell history

Populate the database from your existing shell history (also done by ukrop setup):

ukrop import        # auto-detect shell type
ukrop import zsh
ukrop import bash
ukrop import fish
ukrop import powershell

Reset database and reimport

rm "$HOME/Library/Application Support/ukrop/ukrop.db"   # macOS
rm ~/.local/share/ukrop/ukrop.db                        # Linux

ukrop import

Manage entries

ukrop add ~/projects/myapp    # add favorite directory (validates path exists)
ukrop forget ~/old/path       # remove from database
ukrop list                    # show tracked directories with scores
ukrop list --commands         # show tracked commands with scores
ukrop list --ssh              # show tracked SSH hosts with scores
ukrop list --json             # JSON output for scripting

Export / import database

Back up and restore the entire database (all directories, commands and SSH hosts with exact scores and timestamps):

ukrop export --file backup.jsonl     # export to JSONL file
ukrop export                         # export to stdout (pipe-friendly)
ukrop import --file backup.jsonl     # restore from JSONL (replaces current data)

JSONL format — one JSON object per line with a type field (directory, command, ssh_host).

Typical workflow for recording a demo video:

ukrop export --file ~/my-data.jsonl  # save personal data
ukrop demo                           # generate demo data
# ... record video ...
ukrop import --file ~/my-data.jsonl  # restore personal data

Generate demo data

ukrop demo      # replaces database with realistic sample data

Generates ~25 directories, ~40 commands and ~10 SSH hosts with varied scores, timestamps and favorites — useful for screencasts and testing.

Shell integration output

ukrop init zsh          # print zsh integration script
ukrop init bash         # print bash integration script
ukrop init fish         # print fish integration script
ukrop init powershell   # print PowerShell integration script

TUI Layout

All three panels are shown simultaneously with a shared search bar at the top:

• Left column (25% width): cd panel (top 75%) and ssh panel (bottom 25%)
• Right column (75% width): run panel (full height)
• The active panel is highlighted with a green border; inactive panels are dimmed
• Search filters all three panels simultaneously with matched characters highlighted (cyan + underline)

Active panel defaults

Keyboard shortcuts

Press F1 inside the TUI to show the help overlay with all shortcuts.

Terminal compatibility

Some shortcuts depend on the terminal emulator's ability to send extended key sequences:

• Shift+Enter requires the kitty keyboard protocol. Terminals that support it include kitty, WezTerm, foot, and Ghostty. Standard terminals (macOS Terminal.app, older GNOME Terminal) send the same byte for Enter and Shift+Enter, so the shortcut has no effect there. Use F5 as a universal alternative for paste-to-terminal, or F2 to open the in-TUI command editor.
• Ctrl+Delete requires the terminal to send a CSI modifier sequence. Some terminals (notably macOS Terminal.app) send a plain Delete even with Ctrl held. Use F8 as a universal alternative, or press Delete when the search bar is empty.

Configuration

ukrop supports an optional TOML configuration file at ~/.config/ukrop/config.toml. Override the path with the UKROP_CONFIG_PATH environment variable. If the file doesn't exist, defaults are used — all settings are optional.

# Commands matching these patterns are never recorded
ignore_patterns = [
    " ",   # commands starting with a space
    "ls",  # exact match
    "cd *",# prefix + wildcard (any cd command)
    "exit",
]

[scoring]
frecency_weight = 100.0
substring_bonus = 8000
prefix_bonus    = 10000

[cleanup]
stale_days = 90

confirm_delete = true

[theme]
preset          = "default"
selection_bold  = true
match_underline = true
favorite_italic = false

[layout]
left_panel_pct = 25
cd_panel_pct   = 75

See the configuration page for the full reference including all 12 theme presets.

In-TUI config editor

Press F9 inside the TUI or run ukrop config to open the config editor as a modal overlay. Changes are previewed live — theme and layout changes update the background panels in real time. Press F9 or Ctrl+S to save, Esc to cancel and revert.

Ignore patterns

• "ls" — exact match only
• "cd *" — matches any command starting with cd  (prefix wildcard)
• " " — matches commands starting with a space (like bash HISTCONTROL=ignorespace)

Auto-cleanup

When opening the cd panel, directories that no longer exist on disk and haven't been visited in stale_days days (default 90) with a low score are automatically removed.

Non-interactive mode

When stdout is not a TTY (e.g. in scripts), ukrop cd <query> prints the best match directly without opening the TUI:

cd "$(ukrop cd projects)"   # jump to best-matching directory

How it works

1. Directory tracking: the shell hook calls ukrop hook -- "$PWD" on every prompt, recording the visit with a frecency score.
2. Command tracking: the preexec hook captures each command, and the precmd hook records it along with exit code, working directory and execution duration via ukrop hook-cmd.
3. Frecency scoring: scores decay exponentially with a one-week half-life — a directory visited 100 times a month ago scores lower than one visited 10 times today.
4. Aging: when total scores exceed 10,000, all scores are scaled down and near-zero entries are pruned.
5. TUI rendering: the picker renders to /dev/tty (not stdout), so the shell wrapper can capture stdout to get the selected path/command.
6. Atomic writes: database operations use SQLite transactions to prevent corruption from concurrent access.

Database

SQLite database (WAL mode for concurrent reads) at:

• macOS: ~/Library/Application Support/ukrop/ukrop.db
• Linux: ~/.local/share/ukrop/ukrop.db

Override location with the UKROP_DB_PATH environment variable:

UKROP_DB_PATH=/tmp/test.db ukrop list

Schema

directories — tracked directory visits: path, score, visit_count, last_visit, is_favorite.

commands — tracked command executions: command, score, use_count, last_used, is_favorite, source, exit_code, cwd, duration_ms.

ssh_hosts — tracked SSH connections: host, hostname, port, user, score, use_count, last_used, is_favorite, source.