https://github.com/catsdeservepets/spit
spit is a tiny TUI tool that lets you flip through images directly in your terminal.
https://github.com/catsdeservepets/spit
command-line command-line-tool image picture terminal vim
Last synced: about 2 months ago
JSON representation
spit is a tiny TUI tool that lets you flip through images directly in your terminal.
- Host: GitHub
- URL: https://github.com/catsdeservepets/spit
- Owner: CatsDeservePets
- Created: 2025-08-09T03:52:49.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-08-21T17:57:43.000Z (10 months ago)
- Last Synced: 2025-10-25T08:38:18.349Z (8 months ago)
- Topics: command-line, command-line-tool, image, picture, terminal, vim
- Language: Go
- Homepage:
- Size: 43.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# spit - Show Pictures In Terminal
`spit` is a tiny TUI tool that lets you flip through images directly in your terminal.
\
\
## Installation
```shell
go install github.com/CatsDeservePets/spit@latest
```
## Usage
```
usage: spit [-h] [-V] [-p] [-c FILE] [-n VALUE] [path ...]
spit - Show Pictures In Terminal
positional arguments:
path image files or directories (default: *)
options:
-h, -help show this help message and exit
-V, -version show program's version number and exit
-p print default configuration and exit
-c FILE use this configuration file (default: $XDG_CONFIG_HOME/spit/spit.conf)
-n VALUE set initial image using 1-based index or filename (default: 1)
navigation:
l, j move forward
h, k move backward
g go to first image
G go to last image
? help
q quit
```
> [!NOTE]
> Directory paths must end with a path separator (`/` on Unix, `\` on Windows).
> For example: `Downloads/` (not `Downloads`).
## Configuration
### Image previews
To enable previews, configure a `previewer` command. It runs for each image and draws it. It can talk to a terminal image protocol (e.g. [Kitty](https://sw.kovidgoyal.net/kitty/graphics-protocol/), [iTerm](https://iterm2.com/documentation-images.html)) or call a helper tool (e.g. [chafa](https://github.com/hpjansson/chafa/), [viu](https://github.com/atanunq/viu)).\
See the [Config file](#config-file) section for available expansions.
Kitty:
```shell
previewer="kitten icat --clear --stdin=no --transfer-mode=memory --place=%cx%r@0x0 --scale-up=yes %f"
```
Chafa:
```shell
previewer="chafa --clear --size=%cx%r --align=mid,mid %f"
```
There is also a `cleaner` command that clears the previously drawn image. Many tools and protocols already offer a flag to clear.\
However, in some cases it might still be useful to separate clearing and drawing (e.g. performance reasons).
For tools without a clear option, you can clear the screen manually:
```shell
cleaner="printf \033[2J\033[H"
```
> [!NOTE]
> Protocol support varies by terminal. [Yazi's docs](https://github.com/sxyazi/yazi?tab=readme-ov-file#documentation) have a nice list of different terminals and their supported protocols.\
> Tools like `chafa` or `viu` can behave differently across terminals. Be prepared to tweak flags and try out different things to make it all work.\
> Using a terminal multiplexer like `Tmux` can also cause issues with some tools.
### Config file
By default, `spit` loads its configuration from:
$XDG_CONFIG_HOME/spit/spit.conf
If `$XDG_CONFIG_HOME` is not set, it falls back to:
Linux ~/.config/spit/spit.conf
macOS ~/Library/Application Support/spit/spit.conf
Windows %AppData%\spit\spit.conf
The `-config` flag takes precedence over all of the above.
### Default configuration
```shell
# vim:ft=config
# Command used to cleanup the preview.
# For more details about expansions, see 'previewer'.
cleaner=""
# Format string for error messages
errorfmt="\x1b[7;31;47m"
# Enable 'spit' on the following image extensions
extensions="bmp,gif,jpg,jpeg,png,tif,tiff,webp"
# Use human readable sizes
humanreadable=false
# Command used to preview images.
# Following expansions are available:
# %c terminal columns
# %r terminal rows
# %f file name (including path)
previewer="kitten icat --clear --stdin=no --transfer-mode=memory --place=%cx%r@0x0 --scale-up=yes %f"
# Set the look of the statusline.
# Following expansions are available:
# %f file name
# %h image height
# %w image width
# %i current index
# %t total amount of images
# %s image size
# %= alignment separator
statusline="%f %= %wx%h %s %i/%t"
# Whether to set the terminal title to the current image
title=false
# Character used for truncating the statusline when it gets too long
truncatechar="<"
# Scroll past the last image back to the first one and vice versa
wrapscroll=true
```