Skip to main content

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 NameTypeFunction
app:globalhotkeystringA 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:dismissarchitecturewarningboolDisable 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:presetstringthe default AI preset to use
ai:baseurlstringSet the AI Base Url (must be OpenAI compatible)
ai:apitokenstringyour AI api token
ai:apitypestringdefaults to "open_ai", but can also set to "azure" (forspecial Azure AI handling), "anthropic", or "perplexity"
ai:namestringstring to display in the Wave AI block header
ai:modelstringmodel name to pass to API
ai:apiversionstringfor Azure AI only (when apitype is "azure", this will default to "2023-05-15")
ai:orgidstring
ai:maxtokensintmax tokens to pass to API
ai:timeoutmsinttimeout (in milliseconds) for AI calls
conn:askbeforewshinstallboolset to false to disable popup asking if you want to install wsh extensions on new machines
term:fontsizefloatthe fontsize for the terminal block
term:fontfamilystringfont family to use for terminal block
term:disablewebglboolset to false to disable WebGL acceleration in terminal
term:localshellpathstringset to override the default shell path for local terminals
term:localshelloptsstring[]set to pass additional parameters to the term:localshellpath (example: ["-NoLogo"] for PowerShell will remove the copyright notice)
term:copyonselectboolset to false to disable terminal copy-on-select
term:scrollbackintsize of terminal scrollback buffer, max is 10000
term:themestringpreset name of terminal theme to apply by default (default is "default-dark")
term:transparencyfloat64set the background transparency of terminal theme (default 0.5, 0 = not transparent, 1.0 = fully transparent)
editor:minimapenabledboolset to false to disable editor minimap
editor:stickyscrollenabledboolenables monaco editor's stickyScroll feature (pinning headers of current context, e.g. class names, method names, etc.), defaults to false
editor:wordwrapboolset to true to enable word wrapping in the editor (defaults to false)
markdown:fontsizefloat64font size for the normal text when rendering markdown in preview. headers are scaled up from this size, (default 14px)
markdown:fixedfontsizefloat64font size for the code blocks when rendering markdown in preview (default is 12px)
web:openlinksinternallyboolset to false to open web links in external browser
web:defaulturlstringdefault web page to open in the web widget when no url is provided (homepage)
web:defaultsearchstringsearch template for web searches. e.g. https://www.google.com/search?q={query}. "{query}" gets replaced by search term
blockheader:showblockidsboolshow first 8 chars of blockid in the header
autoupdate:enabledboolenable/disable checking for updates (requires app restart)
autoupdate:intervalmsfloat64time in milliseconds to wait between update checks (requires app restart)
autoupdate:installonquitboolwhether to automatically install updates on quit (requires app restart)
autoupdate:channelstringthe auto update channel "latest" (stable builds), or "beta" (updated more frequently) (requires app restart)
tab:presetstringa "bg@" preset to automatically apply to new tabs. e.g. bg@green. should match the preset key
widget:showhelpboolwhether to show help/tips widgets in right sidebar
window:transparentboolset 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:blurboolset to enable window background blurring (cannot be combined with window:transparent) (macOS and Windows only, requires app restart, see note on Windows compatibility)
window:opacityfloat640-1, window opacity when window:transparent or window:blur are set
window:bgcolorstringset the window background color (should be hex: #xxxxxx)
window:reducedmotionboolset to true to disable most animations
window:tilegapsizeintset to change override default gap size (in CSS pixels) between blocks
window:magnifiedblockopacityfloat64change the opacity of a magnified block (must be between 0 and 1, defaults to 0.6)
window:magnifiedblocksizefloat64change 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:magnifiedblockblurprimarypxintchange 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:magnifiedblockblursecondarypxintchange 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:maxtabcachesizeintnumber of tabs to cache. when tabs are cached, switching between them is very fast. (defaults to 10)
window:showmenubarboolset to use the OS-native menu bar (Windows and Linux only, requires app restart)
window:nativetitlebarboolset to use the OS-native title bar, rather than the overlay (Windows and Linux only, requires app restart)
window:disablehardwareaccelerationboolset to disable Chromium hardware acceleration to resolve graphical bugs (requires app restart)
window:savelastwindowboolwhen true, the last window that is closed is preserved and is reopened the next time the app is launched (defaults to true)
window:confirmoncloseboolwhen 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:enabledboolset 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 NameTypeANSI FG#ANSI BG#Function
display:namestringthe name as it will appear in the UI context menu
display:orderfloatentries in the context menu are sorted by display:order
blackCSS color3040color for black
redCSS color3141color for red
greenCSS color3242color for green
yellowCSS color3343color for yellow
blueCSS color3444color for blue
magentaCSS color3545color for magenta
cyanCSS color3646color for cyan
whiteCSS color3747color for white
brightBlackCSS color90100color for bright black
brightRedCSS color91101color for bright red
brightGreenCSS color92102color for bright green
brightYellowCSS color93103color for bright yellow
brightBlueCSS color94104color for bright blue
brightMagentaCSS color95105color for bright magenta
brightCyanCSS color96106color for bright cyan
brightWhiteCSS color97107color for bright white
grayCSS colorcurrently unused
cmdtextCSS colorcurrently unused
foregroundCSS colorforeground color (default when no color code is applied)
backgroundCSS colorbackground color (default when no color code is applied), must have alpha channel (#rrggbbaa) if you want the terminal to be transparent
cursorAccentCSS colorcolor for cursor
selectionBackgroundCSS colorbackground 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