### Start development server

Source: https://docs.waveterm.dev/wsh

Use `wsh run -m` to start a development server in a new, magnified block.

```bash
wsh run -m -- npm run dev
```

--------------------------------

### Install Wave beta via Snap

Source: https://docs.waveterm.dev/faq

Use the snap command to install the beta version of Wave on supported Linux distributions.

```bash
sudo snap install waveterm --classic --beta
```

--------------------------------

### Example bookmarks.json Configuration

Source: https://docs.waveterm.dev/config

An example of a bookmarks.json file demonstrating various bookmark configurations, including custom titles, display order, and icon URLs.

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

```

--------------------------------

### YouTube Web Widget Example

Source: https://docs.waveterm.dev/customwidgets

Example configuration for a web widget that defaults to the YouTube homepage and uses YouTube as its home page.

```json
{
    <... other widgets go here ...>,
    "youtube" : {
        "icon": "brands@youtube",
        "label": "youtube",
        "blockdef": {
            "meta": {
                "view": "web",
                "url": "https://youtube.com",
                "pinnedurl": "https://youtube.com"
            }
        }
    },
    <... other widgets go here ...>
}

```

--------------------------------

### GitHub Web Widget Example

Source: https://docs.waveterm.dev/customwidgets

Example configuration for a web widget that opens to GitHub but uses Google as its home page.

```json
{
    <... other widgets go here ...>,
    "github" : {
        "icon": "brands@github",
        "label": "github",
        "blockdef": {
            "meta": {
                "view": "web",
                "url": "https://github.com",
                "pinnedurl": "https://google.com"
            }
        }
    },
    <... other widgets go here ...>
}

```

--------------------------------

### Full AI Configuration Example

Source: https://docs.waveterm.dev/waveai-modes

This example demonstrates all available configuration fields for a custom AI endpoint. It includes settings for display, API type, model, endpoint, and capabilities.

```json
{
  "mode-key": {
    "display:name": "Display Name",
    "display:order": 1,
    "display:icon": "icon-name",
    "display:description": "Full description",
    "ai:provider": "custom",
    "ai:apitype": "openai-chat",
    "ai:model": "model-name",
    "ai:thinkinglevel": "medium",
    "ai:endpoint": "http://localhost:11434/v1/chat/completions",
    "ai:azureapiversion": "v1",
    "ai:apitoken": "your-token",
    "ai:apitokensecretname": "PROVIDER_KEY",
    "ai:azureresourcename": "your-resource",
    "ai:azuredeployment": "your-deployment",
    "ai:capabilities": ["tools", "images", "pdfs"]
  }
}
```

--------------------------------

### Full Configuration (all fields)

Source: https://docs.waveterm.dev/waveai-modes

An example showcasing all available configuration fields for maximum customization.

```APIDOC
## Full Configuration (all fields)

### Description
This configuration includes all possible fields for detailed control over AI mode settings.

### Request Body
```json
{
  "mode-key": {
    "display:name": "Display Name",
    "display:order": 1,
    "display:icon": "icon-name",
    "display:description": "Full description",
    "ai:provider": "custom",
    "ai:apitype": "openai-chat",
    "ai:model": "model-name",
    "ai:thinkinglevel": "medium",
    "ai:endpoint": "http://localhost:11434/v1/chat/completions",
    "ai:azureapiversion": "v1",
    "ai:apitoken": "your-token",
    "ai:apitokensecretname": "PROVIDER_KEY",
    "ai:azureresourcename": "your-resource",
    "ai:azuredeployment": "your-deployment",
    "ai:capabilities": ["tools", "images", "pdfs"]
  }
}
```
```

--------------------------------

### Install Wave Terminal via Snap

Source: https://docs.waveterm.dev/gettingstarted

Use the snap package manager to install Wave Terminal on supported Linux distributions.

```bash
sudo snap install --classic waveterm
```

--------------------------------

### Minimal Configuration (with Provider)

Source: https://docs.waveterm.dev/waveai-modes

A basic configuration example for connecting to an AI provider using presets.

```APIDOC
## Minimal Configuration (with Provider)

### Description
This configuration demonstrates the minimal setup required when using a predefined AI provider.

### Request Body
```json
{
  "mode-key": {
    "display:name": "Qwen (OpenRouter)",
    "ai:provider": "openrouter",
    "ai:model": "qwen/qwen-2.5-coder-32b-instruct"
  }
}
```
```

--------------------------------

### Automate Development Environment Setup with wsh

Source: https://docs.waveterm.dev/wsh

Use this script to initialize services, open project views, and trigger notifications upon build completion.

```bash
#!/bin/bash
# Setup development environment
wsh run -- docker-compose up -d
wsh web open localhost:8080
wsh view ./src
wsh run -- npm run test:watch

