Kitten Commands Reference

Kittens are auxiliary programs that ship with kitty. They extend kitty's functionality for tasks like image display, file comparison, theme management, SSH, and remote control.

Learning Focus

Kittens are launched with kitty +kitten <name>. They inherit kitty's terminal capabilities, so they can use kitty-specific protocols (images, hyperlinks, etc.) even over SSH.

Image Display: `icat`

Display images directly in the terminal.

# Basic image display
kitty +kitten icat image.png

# Display with specific size
kitty +kitten icat --scale-up --place 80x40@0x0 image.png

# Display multiple images
kitty +kitten icat image1.jpg image2.jpg

# Image from stdin
curl -s https://example.com/image.png | kitty +kitten icat

# Clear displayed images
kitty +kitten icat --clear

Option	Description
`--scale-up`	Scale image up to fill available space
`--place WxH@XxY`	Place at specific position and size (cell units)
`--stdin no`	Read from stdin (default: auto-detect)
`--align left	center
`--transfer-mode file	stream
`--clear`	Remove all displayed images
`--print-window-size`	Print terminal window dimensions

File Comparison: `diff`

Visual diff tool using kitty's terminal hyperlinks.

# Compare two files
kitty +kitten diff file1.txt file2.txt

# Compare with context
kitty +kitten diff --context 5 file1.txt file2.txt

# Diff directories
kitty +kitten diff dir1/ dir2/

# Use with git
git diff --no-index file1.txt file2.txt | kitty +kitten diff

Option	Description
`--context N`	Context lines around changes (default: 3)
`--ignore-all-space`	Ignore whitespace changes
`--ignore-blank-lines`	Ignore blank line changes
`--recursive`	Recursively diff directories
`--exclude PATTERN`	Exclude files matching pattern

Theme Management: `themes`

Browse and apply color themes interactively.

# Browse and select a theme
kitty +kitten themes

# List all available themes
kitty +kitten themes --list

# Preview a specific theme
kitty +kitten themes --theme="Solarized Dark"

# Apply theme via config
kitty +kitten themes --reload-in=parent

# Cache themes for offline use
kitty +kitten themes --cache-update

Option	Description
`--list`	List all themes without interactive UI
`--theme NAME`	Apply theme directly (no interactive)
`--reload-in=parent	child`
`--cache-update`	Update theme cache from GitHub

Text Selection / Actions: `hints`

Select visible text on screen and perform actions (copy, open, insert).

# Copy a visible path/filename
kitty +kitten hints

# Open a URL
kitty +kitten hints --type url

# Copy a specific pattern
kitty +kitten hints --type path --program @copy

# Hyperlink grep results
kitty +kitten hints --type grep --program @open

# Custom type (regex match)
kitty +kitten hints --customize "regex:0x[0-9a-fA-F]+"

Option	Description
`--type url\|path\|line\|word\|hash\|grep`	What to select
`--program @copy\|@open\|@paste`	What to do with selection
`--customize PATTERN`	Custom regex hint type
`--multiple`	Select multiple items sequentially
`--terminal`	Use terminal to display choices

SSH with Terminfo: `ssh`

SSH into a remote host with automatic terminfo transfer.

# Basic SSH (transfers xterm-kitty terminfo)
kitty +kitten ssh user@host

# With ports and options
kitty +kitten ssh -p 2222 user@host

# Command mode
kitty +kitten ssh user@host "tail -f /var/log/syslog"

# Verbose debug
kitty +kitten ssh -v user@host

# With X11 forwarding
kitty +kitten ssh -X user@host

Option	Description
`-p PORT`	SSH port
`-v`	Verbose output
`-X`	Enable X11 forwarding
`-A`	Enable agent forwarding
`-i KEY`	Identity file
`-o OPTIONS`	Additional SSH options
`--ssh-transferred-files`	Path for transferred files

The SSH kitten is superior to plain ssh because it:

