Skip to main content
The ssh-cache command manages the SSH terminfo cache used for automatic remote host setup when SSH integration is enabled.

​
Usage

ghostty +ssh-cache [options]

​
Description

When SSH integration is enabled with shell-integration-features = ssh-terminfo, Ghostty automatically installs its terminfo database on remote hosts when you SSH into them. This command manages the cache of successful installations to avoid redundant uploads. The cache stores hostnames (or user@hostname combinations) along with timestamps of when terminfo was successfully installed. Entries older than a configurable expiration period can be automatically removed, though by default entries never expire.

​
Options

​
--clear
boolean
Clear the entire SSH cache, removing all stored hostnames. After clearing, Ghostty will re-upload terminfo to all hosts on next connection.
​
--add
string
Manually add a hostname to the cache. Accepts formats:
  • hostname - Just the hostname
  • user@hostname - User and hostname combination
Use this to pre-populate the cache or mark a host as having terminfo installed.
​
--remove
string
Remove a specific hostname from the cache. Next SSH connection to this host will trigger terminfo upload. Accepts same formats as --add.
​
--host
string
Check if a specific host is in the cache. Returns exit code 0 if cached, 1 if not. Useful for scripting.
​
--expire-days
number
Set a custom expiration period in days for cache entries. Entries older than this will be considered invalid and removed during cache operations.By default, entries never expire.
​
-h, --help
flag
Display help information for this command.
Only one of --clear, --add, --remove, or --host should be specified per command. If multiple are specified, one will be executed but which one is not guaranteed. Always split multiple actions into separate commands.

​
Examples

​
List All Cached Hosts

ghostty +ssh-cache

Cached hosts (3):
  server1.example.com (5 days ago)
  user@server2.example.com (yesterday)
  192.168.1.100 (today)

​
Check If Host Is Cached

ghostty +ssh-cache --host=example.com
echo $?  # 0 if cached, 1 if not

'example.com' has Ghostty terminfo installed.

​
Add Host to Cache

ghostty +ssh-cache --add=example.com

Added 'example.com' to cache.
Or with a user: 
ghostty +ssh-cache --add=user@example.com

Added 'user@example.com' to cache.

​
Remove Host from Cache

ghostty +ssh-cache --remove=example.com

Removed 'example.com' from cache.
Next time you SSH to this host, terminfo will be uploaded again.

​
Clear Entire Cache

ghostty +ssh-cache --clear

Cache cleared.

​
Set Expiration Period

ghostty +ssh-cache --expire-days=30
Entries older than 30 days will be automatically removed during cache operations.

​
Cache Behavior

​
Automatic Cache Updates

When SSH integration is enabled:
  1. Ghostty detects SSH connections
  2. Checks if the target host is in the cache
  3. If not cached, uploads terminfo to the remote host
  4. On successful upload, adds host to cache
  5. Subsequent connections skip the upload

​
Cache Storage Location

The cache is stored in:
  • Linux: $XDG_CACHE_HOME/ghostty/ssh-cache or ~/.cache/ghostty/ssh-cache
  • macOS: ~/Library/Caches/com.mitchellh.ghostty/ssh-cache

​
Entry Format

Cache entries can be:
  • Just hostname: example.com
  • User + hostname: user@example.com
  • IP address: 192.168.1.100
  • User + IP: user@192.168.1.100
Ghostty stores whatever format you used to connect.

​
Use Cases

​
Pre-populate Cache

Before bulk SSH operations:
Script
#!/bin/bash
servers=(
    "web1.example.com"
    "web2.example.com"
    "db.example.com"
)

for server in "${servers[@]}"; do
    ghostty +ssh-cache --add="$server"
done

​
Force Terminfo Re-upload

If terminfo is corrupted on a remote host: 
ghostty +ssh-cache --remove=broken-host.com
ssh broken-host.com  # Will re-upload terminfo

​
Check Cache in Scripts

Script
#!/bin/bash
if ghostty +ssh-cache --host="$1"; then
    echo "Host already has terminfo"
else
    echo "First connection to this host"
fi

​
Periodic Cache Maintenance

Cron Job
# Clear old cache entries monthly
0 0 1 * * ghostty +ssh-cache --expire-days=30

​
Troubleshooting

​
Terminfo Not Loading on Remote Host

  1. Check if host is cached: 
    ghostty +ssh-cache --host=problem-host.com
  2. Remove from cache to force re-upload: 
    ghostty +ssh-cache --remove=problem-host.com
  3. Connect again to trigger upload: 
    ssh problem-host.com

​
Invalid Hostname Error

Error
Error: Invalid hostname format 'bad@host@name'
Expected format: hostname or user@hostname
Solution: Use valid hostname format:
  • hostname.com
  • user@hostname.com

​
Cache Is Locked Error

Error
Error: Cache is busy, try again
Solution: Another Ghostty process is modifying the cache. Wait a moment and retry.

​
SSH Integration Configuration

Enable SSH terminfo integration in your config:
config
# Enable SSH terminfo upload
shell-integration-features = ssh-terminfo

# Or enable all shell integration features
shell-integration-features = true

​
Notes

The cache only tracks successful terminfo installations. If upload fails, the host is not added to the cache and will be retried on the next connection.
Entries in the cache don’t expire by default. Use --expire-days to set an expiration policy if desired.
The cache is per-user on your local machine. Each user maintains their own separate SSH terminfo cache.
If you have many remote hosts that you access regularly, consider pre-populating the cache to avoid the small delay on first connection.

​
See Also