# Get notified when long-running tasks complete using wsh notify
npm run build && wsh notify "Build complete" || wsh notify "Build failed"
```

--------------------------------

### Background Image Configuration

Source: https://docs.waveterm.dev/tab-backgrounds

Example of configuring a background image using a URL, with specific sizing and repeat properties.

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

```

--------------------------------

### Start new AI chat with attached files

Source: https://docs.waveterm.dev/wsh

Use `wsh ai -n` to start a new, fresh AI conversation with specified files attached.

```bash
wsh ai -n *.log -m "analyze these logs"
```

--------------------------------

### Start AI Chat with Files

Source: https://docs.waveterm.dev/wsh-reference

Initiate a new AI conversation or attach files to an existing one using the wsh ai command.

```bash
wsh ai -n report.pdf data.csv -m "summarize these reports"
```

```bash
wsh ai architecture.png api-spec.pdf server.go -m "review the system design"
```

--------------------------------

### Simple Solid Color Background

Source: https://docs.waveterm.dev/tab-backgrounds

Example of a basic solid color background configuration with custom opacity and active border color.

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

```

--------------------------------

### Configure Ollama Local Model

Source: https://docs.waveterm.dev/waveai-modes

Example configuration for running a local Llama 3.3 model via Ollama.

```json
{
  "ollama-llama": {
    "display:name": "Ollama - Llama 3.3",
    "display:order": 1,
    "display:icon": "microchip",
    "display:description": "Local Llama 3.3 70B model via Ollama",
    "ai:apitype": "openai-chat",
    "ai:model": "llama3.3:70b",
    "ai:thinkinglevel": "medium",
    "ai:endpoint": "http://localhost:11434/v1/chat/completions",
    "ai:apitoken": "ollama"
  }
}
```

--------------------------------

### GET /editconfig

Source: https://docs.waveterm.dev/wsh-reference

Opens specified Wave configuration files for editing.

```APIDOC
## GET /editconfig

### Description
Opens a Wave configuration file in the editor.

### Method
GET

### Endpoint
wsh editconfig [config-file-name]

### Parameters
#### Path Parameters
- **config-file-name** (string) - Optional - The name of the config file to open (e.g., presets.json, widgets.json). Defaults to settings.json if omitted.
```

--------------------------------

### Basic AI Preset Configuration (Claude)

Source: https://docs.waveterm.dev/ai-presets

A basic example of an AI preset configuration for Claude 3 Sonnet. Replace '<your anthropic API key>' with your actual key.

```json
{
  "ai@claude-sonnet": {
    "display:name": "Claude 3 Sonnet",
    "display:order": 1,
    "ai:*": true,
    "ai:apitype": "anthropic",
    "ai:model": "claude-3-5-sonnet-latest",
    "ai:apitoken": "<your anthropic API key>"
  }
}

```

--------------------------------

### Get File Information

Source: https://docs.waveterm.dev/wsh-reference

Displays information about a file, including size, creation time, modification time, and metadata. Supports local and remote files via WSH.

```bash
wsh file info [file-uri]  

```

```bash
wsh file info wsh://user@ec2/home/user/config.txt  

```

```bash
wsh file info ./local-config.txt  

```

--------------------------------

### Append content to Wave AI sidebar

Source: https://docs.waveterm.dev/wsh-reference

Use `wsh ai` to append content to the Wave AI sidebar. Files are attached directly. Use `-m` to add a message, `-s` to auto-submit, and `-n` to start a new chat. Use '-' to read from stdin. Multiple files can be attached.

```bash
# Pipe command output to AI (ask question in UI)
git diff | wsh ai -
```

```bash
docker logs mycontainer | wsh ai -
```

```bash
# Attach files without auto-submit (review in UI first)
wsh ai main.go utils.go
```

```bash
wsh ai screenshot.png logs.txt
```

```bash
# Attach files with message
wsh ai app.py -m "find potential bugs"
```

```bash
wsh ai *.log -m "analyze these error logs"
```

```bash
# Auto-submit immediately
wsh ai config.json -s -m "explain this configuration"
```

```bash
tail -n 50 app.log | wsh ai -s - -m "what's causing these errors?"
```

--------------------------------

### Enable beta updates in settings

Source: https://docs.waveterm.dev/faq

Configure the auto-update channel to beta in the settings.json file.

```json
"autoupdate:enabled": true,
"autoupdate:channel": "beta"
```

--------------------------------

### Get a Secret

Source: https://docs.waveterm.dev/wsh-reference

Retrieve a previously stored secret using the `wsh secret get` command. Secrets are securely retrieved from your local machine, even when accessed from remote connections.

```bash
wsh secret get
```

--------------------------------

### wsh launch

Source: https://docs.waveterm.dev/wsh-reference

Opens pre-configured widgets directly from the terminal.

```APIDOC
## wsh launch