Transfers the xterm-kitty terminfo to the remote host automatically
Enables true color, italic, and kitty protocol features on remote sessions
Supports image transfer over SSH (with --remote-pwd)

File Transfer: `transfer`

Transfer files between kitty instances or to remote hosts.

# Send file to remote via SSH
kitty +kitten transfer local-file.txt user@host:/remote/path/

# Receive file from remote
kitty +kitten transfer user@host:/remote/file.txt ./local-dir/

# Transfer between kitty instances
kitty +kitten transfer --direction send /path/to/file

# With compression
kitty +kitten transfer --compress local-file.txt user@host:~/files/

File Selection: `choose-files`

Interactive file chooser dialog in the terminal.

# Basic file selection
kitty +kitten choose-files

# Multiple file selection
kitty +kitten choose-files --multiple

# Start in specific directory
kitty +kitten choose-files --cwd /var/log

# Filter by type
kitty +kitten choose-files --pattern "*.log"

# Output as JSON
kitty +kitten choose-files --json

Clipboard Access: `clipboard`

Read and write the system clipboard.

# Show clipboard contents
kitty +kitten clipboard

# Write to clipboard
echo "hello" | kitty +kitten clipboard

# Read clipboard
kitty +kitten clipboard --get-clipboard

# Write to primary selection (X11)
echo "text" | kitty +kitten clipboard --primary

Multi-Window Input: `broadcast`

Send input to multiple kitty windows simultaneously.

# List broadcast groups
kitty +kitten broadcast

# Send command to all windows
kitty +kitten broadcast "ls -la"

# Send to specific windows by ID
kitty +kitten broadcast --match id:1,id:2 "echo hello"

# Send control character
kitty +kitten broadcast --send-keys "Ctrl+c"

# Toggle broadcast mode for active windows
kitty +kitten broadcast --toggle

# Create named broadcast group
kitty +kitten broadcast --group servers "uptime"

Option	Description
`--match PATTERN`	Match windows (id:, title:, env:, etc.)
`--group NAME`	Broadcast to named group
`--toggle`	Toggle broadcast mode on/off
`--send-keys KEYS`	Send specific key events

Desktop Panel: `panel`

Create a kitty desktop panel (like a dock widget).

# Show system info panel
kitty +kitten panel htop

# Show clock panel
kitty +kitten panel --clock

# Custom command panel
kitty +kitten panel --title "watch" "watch -n 1 date"

# Panel placement
kitty +kitten panel --placement top-left --size 400x200 htop

Hyperlinked Grep: `hyperlinked_grep`

Run grep with clickable hyperlinks to files.

# Basic grep with hyperlinks
kitty +kitten hyperlinked_grep "pattern" src/

# With line numbers
kitty +kitten hyperlinked_grep -n "pattern" src/

# Recursive with context
kitty +kitten hyperlinked_grep -rn -C 3 "function" src/

# Use with hints to open results
kitty +kitten hyperlinked_grep "TODO" . | kitty +kitten hints

Remote Control: `kitten @`

Control a running kitty instance programmatically.

# List all windows/tabs
kitty @ ls

# Create new window
kitty @ new-window --cwd /var/log --title logs

# Create new tab
kitty @ new-tab --tab-title "monitoring"

# Send text to a window
kitty @ send-text --match title:logs "tail -f syslog\n"

# Set colors dynamically
kitty @ set-colors --match all foreground=#ffffff

# Get current colors
kitty @ get-colors

# Resize window
kitty @ resize-window --match id:1 --axis horizontal --increment 20

# Focus specific window
kitty @ focus-window --match title:logs

# Close window
kitty @ close-window --match id:3

# Load config
kitty @ load-config

# Get remote control help
kitty @ --help

