---
sidebar_position: 3
id: "config"
title: "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
```

:::

| 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" for special Azure AI handling                                                                                                                                                                              |
| 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](https://www.electronjs.org/docs/latest/tutorial/window-customization#limitations))       |
| 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](https://www.electronjs.org/docs/latest/tutorial/window-customization#limitations)) |
| 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: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.8.8):

```json
{
  "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,
  "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!)

```json
{
  "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                                                                                                       |
