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.
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
}
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": ""
}
}
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}
throughc{Digit9}
- Letters
a
thoughz
- F keys
F1
throughF20
- Soft keys
Soft1
throughSoft4
. These are essentially the same asF21
throughF24
. - 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
, andArrowRight
Home
End
PageUp
PageDown
Esc
- Volume controls
AudioVolumeUp
,AudioVolumeDown
,AudioVolumeMute
- Media controls
MediaTrackNext
,MediaTrackPrevious
,MediaPlayPause
, andMediaStop
PrintScreen
- Numpad keys represented by
c{Numpad0}
throughc{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