### Description
Opens pre-configured widgets directly from the terminal by searching for the specified widget ID.

### Endpoint
wsh launch [flags] widget-id

### Parameters
#### Path Parameters
- **widget-id** (string) - Required - The ID of the widget to launch.

#### Flags
- **-m, --magnify** (flag) - Optional - Open the widget in magnified mode, overriding the widget's default magnification setting.
```

--------------------------------

### Get metadata from a block

Source: https://docs.waveterm.dev/wsh

Use `wsh getmeta` to retrieve metadata, such as the file path, from a specified block.

```bash
wsh getmeta -b 2 file
```

--------------------------------

### Configure All CPU Data Sysinfo Widget

Source: https://docs.waveterm.dev/customwidgets

Create a widget to display all available CPU data, overriding the default 100-second limit. This is useful when you need to see the complete CPU activity history.

```json
{
    "<... other widgets go here ...>",
    "all-cpu" : {
        "icon": "chart-scatter",
        "label": "all-cpu",
        "blockdef": {
            "meta": {
                "view": "sysinfo",
                "sysinfo:type": "All CPU"
            }
        }
    },
    "<... other widgets go here ...>"
}
```

--------------------------------

### Get information about the current block

Source: https://docs.waveterm.dev/wsh

Use `wsh getmeta` without arguments to retrieve metadata about the current block.

```bash
wsh getmeta
```

--------------------------------

### Edit Backgrounds Configuration

Source: https://docs.waveterm.dev/tab-backgrounds

Launches the configuration file for custom backgrounds from the command line.

```bash
wsh editconfig backgrounds.json  
```

--------------------------------

### List Secrets for Troubleshooting

Source: https://docs.waveterm.dev/secrets

Verify the existence of a secret by listing all available secret names.

```bash
wsh secret list
```

--------------------------------

### Retrieve secrets with wsh secret get

Source: https://docs.waveterm.dev/wsh-reference

Access stored secrets from the system's native secure storage backend.

```bash
wsh secret get [name]
```

```bash
# Get an API key
wsh secret get github_token

# Use in scripts
export API_KEY=$(wsh secret get my_api_key)
```

--------------------------------

### Connect to WSL

Source: https://docs.waveterm.dev/wsh-reference

Connects to a local Windows Subsystem for Linux distribution.

```bash
wsh wsl [-d <distribution-name>]
```

--------------------------------

### Use stored variables in commands

Source: https://docs.waveterm.dev/wsh

Retrieve stored variables using `wsh getvar` and use them in subsequent commands, for example, in API request headers.

```bash
curl -H "Authorization: $(wsh getvar API_KEY)" https://api.example.com
```

--------------------------------

### Configuration Settings Reference

Source: https://docs.waveterm.dev/config

A comprehensive list of available configuration keys and their types for customizing the WaveTerm environment.

```APIDOC
## Configuration Settings

### Description
This reference lists the available configuration keys used to customize the behavior and appearance of the WaveTerm application.