Command	Description	Common Options
`ls`	List all windows/tabs	—
`new-window`	Create new window	`--cwd`, `--title`, `--match`, `--location`
`new-tab`	Create new tab	`--tab-title`, `--cwd`
`close-window`	Close window	`--match`, `--all`
`send-text`	Send text to window	`--match`, stdin
`set-colors`	Change colors	`--match`, `foreground=`, `background=`
`get-colors`	Get current colors	`--match`
`resize-window`	Resize window	`--axis`, `--increment`, `--match`
`focus-window`	Focus window	`--match`
`load-config`	Reload config	—
`set-tab-title`	Set tab title	`--match`, title string
`set-window-title`	Set window title	`--match`, title string

Kitten Quick Reference Table

Kitten	Command	Primary Use
icat	`kitty +kitten icat <file>`	Display images in terminal
diff	`kitty +kitten diff <a> <b>`	Visual file comparison
themes	`kitty +kitten themes`	Browse and apply themes
hints	`kitty +kitten hints --type <type>`	Click-to-select visible text
ssh	`kitty +kitten ssh <user>@<host>`	SSH with auto terminfo
transfer	`kitty +kitten transfer <src> <dst>`	File transfer with progress
choose-files	`kitty +kitten choose-files`	Interactive file picker
clipboard	`kitty +kitten clipboard`	Clipboard read/write
broadcast	`kitty +kitten broadcast <text>`	Multi-window input
panel	`kitty +kitten panel <cmd>`	Desktop panel widget
hyperlinked_grep	`kitty +kitten hyperlinked_grep <pat> <dir>`	Grep with clickable results
query_terminal	`kitty +kitten query_terminal`	Query terminal capabilities
benchmark	`kitty +kitten benchmark`	Performance benchmark
@ (remote)	`kitty @ <command>`	Programmatic kitty control

Common Pitfalls

Pitfall	Symptom	Fix
`icat` shows garbled output	Image protocol blocked by tmux	Exit tmux or use `kitty +kitten icat` directly
`themes` can't fetch list	No internet connection	Use `--cache-update` when online, then themes works offline
`ssh` fails with "not a kitty terminal"	Called from non-kitty terminal	Always use inside kitty or set `TERM=xterm-kitty`
`broadcast` sends to wrong windows	Match pattern too loose	Use `--match id:1,id:2` instead of title matching
`remote control` commands fail	`allow_remote_control` not set	Set `allow_remote_control yes` and restart kitty
`clipboard` read permission denied	`clipboard_control` restricts reads	Set `clipboard_control read-clipboard write-clipboard`
`diff` shows no output	Files are identical	`diff` only shows when differences exist
`hyperlinked_grep` links not clickable	Not inside kitty	Only works in kitty (uses kitty hyperlink protocol)

Hands-On Practice

# 1. Test icat with kitty's own icon (if available)
kitty +kitten icat /usr/share/icons/hicolor/48x48/apps/kitty.png 2>/dev/null || echo "icat unavailable (not in kitty or no image)"

# 2. Browse themes
kitty +kitten themes

# 3. Compare two files
echo "hello" > /tmp/a.txt
echo "world" > /tmp/b.txt
kitty +kitten diff /tmp/a.txt /tmp/b.txt

# 4. Test clipboard
echo "kitty test" | kitty +kitten clipboard

# 5. List remote control info
kitty @ ls 2>/dev/null || echo "Remote control not enabled (set allow_remote_control yes)"

# 6. Benchmark your kitty
kitty +kitten benchmark

# 7. Query terminal capabilities
kitty +kitten query_terminal | head -15

Image Display: icat​

File Comparison: diff​

Theme Management: themes​

Text Selection / Actions: hints​

SSH with Terminfo: ssh​

File Transfer: transfer​

File Selection: choose-files​

Clipboard Access: clipboard​

Multi-Window Input: broadcast​

Desktop Panel: panel​

Hyperlinked Grep: hyperlinked_grep​

Remote Control: kitten @​

Kitten Quick Reference Table​

Common Pitfalls​

Hands-On Practice​

What's Next​