import { Kbd } from "@site/src/components/kbd"; import { PlatformProvider, PlatformSelectorButton } from "@site/src/components/platformcontext"; import { VersionBadge, DeprecatedBadge } from "@site/src/components/versionbadge";

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

:::

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

{
    "ai:preset": "ai@global",
    "ai:model": "gpt-5-mini",
    "ai:maxtokens": 4000,
    "ai:timeoutms": 60000,
    "app:defaultnewblock": "term",
    "app:confirmquit": true,
    "app:hideaibutton": false,
    "app:disablectrlshiftarrows": false,
    "app:disablectrlshiftdisplay": false,
    "app:focusfollowscursor": "off",
    "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:fullscreenonlaunch": false,
    "window:magnifiedblockblursecondarypx": 2,
    "window:confirmclose": true,
    "window:savelastwindow": true,
    "telemetry:enabled": true,
    "term:bellsound": false,
    "term:bellindicator": false,
    "term:osc52": "always",
    "term:cursor": "block",
    "term:cursorblink": false,
    "term:copyonselect": true,
    "term:durable": false,
    "waveai:showcloudmodes": true,
    "waveai:defaultmode": "waveai@balanced",
    "preview:defaultsort": "name"
}

:::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.

:::

To avoid putting secrets directly in config files, Wave supports environment variable resolution using $ENV:VARIABLE_NAME or $ENV:VARIABLE_NAME:fallback syntax. This works for any string value in any config file (settings.json, presets.json, ai.json, etc.).

{
  "ai:apitoken": "$ENV:OPENAI_APIKEY",
  "ai:baseurl": "$ENV:AI_BASEURL:https://api.openai.com/v1"
}

WebBookmarks allows you to store and manage web links with customizable display preferences. The bookmarks are stored in a JSON file (bookmarks.json) as a key-value map where the key (id) is an arbitrary identifier for the bookmark. By convention, you should start your ids with "bookmark@". In the web widget, you can pull up your bookmarks using

Each bookmark follows this structure (only url is required):

{
  "url": "https://example.com",
  "title": "Example Site",
  "iconurl": "https://example.com/custom-icon.png",
  "display:order": 1
}

{
  "bookmark@google": {
    "url": "https://www.google.com",
    "title": "Google"
  },
  "bookmark@claude": {
    "url": "https://claude.ai",
    "title": "Claude AI"
  },
  "bookmark@wave": {
    "url": "https://waveterm.dev",
    "title": "Wave Terminal",
    "display:order": -1
  },
  "bookmark@wave-github": {
    "url": "https://github.com/wavetermdev/waveterm",
    "title": "Wave Github",
    "iconurl": "https://github.githubassets.com/favicons/favicon-dark.png"
  },
  "bookmark@chatgpt": {
    "url": "https://chatgpt.com",
    "iconurl": "https://cdn.oaistatic.com/assets/favicon-miwirzcw.ico"
  },
  "bookmark@wave-pulls": {
    "url": "https://github.com/wavetermdev/waveterm/pulls",
    "title": "Wave Pull Requests",
    "iconurl": "https://github.githubassets.com/favicons/favicon-dark.png"
  }
}

• If iconurl is set, it fetches the icon from the specified URL instead of the site's default favicon.
• Bookmarks are sorted based on display:order (if provided), otherwise by id.
• icon and iconcolor are rarely needed since the default behavior fetches the site's favicon.
• favicons are refreshed every 24-hours

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

:::

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.

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".

We support the following key names:

• Ctrl
• Cmd
• Shift
• Alt
• Option
• Meta
• Super
• Digits (non-numpad) represented by c{Digit0} through c{Digit9}
• Letters a though z
• F keys F1 through F20
• Soft keys Soft1 through Soft4. These are essentially the same as F21 through F24.
• 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, and ArrowRight
• Home
• End
• PageUp
• PageDown
• Esc
• Volume controls AudioVolumeUp, AudioVolumeDown, AudioVolumeMute
• Media controls MediaTrackNext, MediaTrackPrevious, MediaPlayPause, and MediaStop
• PrintScreen
• Numpad keys represented by c{Numpad0} through c{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