If the terminal command clear doesn’t work in SSH sessions when using Ghostty#
I use Ghostty as my terminal emulator. I also sometimes connect to remote machines via SSH.
When I type, for example, the command clear into Ghostty during a SSH session, I receive the following error:
'xterm-ghostty': unknown terminal type.
This means that the environment variable TERM has been set to xterm-ghostty by Ghostty, but the remote machine doesn’t recognize this value of TERM. Ghostty isn’t a terminal emulator that your server knows. Read on to learn how to solve this problem.
Background#
Different terminal emulators have different capabilities. That is after all the explanation for why you use Ghostty and not, for example, Alacritty or Kitty or iTerm2 or foot or XTerm or any of the other existing terminal emulators. The terminal emulator needs to tell the computer what capabilities it has so that the programs you use inside your terminal emulator know which of their features are supported by the particular terminal emulator you choose to use. For example, you won’t be able to see italic types inside Neovim—some people like to style code comments in an italic type—if your particular terminal emulator didn’t advertise to the computer that it even supports italics. The same goes for true color support or underlined text and a number of other features.
The terminal emulator advertises its capabilities to the system by calling a tool named tic (the terminfo entry-description compiler) that then writes the capabilites of the terminal emulator into a database on your computer called the terminfo database. In other words, each terminal emulator you have installed on your computer adds an entry for itself to that terminfo database. That database usually is located at /usr/share/terminfo or ~/.terminfo.
The thing is: When you installed Ghostty or Alacritty or any other terminal emulator on your local computer, your terminal emulator added an entry for itself to your local computer, but when you connect to a remote computer via SSH, that remote machine doesn’t necessarily have an entry for your terminal emulator in its terminfo database. Whether the entry is there or not depends on whether someone has put it there for you: Typically that would have been done by the TUI library ncurses. But since you’re getting errors and ncurses did in fact not add Ghostty’s terminfo definition to the terminfo database for you, you need to inform your remote computer about Ghostty’s capabilities yourself by adding an entry for Ghostty in the remote computer’s terminfo database. You can do that manually or let Ghostty do the work for you. I prefer the automatic approach, because then I don’t have to repeat the manual process for each server I use. All I need to do is change Ghostty’s configuration on my local computer—a change I have to do only once—and from then on everything will work automatically on all my remote machines, no matter how many remote machines I use. The first time I connect to a new remote machine via SSH, Ghostty will automatically add its entry to the terminfo database on the remote machine for me.
Solution#
Add this line to Ghostty’s configuration file ~/.config/ghostty/config, as documented here:
shell-integration-features = ssh-terminfo
You need Ghostty in version 1.2.0 or newer for this to work.
With that newly added line in your configuration, Ghostty will automatically add an entry to the database inside ~/.terminfo/ on your server and thereby introduce itself to your remote machine. Then, your remote machine will know Ghostty and its capabilities. Telling your server about Ghostty is what the TUI library ncurses would normally do for you, but if ncurses isn’t new enough, then ncurses doesn’t itself yet know about Ghostty and therefore won’t add an entry for Ghostty to your remote machine. Then the commands you try to execute on your remote machine won’t work when they try to update the displayed content, as the command clear would.
Final words#
You can find more details here if you’re interested or have similar problems with the command sudo. Feel free to contact me. In any case, be well.