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
# Windows Git Bash example:
# shell = "C:\Program Files\Git\bin\bash.exe" --login -i
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
feishu-enabled = false
feishu-app-id = cli_xxx
feishu-app-secret = your-app-secret

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
shell	OS default	Shell command for new local sessions. Windows aliases: cmd, powershell, pwsh, wsl; POSIX examples: sh, zsh, fish. You can also use a custom command line such as "C:\Program Files\Git\bin\bash.exe" --login -i
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 (WebView2 on Windows, WKWebView on macOS); 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)
ai-default-profile	(none)	Saved AI profile name used by New Agent, startup auto-open, remote auto-open, and Copilot defaults. Empty falls back to the first saved profile. /model changes only the current session and does not rewrite this key
ai-agent-enabled	false	Enable agent tools for AI Chat profiles by default
ai-agent-permission	ask	Agent tool permission mode: ask, auto, or full
ai-agent-command-timeout-ms	60000	Timeout budget for agent shell/SSH commands
ai-agent-output-limit	16384	Maximum bytes returned from a single tool result
ai-agent-working-dir	(none)	Default working directory for agent local commands. Empty leaves it unset
copilot-hint	true	Show the right-edge Copilot summon handle and one-time shimmer hint. Set to false to hide that discovery affordance
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, …
feishu-enabled	false	Enable the Feishu/Lark long-connection channel. Configure credentials from the command center by typing feishu, or set the keys below; restart required
feishu-app-id	(none)	Feishu app ID (cli_...). Falls back to FEISHU_APP_ID when empty
feishu-app-secret	(none)	Feishu app secret. Falls back to FEISHU_APP_SECRET when empty; keep it private
feishu-allowed-user	(none)	Optional Feishu open_id allowed to control WispTerm. Empty means no explicit restriction; the first sender is auto-bound as owner
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.

Default shell and Git Bash

Set shell in your config file to choose what new local shell sessions launch. Existing tabs keep their current process; save the config, wait for hot reload or restart WispTerm, then open a new session.

On Windows, Git Bash should be configured as a command line with double quotes around the executable path:

shell = "C:\Program Files\Git\bin\bash.exe" --login -i

Do not use single quotes, and do not write Windows backslashes as \\. WispTerm config is not JSON, so single quotes and doubled backslashes are treated as literal characters:

# Wrong
shell = 'C:\\Program Files\\Git\\bin\\bash.exe'

That wrong form can make Windows look for an executable whose path includes the quote characters, which shows up as Failed to create Surface for new tab.

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