Launch a Focused X11 Terminal with Zutty

Zutty gives you a lean X11 terminal with a predictable window size, title, font and scrollback. You need a working X display and the zutty executable in your path; a desktop session normally supplies the display environment, but a Wayland-only session may not.

The examples target the Debian package installed on this machine: zutty 0.14.8.20231210+dfsg1-1. Allow about five minutes if X11 is already running. No elevated privileges are needed anywhere in this guide.

Before you start

This manpage documents X11, so treat a missing display as an environment problem rather than adding random options to work around it. Check the installed package and the command's own usage text first:

zutty --version
zutty -help

On the reviewed package, the first command prints zutty 0.14.8.20231210+dfsg1-1. The second prints usage information and exits without opening a terminal.

Checkpoint: open a predictable terminal

1. Start Zutty with an explicit title, geometry and scrollback size.

zutty -title "Project shell" -geometry 100x30 -fontsize 16 -saveLines 2000

This creates a terminal 100 columns wide by 30 rows high, using a 16-pixel font and keeping 2,000 lines of scrollback. The documented defaults are 80x24, font size 16 and 500 scrollback lines. The window title defaults to Zutty, so setting it earns its keep the moment several terminals are open.

Keep the terminal open and run a small visual check:

printf 'title and geometry check\n'
printf 'shell: %s\n' "$SHELL"

If no window appears and the command reports that it can't open a display, check printf '%s\n' "$DISPLAY" from a terminal inside the graphical session. An empty value means the current shell does not know which X display to use. Do not copy a display value from another user's session; X authentication is part of the problem in that case.

Checkpoint: choose the shell deliberately

1. Use -shell when you need a particular shell executable.

zutty -title "POSIX test shell" -shell /bin/sh

The -shell option selects the shell program to run, which is useful for testing scripts without changing your account's default shell. If you want login-shell behaviour, add -login:

zutty -login -title "Login shell"

A login shell can read different startup files from an ordinary interactive shell. That can change aliases, paths and prompts, so use it when you're actually testing login behaviour, not simply because it sounds more complete.

To return to normal, close the Zutty window or type exit in its shell. These examples only start a process; they do not change your account's configured shell.

Run one command, then leave the terminal

1. Pass a command line with -e when the terminal should be tied to one task.

zutty -title "Kernel check" -e sh -c 'uname -sr; printf "Press Enter to close...\n"; read answer'

The command runs inside Zutty: the quoted shell command prints the kernel name and release, waits for input, then ends. Keep the command after -e together as intended, since shell quoting is handled by your current shell before Zutty even starts.

Do not paste untrusted text into a command string just to display it; launch a normal shell and inspect the text there instead. When the command exits, Zutty normally has no child shell left to keep the window useful. If you need to inspect output interactively, use the earlier normal-shell form or append an explicitly chosen shell command after your check.

Adjust appearance without guessing

The installed manpage exposes direct options for the common changes:

zutty -fg '#d8dee9' -bg '#20242b' -fontsize 18 -border 4

• -fg and -bg set foreground and background colours. The documented defaults are white foreground and black background.
• -border sets the border width in pixels; the default is two pixels.
• Quote the #. A colour value's # must be quoted or escaped in shells where it starts a comment.
• Font selection is handled by -font, -dwfont and -fontpath, with defaults of 9x18, 18x18ja and /usr/share/fonts. Font names are environment-specific, so verify what's actually available on your system rather than assuming a name from another desktop.

Useful checks and failure boundaries

Use these read-only diagnostics before changing a launch command:

printf 'DISPLAY=%s\n' "${DISPLAY:-unset}"
zutty -glinfo
zutty -listres

-glinfo prints OpenGL information and -listres prints the X resource listing, then each option exits. They still need a usable X display. If the output is too noisy during normal launches, -quiet silences logging output; -verbose enables informational messages while troubleshooting.

The -name option sets the X instance name used for X resources and WM_CLASS. It does not load an arbitrary configuration file, and this installed manpage does not define resource names, so avoid inventing a resource file or option spelling from advice written for another terminal emulator.

If you're launching through a desktop entry or a tool that calls x-terminal-emulator, that alias may resolve to Zutty on this system. Test the actual target with readlink -f "$(command -v x-terminal-emulator)". A desktop launcher can also hand you a different environment from the shell where you tested zutty directly.

Done means

• zutty --version reports the installed version you intended to use.
• A launch with explicit geometry, title and scrollback opens in the current X11 session.
• You can distinguish a normal shell, a login shell and a one-command launch.
• Display or OpenGL failures have been checked without changing system configuration.
• Closing the window or typing exit returns the session to its previous state.