`gifgrep tui`

The TUI is a small, opinionated terminal UI for browsing GIFs with animated inline previews.

gifgrep tui [<query> ...] [flags]

gifgrep tui                    # launches with empty query, hit / to search
gifgrep tui cats               # initial query
gifgrep tui --source giphy cats

gifgrep TUI with animated inline previews

#Keys

Key	Action
`/`	Edit search query.
`↑` `↓`	Move selection.
`d`	Download current selection to `~/Downloads`.
`f`	Reveal last download in Finder / Explorer / Files.
`q`	Quit.

#Inline previews

The TUI streams animated previews using the Kitty graphics protocol on Kitty/Ghostty, OSC 1337 on iTerm2, Sixel where available, or a truecolor ANSI fallback when forced.

Terminal	Animation playback
Kitty	Native. gifgrep uploads frames once; the terminal animates them.
Ghostty	Software playback (gifgrep ticks frames on a timer).
iTerm2	Native — iTerm2 plays GIFs from raw bytes.
Sixel	Software playback (gifgrep redraws frames into the same cell area).
ANSI fallback	Software playback with truecolor half-blocks.
Apple Terminal	Falls back to a static list (no graphics protocol).
tmux	Best with a graphics-aware host terminal; YMMV with image passthrough.

Force or disable software playback:

GIFGREP_SOFTWARE_ANIM=1 gifgrep tui cats   # always tick frames in software
GIFGREP_SOFTWARE_ANIM=0 gifgrep tui cats   # always trust terminal animation

#Tweaking preview geometry

Some terminals report cell sizes that make GIFs look squashed. Override the cell aspect ratio:

GIFGREP_CELL_ASPECT=0.5 gifgrep tui cats   # default
GIFGREP_CELL_ASPECT=0.45 gifgrep tui cats  # narrower

#Provider selection

Same --source as search:

gifgrep tui --source giphy cats
gifgrep tui --source klipy cats

See Providers for the full matrix.

#When the TUI is the wrong tool

For pipelines and scripts, use gifgrep search. The TUI never writes to stdout.
For local frame extraction, use still or sheet. The TUI is search-first.
In a non-interactive shell (CI, cron), the TUI will refuse to start. Use search with --json.