### Parameters
#### Configuration Keys
- **editor:minimapenabled** (bool) - Set to false to disable editor minimap
- **editor:stickyscrollenabled** (bool) - Enables monaco editor's stickyScroll feature
- **editor:wordwrap** (bool) - Set to true to enable word wrapping
- **editor:fontsize** (float64) - Set the font size for the editor
- **editor:inlinediff** (bool) - Set to true to show diffs inline
- **preview:showhiddenfiles** (bool) - Set to false to disable showing hidden files
- **preview:defaultsort** (string) - Sets the default sort column for directory preview
- **markdown:fontsize** (float64) - Font size for normal text in markdown preview
- **markdown:fixedfontsize** (float64) - Font size for code blocks in markdown preview
- **web:openlinksinternally** (bool) - Set to false to open web links in external browser
- **web:defaulturl** (string) - Default web page to open
- **web:defaultsearch** (string) - Search template for web searches
- **autoupdate:enabled** (bool) - Enable/disable checking for updates
- **autoupdate:intervalms** (float64) - Time in milliseconds between update checks
- **autoupdate:installonquit** (bool) - Automatically install updates on quit
- **autoupdate:channel** (string) - Auto update channel ("latest" or "beta")
- **tab:background** (string) - A "bg@" preset to apply to new tabs
- **tab:confirmclose** (bool) - Show confirmation dialog before closing a tab
- **widget:showhelp** (bool) - Show help/tips widgets in right sidebar
- **window:transparent** (bool) - Enable window transparency
- **window:blur** (bool) - Enable window background blurring
- **window:opacity** (float64) - Window opacity (0-1)
- **window:bgcolor** (string) - Window background color (hex)
- **window:reducedmotion** (bool) - Disable most animations
- **window:tilegapsize** (int) - Override default gap size between blocks
- **window:magnifiedblockopacity** (float64) - Opacity of a magnified block
- **window:magnifiedblocksize** (float64) - Size of a magnified block as percentage
- **window:magnifiedblockblurprimarypx** (int) - Blur pixels behind a magnified block
- **window:magnifiedblockblursecondarypx** (int) - Blur pixels for non-magnified blocks
- **window:maxtabcachesize** (int) - Number of tabs to cache
- **window:showmenubar** (bool) - Use OS-native menu bar
- **window:nativetitlebar** (bool) - Use OS-native title bar
- **window:disablehardwareacceleration** (bool) - Disable Chromium hardware acceleration
- **window:fullscreenonlaunch** (bool) - Launch in fullscreen mode
- **window:savelastwindow** (bool) - Preserve last window on close
- **window:confirmonclose** (bool) - Confirm close if unsaved workspace exists
```

--------------------------------

### Manage system paths with wavepath

Source: https://docs.waveterm.dev/wsh-reference

Retrieve paths to configuration, data, or log directories and files. Supports opening paths in blocks or external applications.

```bash
wsh wavepath {config|data|log}
```

```bash
# Get path to config directory
wsh wavepath config

# Get path to data directory
wsh wavepath data

# Get path to log file
wsh wavepath log

# Open log file in a new block
wsh wavepath -o log

# Open config directory in system file explorer
wsh wavepath -O config

