Presets

Wave's preset system allows you to save and apply multiple configuration settings at once. Presets are used for:

• Tab backgrounds: Apply visual styles to your tabs

Managing Presets

You can store presets in two locations:

• ~/.config/waveterm/presets.json: Main presets file
• ~/.config/waveterm/presets/: Directory for organizing presets into separate files

All presets are aggregated regardless of which file they're in, so you can use the presets directory to organize them (e.g., presets/bg.json).

info

You can easily edit your presets using the built-in editor:

wsh editconfig presets.json        # Edit main presets file
wsh editconfig presets/bg.json     # Edit background presets

File Format

Presets follow this format:

{
  "<preset-type>@<preset-key>": {
    "display:name": "<Preset name>",
    "display:order": "<number>", // optional
    "<overridden-config-key-1>": "<overridden-config-value-1>"
    ...
  }
}

The preset-type determines where the preset appears in Wave's interface:

• bg: Appears in the "Backgrounds" submenu when right-clicking a tab

Common Keys

Key Name	Type	Function
display:name	string	Name shown in the UI menu (required)
display:order	float	Controls the order in the menu (optional)

info

When a preset is applied, it overrides the default configuration values for that tab or block. Using bg:* will clear any previously overridden values, setting them back to defaults. It's recommended to include this key in your presets to ensure a clean slate.

Background Presets

Wave's background system harnesses the full power of CSS backgrounds, letting you create rich visual effects through the "background" attribute. You can apply solid colors, gradients (both linear and radial), images, and even blend multiple elements together.

Configuration Keys

Key Name	Type	Function
bg:*	bool	Reset all existing bg keys (recommended to prevent any existing background settings from carrying over)
bg	string	CSS background attribute for the tab (supports colors, gradients images, etc.)
bg:opacity	float	The opacity of the background (defaults to 0.5)
bg:blendmode	string	The blend mode of the background
bg:bordercolor	string	The color of the border when a block is not active (rarely used)
bg:activebordercolor	string	The color of the border when a block is active

Examples

Simple solid color:

{
  "bg@blue": {
    "display:name": "Blue",
    "bg:*": true,
    "bg": "blue",
    "bg:opacity": 0.3,
    "bg:activebordercolor": "rgba(0, 0, 255, 1.0)"
  }
}

Complex gradient:

{
  "bg@duskhorizon": {
    "display:name": "Dusk Horizon",
    "bg:*": true,
    "bg": "linear-gradient(0deg, rgba(128,0,0,1) 0%, rgba(204,85,0,0.7) 20%, rgba(255,140,0,0.6) 45%, rgba(160,90,160,0.5) 65%, rgba(60,60,120,1) 100%), radial-gradient(circle at 30% 30%, rgba(255,255,255,0.1), transparent 60%), radial-gradient(circle at 70% 70%, rgba(255,255,255,0.05), transparent 70%)",
    "bg:opacity": 0.9,
    "bg:blendmode": "overlay"
  }
}

Background image:

{
  "bg@ocean": {
    "display:name": "Ocean Scene",
    "bg:*": true,
    "bg": "url('/path/to/ocean.jpg') center/cover no-repeat",
    "bg:opacity": 0.2
  }
}

info

Background images support both URLs and local file paths. For better reliability, we recommend using local files. Local paths must be absolute or start with ~ (e.g., ~/Downloads/background.png). We support common web formats: PNG, JPEG/JPG, WebP, GIF, and SVG.

tip

The setbg command can help generate background preset JSON:

# Preview a solid color preset
wsh setbg --print "#ff0000"
{
  "bg:*": true,
  "bg": "#ff0000",
  "bg:opacity": 0.5
}

# Preview a centered image preset
wsh setbg --print --center --opacity 0.3 ~/logo.png
{
  "bg:*": true,
  "bg": "url('/absolute/path/to/logo.png') no-repeat center/auto",
  "bg:opacity": 0.3
}

Just add the required display:name field to complete your preset!