Troubleshooting

Cretty does not start

Run Cretty from a terminal to capture diagnostic output:

CRETTY_LOG=cretty=debug cretty

When running from a source checkout, use CRETTY_LOG=cretty=debug cargo run. Include the operating system and display backend when reporting a graphics startup issue. On Linux, try the other display session (Wayland or X11) and verify the required system libraries are installed.

The shell or working directory is wrong

Check terminal.shell.program and terminal.shell.args in Settings or config.toml. cretty --directory applies only to the initial tab. Later tabs normally follow the active tab’s current directory; change terminal.inherit_working_directory if you want new tabs to start elsewhere.

Clipboard access and terminal links

Copy and paste shortcuts access the system clipboard. OSC 52 lets a terminal program write to the clipboard only when its terminal is focused. Clipboard read requests from terminal output are denied, including requests from remote commands. A program that expects to read your clipboard through OSC 52 will not receive its contents; paste explicitly with the normal shortcut instead.

Activated terminal links open HTTP, HTTPS, and mailto destinations. Other schemes are ignored. If a link does not open, check its target and whether hyperlinks are enabled in Settings.

Unknown terminal type over SSH

Cretty sets TERM=xterm-cretty and installs its terminfo entry for the local user when tic is available. A remote machine may not know that terminal name. For a session using the standard fallback, launch:

TERM=xterm-256color ssh host

Alternatively, copy cretty/cretty.terminfo from the source checkout to the remote machine and run tic -x cretty.terminfo there. A missing local tic command is logged and does not prevent startup.

UI scheduling priority on Linux

Cretty requests nice -5 for its UI thread, using RealtimeKit when direct priority changes are unavailable. It enables Linux’s reset-on-fork flag before requesting the boost, so new worker threads, terminal shells, and launched programs retain normal priority. If the system denies the request, Cretty continues at normal priority and logs the reason at debug level. No root privileges or realtime scheduling are required. See the Linux scheduling documentation and RealtimeKit interface.

Notifications or bells are not visible

Cretty can flash inactive tabs for terminal bells and show desktop notifications for bells, OSC 9;4 progress, and OSC 777 notifications. Verify that notifications are permitted for Cretty in your operating system settings; then confirm that the terminal application is actually emitting the relevant escape sequence.

Fonts, icons, or glyphs look wrong

Select a known terminal font in Settings → Terminal and ensure terminal.nerd_font_fallback is enabled when you want embedded Nerd Font symbols to fill missing glyphs. The Themes and fonts guide lists the bundled families and the relevant settings.

Reporting a bug

Report issues on the GitHub Issues page. Include:

• Cretty version (cretty --version), operating system, and display backend.
• A minimal way to reproduce the problem and the expected versus actual result.
• Relevant settings or preset snippets and terminal output from a diagnostic launch.

Remove secrets, tokens, private hostnames, and sensitive paths before sharing logs or screenshots.