# View recent log entries
wsh wavepath -t log
```

--------------------------------

### Define Multiple AI Modes

Source: https://docs.waveterm.dev/waveai-modes

Configure multiple AI modes with different models and endpoints, allowing easy switching between them. This example shows configurations for Ollama and OpenAI.

```json
{
  "ollama-llama": {
    "display:name": "Ollama - Llama 3.3",
    "display:order": 1,
    "ai:model": "llama3.3:70b",
    "ai:endpoint": "http://localhost:11434/v1/chat/completions",
    "ai:apitoken": "ollama"
  },
  "ollama-codellama": {
    "display:name": "Ollama - CodeLlama",
    "display:order": 2,
    "ai:model": "codellama:34b",
    "ai:endpoint": "http://localhost:11434/v1/chat/completions",
    "ai:apitoken": "ollama"
  },
  "openai-gpt4o": {
    "display:name": "GPT-4o",
    "display:order": 10,
    "ai:provider": "openai",
    "ai:model": "gpt-4o"
  }
}
```

--------------------------------

### Connect to a Connection (WSL)

Source: https://docs.waveterm.dev/wsh-reference

Connects to the specified WSL distribution without creating a block for it.

```bash
wsh conn connect [wsl://<distribution-name>]  

```

--------------------------------

### Preview Background Metadata

Source: https://docs.waveterm.dev/customization

Print the metadata for a background configuration without applying it to the current tab.

```bash
wsh setbg --print "#ff0000"
```

--------------------------------

### Global Hotkey Configuration

Source: https://docs.waveterm.dev/config

Configure a system-wide hotkey to quickly open your most recent WaveTerm window.

```APIDOC
## Customizable Systemwide Global Hotkey

Wave allows setting a custom global hotkey to open your most recent window from anywhere on 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

*   **Single Key:** To set `F5` as your global hotkey:
    ```json
    {
      "app:globalhotkey": "F5"
    }
    ```

*   **Key Combination:** To set `Ctrl + Option + e` as your global hotkey:
    ```json
    {
      "app:globalhotkey": "Ctrl:Option:e"
    }
    ```

After modifying `settings.json`, reboot Wave for the changes to take effect.
```

--------------------------------

### Launch a widget by ID using wsh launch

Source: https://docs.waveterm.dev/wsh-reference

Use `wsh launch` to open pre-configured widgets. The command searches for the widget ID and creates a new block. Use the `-m` flag to force magnified mode.

```bash
wsh launch [flags] widget-id
```

```bash
# Launch a widget with its default settings
wsh launch my-custom-widget
```

```bash
# Launch a widget in magnified mode
wsh launch -m system-monitor
```

--------------------------------

### Get persistent variables using wsh getvar

Source: https://docs.waveterm.dev/wsh-reference

Use `wsh getvar` to retrieve variable values. It returns exit code 0 if the variable exists. Use `--all` to list all variables and `-0` for null-terminated output.

```bash
wsh getvar [flags] [key]
```

```bash
# Check if a variable exists
if wsh getvar API_KEY >/dev/null; then
    echo "API key is set"
fi
```

```bash
# Use a variable in a command
curl -H "Authorization: $(wsh getvar API_KEY)" https://api.example.com
```

```bash
# Get a block-local variable
wsh getvar -l BLOCK_SPECIFIC
```

```bash
# List all variables
wsh getvar --all
```

```bash
# List all variables with null terminators (for scripting)
wsh getvar --all -0
```

--------------------------------

### Retrieve terminal scrollback using wsh termscrollback

Source: https://docs.waveterm.dev/wsh-reference

Use `wsh termscrollback` to get terminal scrollback. Specify a block ID, line range, or use `--lastcommand` for the last command's output. Output can be saved to a file with `-o`.

```bash
wsh termscrollback [-b blockid] [flags]
```

```bash
# Get all scrollback from current terminal
wsh termscrollback
```

```bash
# Get scrollback from a specific terminal block
wsh termscrollback -b 2
```

```bash
# Get only the last command's output
wsh termscrollback --lastcommand
```

```bash
# Get a specific line range (lines 100-200)
wsh termscrollback --start 100 --end 200
```

```bash
# Save scrollback to a file
wsh termscrollback -o terminal-log.txt
```

--------------------------------

### Get metadata for blocks or tabs

Source: https://docs.waveterm.dev/wsh-reference

Use `wsh getmeta` to retrieve metadata for blocks or tabs. Specify the block using `-b` with block ID, number, or 'this'/'tab'. You can dump specific keys or sets of keys using wildcard prefixes. The default is the current terminal block.

```bash
# get the metadata for the current terminal block
wsh getmeta
```

```bash
# get the metadata for block num 2 (see block numbers by holidng down Ctrl+Shift)
wsh getmeta -b 2
```

```bash
# get the metadata for a blockid (get block ids by right clicking any block header "Copy Block Id")
wsh getmeta -b [blockid]
```

```bash
# get the metadata for a tab
wsh getmeta -b tab
```

```bash
# dump a single metadata key
wsh getmeta [-b [blockid]] [key]
```

```bash
# dump a set of keys with a certain prefix
wsh getmeta -b tab "bg:*"
```

```bash
# dump a set of keys with prefix (and include the 'clear' key)
wsh getmeta -b tab --clear-prefix "bg:*"
```

--------------------------------

### Define a Local Shell Widget

Source: https://docs.waveterm.dev/customwidgets

Configure a widget to launch a specific local shell like fish or pwsh. Ensure the shell path is accessible or provide an absolute path if it is not in the system PATH.

```json
{
    <... other widgets go here ...>,
    "fish" : {
        "icon": "fish",
        "color": "#4abc39",
        "label": "fish",
        "blockdef": {
            "meta": {
                "view": "term",
                "controller": "shell",
                "term:localshellpath": "/usr/local/bin/fish",
                "term:localshellopts": "-i -l"
            }
        }
    },
    <... other widgets go here ...>
}
```

```json
{
    <... other widgets go here ...>,
    "pwsh" : {
        "icon": "rectangle-terminal",
        "color": "#2671be",
        "label": "pwsh",
        "blockdef": {
            "meta": {
                "view": "term",
                "controller": "shell",
                "term:localshellpath": "pwsh"
            }
        }
    },
    <... other widgets go here ...>
}
```

--------------------------------

### Configure Local AI Inference Servers

Source: https://docs.waveterm.dev/waveai-modes

Use these configurations to connect to local servers. Ensure the endpoint matches the specific server's chat completion path.

```json
{
  "lmstudio-qwen": {
    "display:name": "LM Studio - Qwen",
    "display:order": 2,
    "display:icon": "server",
    "display:description": "Local Qwen model via LM Studio",
    "ai:apitype": "openai-chat",
    "ai:model": "qwen/qwen-2.5-coder-32b-instruct",
    "ai:thinkinglevel": "medium",
    "ai:endpoint": "http://localhost:1234/v1/chat/completions",
    "ai:apitoken": "not-needed"
  }
}
```

```json
{
  "vllm-local": {
    "display:name": "vLLM",
    "display:order": 3,
    "display:icon": "server",
    "display:description": "Local model via vLLM",
    "ai:apitype": "openai-chat",
    "ai:model": "your-model-name",
    "ai:thinkinglevel": "medium",
    "ai:endpoint": "http://localhost:8000/v1/chat/completions",
    "ai:apitoken": "not-needed"
  }
}
```

--------------------------------

### Local LLMs (Ollama) AI Preset Configuration

Source: https://docs.waveterm.dev/ai-presets

Connect to a local Ollama instance. The 'ai:apitoken' is required but can be any value as Ollama ignores it.

```json
{
  "ai@ollama-llama": {
    "display:name": "Ollama - Llama2",
    "display:order": 3,
    "ai:*": true,
    "ai:baseurl": "http://localhost:11434/v1",
    "ai:name": "llama2",
    "ai:model": "llama2",
    "ai:apitoken": "ollama"
  }
}

```

--------------------------------

### Define Multiple AI Presets

Source: https://docs.waveterm.dev/ai-presets

Configure various AI models with their specific settings in `ai.json`. The `display:order` key determines the order in the UI.

```json
{
  "ai@claude-sonnet": {
    "display:name": "Claude 3 Sonnet",
    "display:order": 1,
    "ai:*": true,
    "ai:apitype": "anthropic",
    "ai:model": "claude-3-5-sonnet-latest",
    "ai:apitoken": "<your anthropic API key>"
  },
  "ai@openai-gpt41": {
    "display:name": "GPT-4.1",
    "display:order": 2,
    "ai:*": true,
    "ai:model": "gpt-4.1",
    "ai:apitoken": "<your OpenAI API key>"
  },
  "ai@ollama-llama": {
    "display:name": "Ollama - Llama2",
    "display:order": 3,
    "ai:*": true,
    "ai:baseurl": "http://localhost:11434/v1",
    "ai:name": "llama2",
    "ai:model": "llama2",
    "ai:apitoken": "ollama"
  },
  "ai@perplexity-sonar": {
    "display:name": "Perplexity Sonar",
    "display:order": 4,
    "ai:*": true,
    "ai:apitype": "perplexity",
    "ai:model": "llama-3.1-sonar-small-128k-online",
    "ai:apitoken": "<your perplexity API key>"
  }
}
```

--------------------------------

### Configure 3-Minute CPU and Memory Sysinfo Widget

Source: https://docs.waveterm.dev/customwidgets

Add a custom widget to display CPU and Memory usage for the last 180 seconds. This widget is useful for monitoring short, intensive processes.

```json
{
    "<... other widgets go here ...>",
    "3min-info" : {
        "icon": "circle-3",
        "label": "3mininfo",
        "blockdef": {
            "meta": {
                "view": "sysinfo",
                "graph:numpoints": 180,
                "sysinfo:type": "CPU + Mem"
            }
        }
    },
    "<... other widgets go here ...>"
}
```

--------------------------------

### Generate Solid Color Background JSON

Source: https://docs.waveterm.dev/tab-backgrounds

Uses the `setbg` command to preview and generate the JSON for a solid color background.

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

```

--------------------------------

### Edit Configuration File

Source: https://docs.waveterm.dev/config

Open the termthemes.json configuration file directly using this command.

```shell
wsh editconfig termthemes.json  

```

--------------------------------

### Edit Configuration Files

Source: https://docs.waveterm.dev/wsh-reference

Open specific Wave configuration files for editing.

```bash
wsh editconfig [config-file-name]

# opens the default settings.json file
wsh editconfig

# opens presets.json
wsh editconfig presets.json

# opens widgets.json
wsh editconfig widgets.json

# opens ai presets
wsh editconfig presets/ai.json
```

--------------------------------

### Open a webpage in a new block

Source: https://docs.waveterm.dev/wsh

Use `wsh web open` to open a specified URL in a new web block.

```bash
wsh web open github.com
```

```bash
wsh web open "wave terminal"
```

--------------------------------

### Preview file or directory contents

Source: https://docs.waveterm.dev/wsh-reference

Use `wsh view` to open a preview block for any file or directory. Use the `-m` flag to open in magnified mode. This is useful for images, markdown, and directories, and opens a codeedit block for text/code files.

```bash
wsh view [path]
```

```bash
wsh view -m [path]           # opens in magnified block
```

--------------------------------

### Connection Issues

Source: https://docs.waveterm.dev/waveai-modes

Troubleshooting steps for when Wave cannot connect to the model server.

```APIDOC
## Connection Issues

### Description
This section provides troubleshooting steps for common connection problems encountered when Wave cannot establish a connection with your model server.

### Troubleshooting Steps
1.  **For cloud providers with `ai:provider` set**: Ensure you have the correct secret stored (e.g., `OPENAI_KEY`, `OPENROUTER_KEY`).
2.  **For local/custom endpoints**: Verify the server is running (e.g., `curl http://localhost:11434/v1/models` for Ollama).
3.  Check that the `ai:endpoint` is the complete endpoint URL, including the path (e.g., `http://localhost:11434/v1/chat/completions`).
4.  Verify that the `ai:apitype` matches your server's API (defaults are usually correct when using providers).
5.  Check firewall settings if using a non-localhost address.
```

--------------------------------

### Verifying Local Server Connection

Source: https://docs.waveterm.dev/waveai-modes

Test your local AI server connection by sending a request to its `/v1/models` endpoint. This is useful for diagnosing connection issues.

```bash
curl http://localhost:11434/v1/models
```

--------------------------------

### Configure NanoGPT Provider

Source: https://docs.waveterm.dev/waveai-modes

NanoGPT acts as a proxy service. Capabilities must be defined manually based on the specific model's supported features.

```json
{
  "nanogpt-glm47": {
    "display:name": "NanoGPT - GLM 4.7",
    "ai:provider": "nanogpt",
    "ai:model": "zai-org/glm-4.7"
  }
}
```

```json
{
  "nanogpt-glm47": {
    "display:name": "NanoGPT - GLM 4.7",
    "ai:provider": "nanogpt",
    "ai:model": "zai-org/glm-4.7",
    "ai:capabilities": ["tools"]
  }
}
```

--------------------------------

### Web Widgets Configuration

Source: https://docs.waveterm.dev/customwidgets

Configuration for creating custom web widgets that display external websites.

```APIDOC
## Web Widgets

Web widgets allow you to embed external websites directly into Waveterm. They are configured within the main widget structure.

### General Structure
```json
{
    "<widget name>": {
        "icon": "<font awesome icon name>",
        "label": "<the text label of the widget>",
        "color": "<the color of the label>",
        "blockdef": {
            "meta": {
                "view": "web",
                "url": "<url of the first webpage>",
                "pinnedurl": "<url of the homepage button>"
            }
        }
    }
}
```

### Meta Parameters for Web Widgets

- **view** (string): Must be set to `"web"` for web widgets.
- **url** (string): The initial URL to load in the web widget. Defaults to `"web:defaulturl"`.
- **pinnedurl** (string, optional): The URL the home button navigates to. Defaults to `"web:defaulturl"`.

### Example: YouTube Widget

This example creates a widget that opens to the YouTube homepage and uses YouTube as its home page.

```json
{
    "youtube" : {
        "icon": "brands@youtube",
        "label": "youtube",
        "blockdef": {
            "meta": {
                "view": "web",
                "url": "https://youtube.com",
                "pinnedurl": "https://youtube.com"
            }
        }
    }
}
```

### Example: GitHub Widget with Google Homepage

This example creates a widget that opens to GitHub but uses Google as its home page.

```json
{
    "github" : {
        "icon": "brands@github",
        "label": "github",
        "blockdef": {
            "meta": {
                "view": "web",
                "url": "https://github.com",
                "pinnedurl": "https://google.com"
            }
        }
    }
}
```
```

--------------------------------

### Reinstall Wave Shell Extensions (WSL)

Source: https://docs.waveterm.dev/wsh-reference

Use this command to reinstall the Wave Shell Extensions on a specified WSL distribution.

```bash
wsh conn reinstall [wsl://<distribution-name>]  

```

--------------------------------

### Set Configuration Option

Source: https://docs.waveterm.dev/wsh-reference

Allows setting various options in the `config/settings.json` file. It validates that a valid config option was provided.

```bash
wsh setconfig [<config-name>=<config-value>]  

```

--------------------------------

### Auto-submit files to AI with a message

Source: https://docs.waveterm.dev/wsh

Use `wsh ai` with the `-s` flag to auto-submit files and a message to the AI immediately.

```bash
wsh ai config.json -s -m "explain this config"
```

--------------------------------

### Generate Image Background JSON

Source: https://docs.waveterm.dev/tab-backgrounds

Uses the `setbg` command to preview and generate JSON for a centered image background with specified opacity.

```bash
# Preview a centered image background
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
}

```

--------------------------------

### Configure OpenAI Compatible API

Source: https://docs.waveterm.dev/waveai-modes

Manual configuration for third-party providers. The endpoint must be the full URL to the chat completions path.

```json
{
  "xai-grokfast": {
    "display:name": "xAI Grok Fast",
    "display:order": 2,
    "display:icon": "server",
    "ai:apitype": "openai-chat",
    "ai:model": "grok-4-1-fast-reasoning",
    "ai:endpoint": "https://api.x.ai/v1/chat/completions",
    "ai:apitokensecretname": "XAI_KEY",
    "ai:capabilities": ["tools", "images", "pdfs"]
  }
}
```

--------------------------------

### Configure AI Preset with Proxy

Source: https://docs.waveterm.dev/ai-presets

Route AI requests through an HTTP proxy by adding the `ai:proxyurl` setting to a preset. This is compatible with most AI providers except Wave Cloud AI.

```json
{
  "ai@claude-with-proxy": {
    "display:name": "Claude 3 Sonnet (via Proxy)",
    "display:order": 1,
    "ai:*": true,
    "ai:apitype": "anthropic",
    "ai:model": "claude-3-5-sonnet-latest",
    "ai:apitoken": "<your anthropic API key>",
    "ai:proxyurl": "http://proxy.example.com:8080"
  }
}
```

--------------------------------

### Store API Key via Command Line

Source: https://docs.waveterm.dev/waveai-modes

Securely store API keys using Wave's secret store via the command line. Replace 'OPENAI_KEY' and 'sk-xxxxxxxxxxxxxxxx' with your actual secret name and API key.

```bash
wsh secret set OPENAI_KEY=sk-xxxxxxxxxxxxxxxx
wsh secret set OPENROUTER_KEY=sk-xxxxxxxxxxxxxxxx
```

--------------------------------

### Ensure Connection is Active (WSL)

Source: https://docs.waveterm.dev/wsh-reference

Connects to the specified WSL distribution if it is not already connected.

```bash
wsh conn ensure [wsl://<distribution-name>]  

```

--------------------------------

### Configure Environment Variable Fallbacks

Source: https://docs.waveterm.dev/releasenotes

Use the $ENV:envvar:fallback syntax in configuration files to retrieve values from the environment, useful for managing secrets.

```text
$ENV:envvar:fallback
```

--------------------------------

### Set Global Hotkey

Source: https://docs.waveterm.dev/config

Configure a global hotkey to open the most recent Waveterm window. The hotkey is defined as a string of key names separated by colons.

```json
"app:globalhotkey": "F5"

```

```json
"app:globalhotkey": "Ctrl:Option:e"

```

--------------------------------

### Sysinfo Widgets Configuration

Source: https://docs.waveterm.dev/customwidgets

Configuration for creating custom sysinfo widgets to display system monitoring graphs.

```APIDOC
## Sysinfo Widgets

Sysinfo widgets display system monitoring graphs. You can customize the data displayed and the number of points shown.

### General Structure
```json
{
    "<widget name>": {
        "icon": "<font awesome icon name>",
        "label": "<the text label of the widget>",
        "color": "<the color of the label>",
        "blockdef": {
            "meta": {
                "view": "sysinfo",
                "graph:numpoints": <the max number of points in the graph>,
                "sysinfo:type": <the name of the plot collection>
            }
        }
    }
}
```

### Meta Parameters for Sysinfo Widgets

- **view** (string): Must be set to `"sysinfo"` for sysinfo widgets.
- **graph:numpoints** (integer, optional): The maximum number of data points to display on the graph. Defaults to 100.
- **sysinfo:type** (string, optional): The type of data collection to display. Valid values are `"CPU"`, `"Mem"`, `"CPU + Mem"`, and `"All CPU"`. Defaults to `"CPU"`.

### Example: Custom Sysinfo Widget

This example shows a sysinfo widget configured to display memory usage with 200 data points.

```json
{
    "memory_monitor" : {
        "icon": "fas@microchip",
        "label": "Memory Usage",
        "blockdef": {
            "meta": {
                "view": "sysinfo",
                "graph:numpoints": 200,
                "sysinfo:type": "Mem"
            }
        }
    }
}
```
```

--------------------------------

### Minimal AI Configuration with Provider

Source: https://docs.waveterm.dev/waveai-modes

Use this minimal configuration when integrating with a provider like OpenRouter. Ensure the `ai:provider` and `ai:model` fields are correctly set for your chosen service.

```json
{
  "mode-key": {
    "display:name": "Qwen (OpenRouter)",
    "ai:provider": "openrouter",
    "ai:model": "qwen/qwen-2.5-coder-32b-instruct"
  }
}
```