Kitten @ Commands
The kitty @ interface is the primary way to control a running kitty instance programmatically. It accepts subcommands that map to every action kitty can perform — window management, tab control, color changes, font sizing, and more.
Learning Focus
Learn the most useful kitty @ commands by category. Use kitty @ ls as your discovery tool — it shows everything running and helps construct the exact --match criteria for targeting windows.
Listing Available Commands
# List all available @ commands
kitty @ help
# Detailed help for a specific command
kitty @ help launch
kitty @ help set-colors
Common Commands Reference
Window and Tab Management
| Command | Description |
|---|---|
kitty @ ls | List all windows, tabs, OS windows |
kitty @ launch | Open new window or tab (optionally with command) |
kitty @ close-window | Close the matching window |
kitty @ close-tab | Close the matching tab |
kitty @ focus-window | Focus a specific window by match |
kitty @ focus-tab | Focus a specific tab |
kitty @ move-window | Move window to another tab or position |
kitty @ resize-window | Resize window (wider, taller, etc.) |
Visual Configuration
| Command | Description |
|---|---|
kitty @ set-colors | Apply a color theme from file |
kitty @ set-font-size | Change font size (temporary) |
kitty @ set-background-opacity | Adjust background transparency |
kitty @ load-config | Reload kitty.conf without restart |
kitty @ set-tab-title | Change a tab's title |
kitty @ set-window-title | Change a window's title |
Input and Data
| Command | Description |
|---|---|
kitty @ send-text | Send text to a window (as if typed) |
kitty @ get-text | Get text content from a window |
kitty @ get-text-encoding | Get current text encoding |
kitty @ clipboard | Access clipboard contents |
Miscellaneous
| Command | Description |
|---|---|
kitty @ set-spacing | Adjust window margin/padding |
kitty @ set-layout | Change window layout |
kitty @ toggle-layout | Cycle to next layout |
kitty @ kitten | Run a kitten from the remote control |
kitty @ signal | Send a signal to a kitty process |
Matching Windows and Tabs
Most commands accept --match to target a specific window or tab. The match criteria are flexible:
# Match by ID (from kitty @ ls)
kitty @ close-window --match id:1
# Match by window title
kitty @ focus-window --match title:logs
# Match by tab title
kitty @ close-tab --match title:editor
# Match by process name
kitty @ launch --match title:monitor htop
# Multiple criteria (AND logic)
kitty @ send-text --match 'id:1 and title:logs' "tail -f syslog\n"
# Match by index
kitty @ focus-window --match index:0
# Find the right match values
kitty @ ls | grep -E "(id|title|tab_title)"
Getting Window State
# Full JSON dump of kitty state
kitty @ ls
# JSON output for scripting
kitty @ ls | jq '.[] | {id: .id, title: .title, tab_title: .tab_title}'
Piping Commands
Commands can be chained or piped:
# Chain: create a window, then send a command
kitty @ launch --type=window && kitty @ send-text --match 'title:bash' "htop\n"
# Pipe kitty @ output to other tools
kitty @ ls | jq '.windows[] | .title' | sort | uniq
# Save state to file
kitty @ ls > /tmp/kitty-state.json
Practical Examples
Change Theme on Schedule
# Day theme
kitty @ set-colors --configured ~/.config/kitty/light-theme.conf
# Night theme
kitty @ set-colors --configured ~/.config/kitty/dark-theme.conf
Open Monitoring Dashboard
kitty @ launch --type=tab --title "Monitor" --cwd /var/log bash -c "htop"
kitty @ launch --type=window --title "Syslog" --cwd /var/log bash -c "tail -f syslog"
kitty @ launch --type=window --title "Dmesg" --cwd /var/log bash -c "watch dmesg"
Send Commands to Running Processes
# Send Ctrl+C to a hanging process
kitty @ send-text --match id:2 "\x03"
# Send a command to a specific window
kitty @ send-text --match 'title:server' "systemctl restart nginx\n"
Common Pitfalls
| Pitfall | Symptom | Fix |
|---|---|---|
| Match criteria too broad | Affects wrong window | Use specific id:N matching from kitty @ ls output |
send-text doesn't execute command | Text typed but not run | Always append \n (newline) at the end of the string |
| JSON output not parseable | jq errors on incomplete output | Use `kitty @ ls |
kitty @ not found | Command not found | Verify kitty is in PATH and running |
load-config doesn't show errors | Config broken silently | Use kitty @ load-config and check for error messages in stderr |
Hands-On Practice
# 1) List all commands
kitty @ help
# 2) Check current kitty state
kitty @ ls
# 3) Create a tab with two windows
kitty @ launch --type=tab --title "Practice"
kitty @ launch --type=window --match 'title:Practice'
# 4) Send a command to a window
kitty @ send-text --match 'title:bash' "echo 'Hello from kitty @'\n"
# 5) Change font size temporarily
kitty @ set-font-size 20
sleep 2
kitty @ set-font-size 12
# 6) Apply a color scheme (create a simple one first)
echo "background #1e1e2e" > /tmp/kitty-test-theme.conf
echo "foreground #cdd6f4" >> /tmp/kitty-test-theme.conf
kitty @ set-colors --configured /tmp/kitty-test-theme.conf
# 7) Clean up
kitty @ close-tab --match 'title:Practice'