Skip to main content

Configuration

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

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

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

Key NameTypeFunction
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" for special Azure AI handling
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
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
editor:minimapenabledboolset to false to disable editor minimap
editor:stickscrollenabledbool
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)
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 between blocks
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.8.8):

{
"ai:model": "gpt-4o-mini",
"ai:maxtokens": 2048,
"ai:timeoutms": 60000,
"autoupdate:enabled": true,
"autoupdate:installonquit": true,
"autoupdate:intervalms": 3600000,
"editor:minimapenabled": true,
"web:defaulturl": "https://github.com/wavetermdev/waveterm",
"web:defaultsearch": "https://www.google.com/search?q={query}",
"window:tilegapsize": 3,
"telemetry:enabled": true
}

Terminal Theming

User-defined terminal themes are located in ~/.waveterm/config/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": ""
}
}
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