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 |
|---|---|---|
| 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) or "anthropic" |
| 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 |
| term:copyonselect | bool | set to false to disable terminal copy-on-select |
| editor:minimapenabled | bool | set to false to disable editor minimap |
| editor:stickscrollenabled | bool | |
| 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) |
| 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: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) |
| telemetry:enabled | bool | set 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 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 |