Configuration

Wave's configuration files are located at ~/.config/waveterm/.

The main configuration file is settings.json (~/.config/waveterm/settings.json).

The file is structured as a mostly flat JSON file. Instead of using sub-objects we prefer to use ":" as level separators.

info

The easiest way to edit your config files is to use the wsh editconfig command which will open your Wave config file in our built-in preview editor.

wsh editconfig

Configuration Keys

Key Name	Type	Function
app:globalhotkey	string	A systemwide keybinding to open your most recent wave window. This is a set of key names separated by :. For more info, see Customizable Systemwide Global Hotkey
app:dismissarchitecturewarning	bool	Disable warnings on app start when you are using a non-native architecture for Wave. For more info, see Why does Wave warn me about ARM64 translation when it launches?.
ai:preset	string	the default AI preset to use
ai:baseurl	string	Set the AI Base Url (must be OpenAI compatible)
ai:apitoken	string	your AI api token
ai:apitype	string	defaults to "open_ai", but can also set to "azure" (forspecial Azure AI handling), "anthropic", or "perplexity"
ai:name	string	string to display in the Wave AI block header
ai:model	string	model name to pass to API
ai:apiversion	string	for Azure AI only (when apitype is "azure", this will default to "2023-05-15")
ai:orgid	string
ai:maxtokens	int	max tokens to pass to API
ai:timeoutms	int	timeout (in milliseconds) for AI calls
conn:askbeforewshinstall	bool	set to false to disable popup asking if you want to install wsh extensions on new machines
term:fontsize	float	the fontsize for the terminal block
term:fontfamily	string	font family to use for terminal block
term:disablewebgl	bool	set to false to disable WebGL acceleration in terminal
term:localshellpath	string	set to override the default shell path for local terminals
term:localshellopts	string[]	set to pass additional parameters to the term:localshellpath (example: ["-NoLogo"] for PowerShell will remove the copyright notice)
term:copyonselect	bool	set to false to disable terminal copy-on-select
term:scrollback	int	size of terminal scrollback buffer, max is 10000
term:theme	string	preset name of terminal theme to apply by default (default is "default-dark")
term:transparency	float64	set the background transparency of terminal theme (default 0.5, 0 = not transparent, 1.0 = fully transparent)
editor:minimapenabled	bool	set to false to disable editor minimap
editor:stickyscrollenabled	bool	enables monaco editor's stickyScroll feature (pinning headers of current context, e.g. class names, method names, etc.), defaults to false
editor:wordwrap	bool	set to true to enable word wrapping in the editor (defaults to false)
markdown:fontsize	float64	font size for the normal text when rendering markdown in preview. headers are scaled up from this size, (default 14px)
markdown:fixedfontsize	float64	font size for the code blocks when rendering markdown in preview (default is 12px)
web:openlinksinternally	bool	set to false to open web links in external browser
web:defaulturl	string	default web page to open in the web widget when no url is provided (homepage)
web:defaultsearch	string	search template for web searches. e.g. https://www.google.com/search?q={query}. "{query}" gets replaced by search term
blockheader:showblockids	bool	show first 8 chars of blockid in the header
autoupdate:enabled	bool	enable/disable checking for updates (requires app restart)
autoupdate:intervalms	float64	time in milliseconds to wait between update checks (requires app restart)
autoupdate:installonquit	bool	whether to automatically install updates on quit (requires app restart)
autoupdate:channel	string	the auto update channel "latest" (stable builds), or "beta" (updated more frequently) (requires app restart)
tab:preset	string	a "bg@" preset to automatically apply to new tabs. e.g. bg@green. should match the preset key
widget:showhelp	bool	whether to show help/tips widgets in right sidebar
window:transparent	bool	set to true to enable window transparency (cannot be combined with window:blur) (macOS and Windows only, requires app restart, see note on Windows compatibility)
window:blur	bool	set to enable window background blurring (cannot be combined with window:transparent) (macOS and Windows only, requires app restart, see note on Windows compatibility)
window:opacity	float64	0-1, window opacity when window:transparent or window:blur are set
window:bgcolor	string	set the window background color (should be hex: #xxxxxx)
window:reducedmotion	bool	set to true to disable most animations
window:tilegapsize	int	set to change override default gap size (in CSS pixels) between blocks
window:magnifiedblockopacity	float64	change the opacity of a magnified block (must be between 0 and 1, defaults to 0.6)
window:magnifiedblocksize	float64	change the size of a magnified block as a percentage of the dimensions of its parent layout (must be between 0 and 1, defaults to 0.9)
window:magnifiedblockblurprimarypx	int	change the blur in CSS pixels that is applied directly behind a magnified block (see backdrop-filter for more info on how this gets applied)
window:magnifiedblockblursecondarypx	int	change the blur in CSS pixels that is applied to the visible portions of non-magnified blocks when a block is magnified (see backdrop-filter for more info on how this gets applied)
window:maxtabcachesize	int	number of tabs to cache. when tabs are cached, switching between them is very fast. (defaults to 10)
window:showmenubar	bool	set to use the OS-native menu bar (Windows and Linux only, requires app restart)
window:nativetitlebar	bool	set to use the OS-native title bar, rather than the overlay (Windows and Linux only, requires app restart)
window:disablehardwareacceleration	bool	set to disable Chromium hardware acceleration to resolve graphical bugs (requires app restart)
window:savelastwindow	bool	when true, the last window that is closed is preserved and is reopened the next time the app is launched (defaults to true)
window:confirmonclose	bool	when true, a prompt will ask a user to confirm that they want to close a window if it has an unsaved workspace with more than one tab (defaults to true)
telemetry:enabled	bool	set to enable/disable telemetry

For reference, this is the current default configuration (v0.10.4):

{
  "ai:preset": "ai@global",
  "ai:model": "gpt-4o-mini",
  "ai:maxtokens": 2048,
  "ai:timeoutms": 60000,
  "autoupdate:enabled": true,
  "autoupdate:installonquit": true,
  "autoupdate:intervalms": 3600000,
  "conn:askbeforewshinstall": true,
  "conn:wshenabled": true,
  "editor:minimapenabled": true,
  "web:defaulturl": "https://github.com/wavetermdev/waveterm",
  "web:defaultsearch": "https://www.google.com/search?q={query}",
  "window:tilegapsize": 3,
  "window:maxtabcachesize": 10,
  "window:nativetitlebar": true,
  "window:magnifiedblockopacity": 0.6,
  "window:magnifiedblocksize": 0.9,
  "window:magnifiedblockblurprimarypx": 10,
  "window:magnifiedblockblursecondarypx": 2,
  "window:confirmclose": true,
  "window:savelastwindow": true,
  "telemetry:enabled": true,
  "term:copyonselect": true
}

warning

If you installed Wave pre-v0.9.0 your configuration file will be located at ~/.waveterm/config/settings.json. This includes all of the other configuration files as well: termthemes.json, presets.json, and widgets.json.

Terminal Theming

User-defined terminal themes are located in ~/.config/waveterm/termthemes.json.

This JSON file is structured as an object, with each sub-key defining a theme. Themes are applied by right-clicking on the terminal's header bar and selecting an entry from the "Themes" sub-menu. Alternatively they can be applied to the block's metadata key term:theme. This uses the JSON key value as the identifier. Note, for best consistency all colors should be of the format "#rrggbb" or "#rrggbbaa" (aa = alpha channel for transparency).

wsh setmeta this term:theme="default-dark"

Here is an example of defining a full terminal theme. All of the built-in themes are defined here: https://github.com/wavetermdev/waveterm/blob/main/pkg/wconfig/defaultconfig/termthemes.json (if you'd like to add a popular terminal theme, please submit a PR!)

{
  "default-dark": {
    "display:name": "Default Dark",
    "display:order": 1,
    "black": "#757575",
    "red": "#cc685c",
    "green": "#76c266",
    "yellow": "#cbca9b",
    "blue": "#85aacb",
    "magenta": "#cc72ca",
    "cyan": "#74a7cb",
    "white": "#c1c1c1",
    "brightBlack": "#727272",
    "brightRed": "#cc9d97",
    "brightGreen": "#a3dd97",
    "brightYellow": "#cbcaaa",
    "brightBlue": "#9ab6cb",
    "brightMagenta": "#cc8ecb",
    "brightCyan": "#b7b8cb",
    "brightWhite": "#f0f0f0",
    "gray": "#8b918a",
    "cmdtext": "#f0f0f0",
    "foreground": "#c1c1c1",
    "selectionBackground": "",
    "background": "#00000077",
    "cursorAccent": ""
  }
}

info

You can easily open the termthemes.json config file by running:

wsh editconfig termthemes.json

Key Name	Type	ANSI FG#	ANSI BG#	Function
display:name	string			the name as it will appear in the UI context menu
display:order	float			entries in the context menu are sorted by display:order
black	CSS color	30	40	color for black
red	CSS color	31	41	color for red
green	CSS color	32	42	color for green
yellow	CSS color	33	43	color for yellow
blue	CSS color	34	44	color for blue
magenta	CSS color	35	45	color for magenta
cyan	CSS color	36	46	color for cyan
white	CSS color	37	47	color for white
brightBlack	CSS color	90	100	color for bright black
brightRed	CSS color	91	101	color for bright red
brightGreen	CSS color	92	102	color for bright green
brightYellow	CSS color	93	103	color for bright yellow
brightBlue	CSS color	94	104	color for bright blue
brightMagenta	CSS color	95	105	color for bright magenta
brightCyan	CSS color	96	106	color for bright cyan
brightWhite	CSS color	97	107	color for bright white
gray	CSS color			currently unused
cmdtext	CSS color			currently unused
foreground	CSS color			foreground color (default when no color code is applied)
background	CSS color			background color (default when no color code is applied), must have alpha channel (#rrggbbaa) if you want the terminal to be transparent
cursorAccent	CSS color			color for cursor
selectionBackground	CSS color			background color for selected text

Customizable Systemwide Global Hotkey

Wave allows settings a custom global hotkey to open your most recent window from anywhere in your computer. This has the name "app:globalhotkey" in the settings.json file and takes the form of a series of key names separated by the : character.

Examples

As a practical example, suppose you want a value of F5 as your global hotkey. Then you can simply set the value of "app:globalhotkey" to "F5" and reboot Wave to make that your global hotkey.

As a less practical example, suppose you use the combination of the keys Ctrl, Option, and e. Then the value for this keybinding would be "Ctrl:Option:e".

Allowed Key Names

We support the following key names:

• Ctrl
• Cmd
• Shift
• Alt
• Option
• Meta
• Super
• Digits (non-numpad) represented by c{Digit0} through c{Digit9}
• Letters a though z
• F keys F1 through F20
• Soft keys Soft1 through Soft4. These are essentially the same as F21 through F24.
• Space represented as either Space or a literal space   
• Enter (This is labeled as return on Mac)
• Tab
• CapsLock
• NumLock
• Backspace (This is labeled as delete on Mac)
• Delete
• Insert
• The arrow keys ArrowUp, ArrowDown, ArrowLeft, and ArrowRight
• Home
• End
• PageUp
• PageDown
• Esc
• Volume controls AudioVolumeUp, AudioVolumeDown, AudioVolumeMute
• Media controls MediaTrackNext, MediaTrackPrevious, MediaPlayPause, and MediaStop
• PrintScreen
• Numpad keys represented by c{Numpad0} through c{Numpad9}
• The numpad decimal represented by Decimal
• The numpad plus/add represented by Add
• The numpad minus/subtract represented by Subtract
• The numpad star/multiply represented by Multiply
• The numpad slash/divide represented by Divide