Configuration

Configuration

English · 中文

Where the config file lives, how CLI flags interact with it, and the full key reference.

WispTerm uses a Ghostty-compatible config format — plain key = value pairs.

Where the config lives

The main config path is resolved in this order:

1. --config <path> or --config-path <path>
2. wispterm.conf next to the executable (portable profile, Windows only)
3. Platform config directory:
   • Windows: %APPDATA%\wispterm\config
   • macOS: ~/Library/Application Support/wispterm/config
   • Linux: $XDG_CONFIG_HOME/wispterm/config (fallback ~/.config/wispterm/config)

Press open_config (Ctrl+,, Cmd+, on macOS) to open the config in your editor, or run wispterm --show-config-path to print the resolved path.

CLI vs file

CLI flags override config-file values (last wins). config-file = extra.conf and --config-file extra.conf include additional config files (prefix the path with ? to make it optional); they do not change the main config path.

Example config

font-family = Cascadia Code
font-style = regular
font-size = 14
cursor-style = bar
cursor-style-blink = true
theme = Poimandres
window-height = 32
window-width = 120
quake-mode = false
keybind = global:ctrl+backquote=toggle_quake
keybind = ctrl+shift+p=toggle_command_palette
scrollback-limit = 10000000
url-open-mode = embedded
custom-shader = path/to/shader.glsl
background-image = C:\Users\me\Pictures\wallpaper.png   # Windows; use /Users/me/Pictures/wallpaper.png on macOS
background-opacity = 0.85
background-image-mode = fill
config-file = extra.conf
auto-update-check = true
focus-follows-mouse = false
remote-enabled = false

Key reference

Key	Default	Description
font-family	(none)	Font family name (falls back to the embedded font if unset)
font-style	regular	Font weight: thin, extra-light, light, regular, medium, semi-bold, bold, extra-bold, black
font-size	12	Font size in points
cursor-style	block	Cursor shape: block, bar, underline, block_hollow
cursor-style-blink	true	Enable cursor blinking
theme	(none)	Theme name or absolute path (453 Ghostty themes built in)
custom-shader	(none)	Path to a GLSL post-processing shader
background-image	(none)	Path to an image (PNG/JPG/BMP/GIF/TGA) rendered behind the terminal
background-opacity	1.0	Opacity of the theme tint over the wallpaper (0.0 = image only, 1.0 = image hidden)
background-image-mode	fill	Image scaling: fill, fit, center, tile
window-height	0 (auto)	Initial height in cells (min 4, 0 = auto 80×24)
window-width	0 (auto)	Initial width in cells (min 10, 0 = auto 80×24)
quake-mode	false	Start as a Quake-style drop-down terminal; toggle_quake hides/shows it while preserving state
keybind	defaults	Configure an app-level shortcut (repeatable). Syntax [global:]modifier+key=action; keybind = clear removes all defaults
scrollback-limit	10000000	Scrollback buffer limit in bytes
focus-follows-mouse	false	Focus the panel under the mouse without clicking
url-open-mode	embedded	Where web URLs open: embedded uses the right-side browser panel when available (Windows only); system-browser always uses the system default browser. SSH loopback URLs keep local port forwards alive either way
restore-tabs-on-startup	false	Persist tab/split layout (session.json) on close and rebuild on next launch. SSH passwords are never persisted; reconnects re-prompt. --cwd overrides skip restore
auto-update-check	true	Check GitHub Releases after startup and prompt when a newer version exists
config-file	(none)	Include another config file (prefix ? to make optional)
remote-enabled	false	Start the shared outbound RemoteClient for this instance — see Remote-Access
remote-server-url	(none)	Cloudflare relay URL, e.g. https://remote.example.com
remote-server-fingerprint	(none)	Expected relay fingerprint for server identity pinning
remote-device-name	(none)	Friendly device name sent with the WispTerm pairing
remote-session-key	(none)	Fixed remote session key base; later concurrent instances use _1, _2, …
ssh-legacy-algorithms	false	Append compatibility options (ssh-rsa, old KEX, CBC) for legacy SSH servers — see SSH-Remote-Development
copy-on-select	false	Copy the terminal selection automatically — see AI-Copilot
right-click-action	(none)	paste, or copy-or-paste (copy when a selection exists, else paste)
confirm-close-running-program	true	Confirm before closing a panel/tab running a full-screen TUI
windows-conpty	auto	Windows console host: auto prefers the bundled modern ConPTY when conpty.dll + OpenConsole.exe sit next to wispterm.exe (shipped in the portable-compat package; restores TUI mouse support on old Windows 10); system forces the OS in-box ConPTY — see FAQ
wispterm-d3d-present	true	Windows: present frames via a DXGI flip-model swapchain. Set false to force the classic GDI presenter (useful on weak integrated GPUs; since v1.19.1 WispTerm also auto-switches affected machines) — see FAQ

Settings page

You do not have to edit the config file by hand. Open the [[command center|Getting-Started]] (Ctrl+Shift+P) and run Settings to edit the most common options in a form: font size, theme, cursor style and blink, focus-follows-mouse, restore-tabs-on-startup, the default shell, the default AI profile, WeChat direct control, and the interface language. There is also an Open raw config button for the advanced keys above. Changes are written back to the same config file; a few options (such as language) apply after a restart.

The Restore default settings row resets the options the page manages, after a confirmation dialog. It clears only the keys exposed on the settings page — it leaves Quake mode, your saved AI profiles, and custom keybind lines untouched.

OpenSSH config import

Open the command center and run Load OpenSSH Config to import compatible entries from ~/.ssh/config into WispTerm's SSH profiles. WispTerm imports Host, HostName, User, Port, and ProxyJump, follows Include files, skips wildcard host patterns, and never imports passwords.

Hot reload

Many changes apply without restarting: save the config (or hot-reload via Ctrl+,) and WispTerm re-reads it. Clearing a value (e.g. background-image) removes the effect.

---

See also: Themes-Appearance · Keyboard-Shortcuts · Remote-Access