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
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
term:copyonselectboolset to false to disable terminal copy-on-select
term:scrollbackintsize of terminal scrollback buffer, max is 10000
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)
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)
telemetry:enabledboolset to enable/disable telemetry

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

{
"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,
"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,
"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