Waveterm

AI-integrated open-source terminal with persistent sessions, inline graphics, and remote connection management.

Installation

Platform Installation

Command	Description
brew install --cask wave	Install on macOS with Homebrew
Download from waveterm.dev	Install from official website
Download .deb or .rpm from releases	Install on Linux
Download .exe installer from releases	Install on Windows
wsh version	Show Wave CLI version
wsh help	Show available wsh commands

Basic Usage

Tab and Window Management

Command	Description
Cmd/Ctrl + N	Open new terminal tab
Cmd/Ctrl + T	Open new workspace tab
Cmd/Ctrl + W	Close current tab
Cmd/Ctrl + Shift + N	Open new window
Cmd/Ctrl + 1-9	Switch to tab by number
Cmd/Ctrl + Shift + ]	Next tab
Cmd/Ctrl + Shift + [	Previous tab
Cmd/Ctrl + Shift + T	Reopen last closed tab

Block and Pane Management

Command	Description
Cmd/Ctrl + Shift + D	Split terminal horizontally
Cmd/Ctrl + D	Split terminal vertically
Click and drag block borders	Resize terminal panes
Alt + Arrow keys	Navigate between blocks
Cmd/Ctrl + Enter	Maximize/restore current block
Cmd/Ctrl + Shift + P	Open command palette
Cmd/Ctrl + Backspace	Close current block

AI Features

AI Chat

Command	Description
Cmd/Ctrl + Space	Open AI chat in current block
Type question in AI chat	Ask AI about commands or code
/explain in AI chat	Explain previous command output
/fix in AI chat	Suggest fix for last error
/summarize in AI chat	Summarize long output
Click “Apply” on AI suggestion	Insert suggested command into terminal
Esc	Close AI chat panel

AI Provider Configuration

Command	Description
Configure AI model in settings	Choose between OpenAI, Anthropic, local models
Set ai:preset in config	Switch between AI providers
Set ai:apitoken in config	Configure API key for AI provider
Set ai:model in config	Specify model name (e.g., gpt-4, claude-3)
Set ai:baseurl in config	Point to custom/local API endpoint
Set ai:maxtokens in config	Set maximum response tokens

AI Configuration Example

{
  "ai:preset": "custom",
  "ai:apitoken": "sk-...",
  "ai:baseurl": "https://api.openai.com/v1",
  "ai:model": "gpt-4",
  "ai:maxtokens": 2048
}

For local models using Ollama:

{
  "ai:preset": "custom",
  "ai:baseurl": "http://localhost:11434/v1",
  "ai:model": "llama3",
  "ai:maxtokens": 4096
}

SSH Connections

SSH Operations

Command	Description
wsh ssh user@hostname	Connect to remote host via SSH
wsh ssh user@host -i ~/.ssh/key	SSH with specific identity key
wsh ssh -p 2222 user@host	SSH on custom port
Click ”+” then “SSH Connection”	Create SSH connection from UI
Connections persist across sessions	Sessions survive app restart
wsh ssh-import	Import SSH config connections
Configure ~/.ssh/config entries	Auto-discover SSH hosts
Right-click connection then Reconnect	Reconnect dropped SSH session

SSH Config Integration

Wave reads your SSH config for host discovery. Configure entries for seamless connections:

Host prod-web
    HostName 10.0.1.50
    User deploy
    IdentityFile ~/.ssh/deploy_key
    Port 22

Host staging-*
    HostName %h.staging.example.com
    User admin
    IdentityFile ~/.ssh/staging_key
    ForwardAgent yes

Host jump-box
    HostName bastion.example.com
    User ops
    IdentityFile ~/.ssh/ops_key

Host internal-*
    ProxyJump jump-box
    User admin
    IdentityFile ~/.ssh/internal_key

Remote File Browsing

Command	Description
wsh view remote:file.txt	View file on remote host
wsh edit remote:file.txt	Edit file on remote host inline
wsh view remote:/var/log/syslog	View remote log file
wsh run --remote user@host -- command	Run command on remote host in new block

Widgets & Blocks

File and Content Viewing

Command	Description
wsh view file.png	View image inline in terminal
wsh view file.jpg	View JPEG image inline
wsh view file.svg	View SVG graphic inline
wsh view file.md	Render markdown inline
wsh view file.csv	Display CSV as table
wsh view file.json	Display JSON with syntax highlighting
wsh view file.pdf	Preview PDF document
wsh view https://example.com	Embed web page in block

Block Operations

Command	Description
wsh edit file.txt	Open file in inline editor
wsh edit --lang=python script.py	Open editor with language mode
wsh getmeta	Get current block metadata
wsh setmeta key=value	Set block metadata
wsh run -- command args	Run command in new block
wsh run --magnify -- htop	Run command in maximized block
wsh createblock	Create an empty block
wsh createblock --tabid=tab1	Create block in specific tab

Widget Usage Patterns

Command	Description
wsh view --magnify file.png	View image in maximized block
wsh view --height=20 file.csv	View with specific block height
Drag and drop files onto Wave	View files directly
wsh view .	Browse current directory
wsh view ~/projects	Browse specific directory

Customization

Appearance Settings

Command	Description
Open Settings then Appearance	Change theme and colors
Open Settings then Terminal	Configure font, size, cursor
Set term:fontsize in config	Set terminal font size
Set term:fontfamily in config	Set terminal font family
Set term:theme in config	Set terminal color theme
Set term:cursorstyle in config	Set cursor style (block, bar, underline)
Set window:transparent in config	Enable window transparency
Set window:blur in config	Enable background blur
Set window:opacity in config	Set window opacity level
Set telemetry:enabled = false	Disable telemetry

Terminal Appearance Configuration

{
  "term:fontsize": 14,
  "term:fontfamily": "JetBrains Mono, Menlo, monospace",
  "term:theme": "dracula",
  "term:cursorstyle": "bar",
  "term:scrollback": 10000,
  "window:transparent": true,
  "window:blur": true,
  "window:opacity": 0.92
}

Custom Theme Configuration

{
  "term:theme": "custom",
  "term:localtheme": {
    "black": "#282a36",
    "red": "#ff5555",
    "green": "#50fa7b",
    "yellow": "#f1fa8c",
    "blue": "#bd93f9",
    "magenta": "#ff79c6",
    "cyan": "#8be9fd",
    "white": "#f8f8f2",
    "brightBlack": "#6272a4",
    "brightRed": "#ff6e6e",
    "brightGreen": "#69ff94",
    "brightYellow": "#ffffa5",
    "brightBlue": "#d6acff",
    "brightMagenta": "#ff92df",
    "brightCyan": "#a4ffff",
    "brightWhite": "#ffffff",
    "background": "#282a36",
    "foreground": "#f8f8f2",
    "cursor": "#f8f8f2",
    "selectionBackground": "#44475a"
  }
}

Keyboard Shortcuts

Navigation

Command	Description
Cmd/Ctrl + Shift + P	Command palette
Cmd/Ctrl + L	Clear terminal
Cmd/Ctrl + Shift + E	Toggle sidebar
Cmd/Ctrl + K	Focus search
Cmd/Ctrl + Shift + F	Global search
Alt + Arrow keys	Navigate between blocks
Cmd/Ctrl + Enter	Maximize/restore current block
Cmd/Ctrl + ,	Open settings

Editing and Clipboard

Command	Description
Cmd/Ctrl + Shift + C	Copy from terminal
Cmd/Ctrl + Shift + V	Paste into terminal
Cmd/Ctrl + A	Select all in block
Cmd/Ctrl + F	Find in current block
Shift + Page Up	Scroll up in terminal
Shift + Page Down	Scroll down in terminal
Cmd/Ctrl + Home	Scroll to top of buffer
Cmd/Ctrl + End	Scroll to bottom of buffer

Block Management

Command	Description
Cmd/Ctrl + D	Split vertically
Cmd/Ctrl + Shift + D	Split horizontally
Cmd/Ctrl + Backspace	Close current block
Cmd/Ctrl + Enter	Toggle block maximize
Alt + Up/Down/Left/Right	Move focus between blocks
Cmd/Ctrl + Shift + Arrow	Resize current block

Configuration

Configuration Management

Command	Description
wsh getvar key	Get configuration variable
wsh setvar key=value	Set configuration variable
wsh getvar --all	List all configuration variables
Config stored in ~/.waveterm/	Default configuration directory
Set autoupdate:enabled in config	Enable/disable auto-updates
Set conn:askbeforewshinstall in config	Prompt before installing wsh on remote
Set editor:minimap in config	Toggle minimap in inline editor
Set web:openlinksinternally in config	Open links in Wave browser block

Full Configuration Example

{
  "term:fontsize": 13,
  "term:fontfamily": "Fira Code, monospace",
  "term:theme": "one-dark",
  "term:cursorstyle": "block",
  "term:scrollback": 5000,
  "window:transparent": false,
  "window:blur": false,
  "telemetry:enabled": false,
  "autoupdate:enabled": true,
  "conn:askbeforewshinstall": true,
  "editor:minimap": false,
  "web:openlinksinternally": true,
  "ai:preset": "openai",
  "ai:model": "gpt-4",
  "ai:maxtokens": 2048
}

Environment Variables

Command	Description
WAVETERM_HOME=~/.waveterm	Override Wave config directory
WAVETERM_DEV=1	Enable development mode
TERM_PROGRAM=waveterm	Automatically set in Wave sessions
WAVETERM_BLOCKID	Current block ID (set per block)
WAVETERM_TABID	Current tab ID (set per tab)

Workspace Management

Workspaces

Command	Description
Click workspace name in sidebar	Switch between workspaces
Right-click workspace then Rename	Rename a workspace
Create new workspace from sidebar	Add a fresh workspace
Drag tabs between workspaces	Reorganize tabs
Workspaces persist across restarts	All state is saved automatically

Session Persistence

Command	Description
Terminal history persists	Command output saved across sessions
SSH connections auto-reconnect	Remote sessions restored on restart
Block layout saved per tab	Pane arrangements preserved
Working directories remembered	Each block remembers its cwd
Scroll position maintained	Return to where you left off

Best Practices

1. Use blocks for multitasking — split your terminal into blocks to monitor logs, run builds, and edit code side by side.

2. Leverage AI for unfamiliar commands — press Cmd/Ctrl + Space to ask the AI assistant about syntax, flags, or troubleshooting.

3. Configure SSH config for quick access — add all your servers to ~/.ssh/config so Wave auto-discovers them in the connection menu.

4. Use inline viewers for quick inspection — wsh view lets you preview images, CSVs, and markdown without leaving the terminal.

5. Pin common blocks — maximize important blocks with Cmd/Ctrl + Enter when focusing on a task, then restore the layout when done.

6. Disable telemetry if preferred — set telemetry:enabled to false in your configuration for privacy.

7. Use workspaces for projects — create separate workspaces for different projects to keep context organized.

8. Use -dev suffix for AI model config — point ai:baseurl to a local Ollama or LM Studio instance for private, offline AI assistance.

9. Learn the block keyboard shortcuts — Alt + Arrow for navigation and Cmd/Ctrl + Shift + D for splitting are the most commonly used shortcuts.

10. Customize your theme — set up a custom color theme using term:localtheme to match your preferred editor colors for a consistent experience.