diff --git a/docs/docs/connections.mdx b/docs/docs/connections.mdx
index 914b72d92..4fb79ba62 100644
--- a/docs/docs/connections.mdx
+++ b/docs/docs/connections.mdx
@@ -78,4 +78,4 @@ In addition to the regular ssh config file, wave also has its own config file to
## Managing Connections with the CLI
-The `wsh` command gives some commands specifically for interacting with the connections. You can view these [here](/wsh#conn).
+The `wsh` command gives some commands specifically for interacting with the connections. You can view these [here](/wsh-reference#conn).
diff --git a/docs/docs/gettingstarted.mdx b/docs/docs/gettingstarted.mdx
index 4b0cd41e5..9330ed77f 100644
--- a/docs/docs/gettingstarted.mdx
+++ b/docs/docs/gettingstarted.mdx
@@ -7,7 +7,7 @@ title: "Getting Started"
import { PlatformProvider, PlatformSelectorButton, PlatformItem } from "@site/src/components/platformcontext.tsx";
import { Kbd } from "@site/src/components/kbd.tsx";
-Wave Terminal combines the power of a traditional terminal with modern graphical capabilities, letting you seamlessly mix CLI operations with web browsing, file previews, AI assistance, and more. This guide will help you get started.
+Wave Terminal is a modern terminal that includes graphical capabilities like web browsing, file previews, and AI assistance alongside traditional terminal features. This guide will help you get started.
## Installation
@@ -61,23 +61,24 @@ You can also download installers directly from our [Downloads page](https://www.
### Tabs and Blocks
- **Tabs**: Like browser tabs, these help organize your work. Create new tabs with .
-- **Blocks**: The building blocks of Wave. Each block can be a terminal, web browser, file preview, or other widget.
-- **Layout**: Blocks can be dragged, dropped, and resized to create your ideal workspace layout.
+- **Blocks**: The building blocks of Wave. Each block can be a terminal, web browser, file preview, AI chat, or other widget.
+- **Layout**: Blocks can be dragged, dropped, and resized to create your ideal layout.
### Key Features
-1. **Terminal Integration**
+1. **Terminal Features**
- - Full terminal emulation with modern features
- - Support for your preferred shell (bash, zsh, fish, etc.)
- - The `wsh` command provides special integration with Wave features
+ - Works with common shells (bash, zsh, fish)
+ - Supports standard terminal features (readline, control sequences, etc)
+ - Includes the `wsh` command for interacting with Wave's GUI features
+ - GPU accelerated (on most platforms)
2. **Graphical Widgets**
- - File previews (images, markdown, code with syntax highlighting)
- - Built-in web browser
- - System monitoring
- - AI assistance
+ - Preview files (images, video, markdown, code with syntax highlighting)
+ - Browse web pages
+ - Ask questions and get AI help directly from the terminal (set up multiple AI models)
+ - Basic system monitoring graphs
3. **Remote Connections**
- Easy SSH connections with the connection button
@@ -86,7 +87,7 @@ You can also download installers directly from our [Downloads page](https://www.
## Quick Start Guide
-1. **Open Your First Terminal**
+1. **Open Your First New Tab**
- New Wave tabs start with a single terminal block
- Use it just like your regular terminal
@@ -99,7 +100,7 @@ You can also download installers directly from our [Downloads page](https://www.
wsh view ~/Documents
# Open a webpage
- wsh web github.com
+ wsh web open github.com
# Get AI assistance
wsh ai "how do I find large files in my current directory?"
diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx
index 2ae1e11d8..a4bbeeba1 100644
--- a/docs/docs/index.mdx
+++ b/docs/docs/index.mdx
@@ -10,9 +10,9 @@ import { Card, CardGroup } from "@site/src/components/card.tsx";
# Welcome to Wave Terminal
-Wave is an [open-source](https://github.com/wavetermdev/waveterm) terminal that adds the ability to launch graphical widgets, controlled and integrated directly with the CLI. We support MacOS, Linux, and Windows ([Getting Started](./gettingstarted)).
+Wave is an [open-source](https://github.com/wavetermdev/waveterm) terminal that combines traditional terminal features with graphical capabilities like file previews, web browsing, and AI assistance. It runs on MacOS, Linux, and Windows ([Getting Started](./gettingstarted)).
-Wave isn't just another terminal emulator; it's a rethink on how terminals are built. For too long there has been a disconnect between the CLI and the web. If you want fast, keyboard-accessible, easy-to-write applications, you use the CLI, but if you want graphical interfaces, native widgets, copy/paste, scrolling, variable font sizes, then you'd have to turn to the web. Wave's goal is to bridge that gap.
+Modern development involves constantly switching between terminals and browsers - checking documentation, previewing files, monitoring systems, and using AI tools. Wave brings these graphical tools directly into the terminal, letting you control them from the command line. This means you can stay in your terminal workflow while still having access to the visual interfaces you need.
@@ -48,7 +48,7 @@ Wave isn't just another terminal emulator; it's a rethink on how terminals are b
description="Explore built-in tools to extend your terminal’s functionality."
/>
button in the top-right corner of the block, by right-clicking on the block header and selecting "Close Block" from the context menu, or by running the [`wsh deleteblock` command](./wsh#deleteblock). Alternatively, the currently focused block/widget can be closed by pressing
+You can delete blocks by clicking the button in the top-right corner of the block, by right-clicking on the block header and selecting "Close Block" from the context menu, or by running the [`wsh deleteblock` command](./wsh-reference#deleteblock). Alternatively, the currently focused block/widget can be closed by pressing
When you delete a block, the layout tree will be automatically adjusted to minimize the tree depth.
diff --git a/docs/docs/releasenotes.mdx b/docs/docs/releasenotes.mdx
index 2b540802e..d380b855f 100644
--- a/docs/docs/releasenotes.mdx
+++ b/docs/docs/releasenotes.mdx
@@ -11,7 +11,7 @@ sidebar_position: 200
Wave Terminal v0.10.0 introduces workspaces, making it easier to manage multiple work environments. We've added powerful new command execution capabilities with `wsh run`, allowing you to launch and control commands in dedicated blocks. This release also brings significant improvements to SSH with a new connections configuration system for managing your remote environments.
- **Workspaces**: Organize your work into separate environments, each with their own tabs, layouts, and settings
-- **Command Blocks**: New `wsh run` command for launching terminal commands in dedicated blocks, with support for magnification, auto-closing, and execution control ([docs](/wsh#run))
+- **Command Blocks**: New `wsh run` command for launching terminal commands in dedicated blocks, with support for magnification, auto-closing, and execution control ([docs](/wsh-reference#run))
- **Connections**: New configuration system for managing SSH connections, with support for wsh-free operation, per-connection themes, and more ([docs](/connections))
- Improved tab management with better switching behavior and context menus (many bug fixes)
- New tab features including pinned tabs and drag-and-drop improvements
@@ -19,7 +19,7 @@ Wave Terminal v0.10.0 introduces workspaces, making it easier to manage multiple
- Attempt wsh-free connection as a fallback if wsh installation or execution fails
- New `-i` flag to add identity files with the `wsh ssh` command
- Added Perplexity API integration ([docs](/faq#perplexity))
-- `wsh setbg` command for background handling ([docs](/wsh#setbg))
+- `wsh setbg` command for background handling ([docs](/wsh-reference#setbg))
- Switched from Less to SCSS for styling
- [bugfix] Fixed tab flickering issues during tab switches
- [bugfix] Corrected WaveAI text area resize behavior
@@ -32,8 +32,8 @@ Wave Terminal v0.10.0 introduces workspaces, making it easier to manage multiple
New minor release that introduces Wave's connected computing extensions. We've introduced new `wsh` commands that allow you to store variables and files, and access them across terminal sessions (on both local and remote machines).
-- `wsh setvar/getvar` to get and set variables -- [Docs](https://docs.waveterm.dev/wsh#getvarsetvar)
-- `wsh file` operations (cat, write, append, rm, info, cp, and ls) -- [Docs](https://docs.waveterm.dev/wsh#file)
+- `wsh setvar/getvar` to get and set variables -- [Docs](https://docs.waveterm.dev/wsh-reference#getvarsetvar)
+- `wsh file` operations (cat, write, append, rm, info, cp, and ls) -- [Docs](https://docs.waveterm.dev/wsh-reference#file)
- Improved golang panic handling to prevent backend crashes
- Improved SSH config logging and fixes a reused connection bug
- Updated telemetry to track additional counters
diff --git a/docs/docs/wsh-reference.mdx b/docs/docs/wsh-reference.mdx
new file mode 100644
index 000000000..b5c095ed5
--- /dev/null
+++ b/docs/docs/wsh-reference.mdx
@@ -0,0 +1,696 @@
+---
+sidebar_position: 4.1
+id: "wsh-reference"
+title: "wsh reference"
+---
+
+import { Kbd } from "@site/src/components/kbd.tsx";
+import { PlatformProvider, PlatformSelectorButton } from "@site/src/components/platformcontext.tsx";
+
+
+
+# wsh command
+
+The `wsh` command is always available from Wave blocks. It is a powerful tool for interacting with Wave blocks and can bridge data between your CLI and the widget GUIs.
+
+This is the detailed wsh reference documention. For an overview of `wsh` functionality, please see our [wsh command docs](/wsh).
+
+---
+
+## view
+
+You can open a preview block with the contents of any file or directory by running:
+
+```
+wsh view [path]
+```
+
+You can use this command to easily preview images, markdown files, and directories. For code/text files this will open
+a codeedit block which you can use to quickly edit the file using Wave's embedded graphical editor.
+
+---
+
+## edit
+
+```
+wsh edit [path]
+```
+
+This will open up codeedit for the specified file. This is useful for quickly editing files on a local or remote machine in our graphical editor. This command will wait until the file is closed before exiting (unlike \`view\`) so you can set your \`$EDITOR\` to \`wsh editor\` for a seamless experience. You can combine this with a \`-m\` flag to open the editor in magnified mode.
+
+---
+
+## getmeta
+
+You can view the metadata of any block or tab by running:
+
+```
+# get the metadata for the current terminal block
+wsh getmeta
+
+# get the metadata for block num 2 (see block numbers by holidng down Ctrl+Shift)
+wsh getmeta -b 2
+
+# get the metadata for a blockid (get block ids by right clicking any block header "Copy Block Id")
+wsh getmeta -b [blockid]
+
+# get the metadata for a tab
+wsh getmeta -b tab
+
+# dump a single metadata key
+wsh getmeta [-b [blockid]] [key]
+
+# dump a set of keys with a certain prefix
+wsh getmeta -b tab "bg:*"
+
+# dump a set of keys with prefix (and include the 'clear' key)
+wsh getmeta -b tab --clear-prefix "bg:*"
+```
+
+This is especially useful for preview and web blocks as you can see the file or url that they are pointing to and use that in your CLI scripts.
+
+blockid format:
+
+- `this` -- the current block (this is also the default)
+- `tab` -- the id of the current tab
+- `d6ff4966-231a-4074-b78a-20acc7226b41` -- a full blockid is a UUID
+- `a67f55a3` -- blockids may be truncated to the first 8 characters
+- `5` -- if a number less than 100 is given, it is a block number. blocks are numbered sequentially in the current tab from the top-left to bottom-right. holding will show a block number overlay.
+
+---
+
+## setmeta
+
+You can update any metadata key value pair for blocks (and tabs) by using the setmeta command. The setmeta command takes the same `-b` arguments as getmeta.
+
+```
+wsh setmeta -b [blockid] [key]=[value]
+wsh setmeta -b [blockid] file=~/myfile.txt
+wsh setmeta -b [blockid] url=https://waveterm.dev/
+
+# set the metadata for the current tab using the given json file
+wsh setmeta -b tab --json [jsonfile]
+
+# set the metadata for the current tab using a json file read from stdin
+wsh setmeta -b tab --json
+```
+
+You can get block and tab ids by right clicking on the appropriate block and selecting "Copy BlockId" (or use the block number via Ctrl:Shift). When you
+update the metadata for a preview or web block you'll see the changes reflected instantly in the block.
+
+Other useful metadata values to override block titles, icons, colors, themes, etc.
+
+Here's a complex command that will copy the background (bg:\* keys) from one tab to the current tab:
+
+```
+wsh getmeta -b [other-tab-id] "bg:*" --clear-prefix | wsh setmeta -b tab --json -
+```
+
+---
+
+## ai
+
+Send messages to new or existing AI blocks directly from the CLI. `-f` passes a file. note that there is a maximum size of 10k for messages and files, so use a tail/grep to cut down file sizes before passing. The `-f` option works great for small files though like shell scripts or `.zshrc` etc. You can use "-" to read input from stdin.
+
+By default the messages get sent to the first AI block (by blocknum). If no AI block exists, then a new one will be created. Use `-n` to force creation of a new AI block. Use `-b` to target a specific AI block.
+
+```
+wsh ai "how do i write an ls command that sorts files in reverse size order"
+wsh ai -f <(tail -n 20 "my.log") -- "any idea what these error messages mean"
+wsh ai -f README.md "help me update this readme file"
+
+# creates a new AI block
+wsh ai -n "tell me a story"
+
+# targets block number 5
+wsh ai -b 5 "tell me more"
+
+# read from stdin and also supply a message
+tail -n 50 mylog.log | wsh ai - "can you tell me what this error means?"
+```
+
+---
+
+## editconfig
+
+You can easily open up any of Wave's config files using this command.
+
+```
+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
+```
+
+---
+
+## setbg
+
+The `setbg` command allows you to set a background image or color for the current tab with various customization options.
+
+```bash
+wsh setbg [--opacity value] [--tile|--center] [--size value] (image-path|"#color"|color-name)
+```
+
+You can set a background using:
+
+- An image file (displayed as cover, tiled, or centered)
+- A hex color (must be quoted like "#ff0000")
+- A CSS color name (like "blue" or "forestgreen")
+
+Flags:
+
+- `--opacity value` - set the background opacity (0.0-1.0, default 0.5)
+- `--tile` - tile the background image instead of using cover mode
+- `--center` - center the image without scaling (good for logos)
+- `--size` - size for centered images (px, %, or auto)
+- `--clear` - remove the background
+- `--print` - show the metadata without applying it
+
+Supported image formats: JPEG, PNG, GIF, WebP, and SVG.
+
+Examples:
+
+```bash
+# Set an image background with default settings
+wsh setbg ~/pictures/background.jpg
+
+# Set a background with custom opacity
+wsh setbg --opacity 0.3 ~/pictures/light-pattern.png
+
+# Set a tiled background
+wsh setbg --tile --opacity 0.2 ~/pictures/texture.png
+
+# Center an image (good for logos)
+wsh setbg --center ~/pictures/logo.png
+wsh setbg --center --size 200px ~/pictures/logo.png
+
+# Set color backgrounds
+wsh setbg "#ff0000" # hex color (requires quotes)
+wsh setbg forestgreen # CSS color name
+
+# Change just the opacity of current background
+wsh setbg --opacity 0.7
+
+# Remove background
+wsh setbg --clear
+
+# Preview the metadata
+wsh setbg --print "#ff0000"
+```
+
+The command validates that:
+
+- Color values are valid hex codes or CSS color names
+- Image paths point to accessible, supported image files
+- The opacity value is between 0.0 and 1.0
+- The center and tile options are not used together
+
+:::tip
+Use `--print` to preview the metadata for any background configuration without applying it. You can then copy this JSON representation to use as a [Background Preset](/presets#background-configurations)
+:::
+
+---
+
+## run
+
+The `run` command creates a new terminal command block and executes a specified command within it. The command can be provided either as arguments after `--` or using the `-c` flag. Unless the `-x` or `-X` flags are passed, commands can be re-executed by pressing `Enter` once the command has finished running.
+
+```bash
+# Run a command specified after --
+wsh run -- ls -la
+
+# Run a command using -c flag
+wsh run -c "ls -la"
+
+# Run with working directory specified
+wsh run --cwd /path/to/dir -- ./script.sh
+
+# Run in magnified mode
+wsh run -m -- make build
+
+# Run and auto-close on successful completion
+wsh run -x -- npm test
+
+# Run and auto-close regardless of exit status
+wsh run -X -- ./long-running-task.sh
+```
+
+The command inherits the current environment variables and working directory by default.
+
+Flags:
+
+- `-m, --magnified` - open the block in magnified mode
+- `-c, --command string` - run a command string in _shell_
+- `-x, --exit` - close block if command exits successfully (stays open if there was an error)
+- `-X, --forceexit` - close block when command exits, regardless of exit status
+- `--delay int` - if using -x/-X, delay in milliseconds before closing block (default 2000)
+- `-p, --paused` - create block in paused state
+- `-a, --append` - append output on command restart instead of clearing
+- `--cwd string` - set working directory for command
+
+Examples:
+
+```bash
+# Run a build command in magnified mode
+wsh run -m -- npm run build
+
+# Execute a script and auto-close after success
+wsh run -x -- ./backup-script.sh
+
+# Run a command in a specific directory
+wsh run --cwd ./project -- make test
+
+# Run a shell command and force close after completion
+wsh run -X -c "find . -name '*.log' -delete"
+
+# Start a command in paused state
+wsh run -p -- ./server --dev
+
+# Run with custom close delay
+wsh run -x --delay 5000 -- ./deployment.sh
+```
+
+When using the `-x` or `-X` flags, the block will automatically close after the command completes. The `-x` flag only closes on successful completion (exit code 0), while `-X` closes regardless of exit status. The `--delay` flag controls how long to wait before closing (default 2000ms).
+
+The `-p` flag creates the block in a paused state, allowing you to review the command before execution.
+
+:::tip
+You can use either `--` followed by your command and arguments, or the `-c` flag with a quoted command string. The `--` method is preferred when you want to preserve argument handling, while `-c` is useful for shell commands with pipes or redirections.
+:::
+
+---
+
+## deleteblock
+
+```
+wsh deleteblock -b [blockid]
+```
+
+This will delete the block with the specified id.
+
+---
+
+## ssh
+
+```
+wsh ssh [user@host]
+```
+
+This will use Wave's internal ssh implementation to connect to the specified remote machine. The `-i` flag can be used to specify a path to an identity file.
+
+---
+
+## wsl
+
+```
+wsh wsl [-d ]
+```
+
+This will connect to a WSL distribution on the local machine. It will use the default if no distribution is provided.
+
+---
+
+## web
+
+You can search for a given url using:
+
+```
+wsh web open
+```
+
+Alternatively, you can search with the configured search engine using:
+
+```
+wsh web open
+```
+
+Both of these commands will open a new web block with the desired page.
+
+---
+
+## notify
+
+The `notify` command creates a desktop notification from Wave Terminal.
+
+```bash
+wsh notify [message] [-t title] [-s]
+```
+
+This allows you to trigger desktop notifications from scripts or commands. The notification will appear using your system's native notification system. It works on remote machines as well as your local machine.
+
+Flags:
+
+- `-t, --title string` - set the notification title (default "Wsh Notify")
+- `-s, --silent` - disable the notification sound
+
+Examples:
+
+```bash
+# Basic notification
+wsh notify "Build completed successfully"
+
+# Notification with custom title
+wsh notify -t "Deployment Status" "Production deployment finished"
+
+# Silent notification
+wsh notify -s "Background task completed"
+```
+
+This is particularly useful for long-running commands where you want to be notified of completion or status changes.
+
+---
+
+## conn
+
+This has several subcommands which all perform various features related to connections.
+
+### status
+
+```
+wsh conn status
+```
+
+This command gives the status of all connections made since waveterm started.
+
+### reinstall
+
+For ssh connections,
+
+```
+wsh conn reinstall [user@host]
+```
+
+For wsl connections,
+
+```
+wsh conn reinstall [wsl://]
+```
+
+This command reinstalls the Wave Shell Extensions on the specified connection.
+
+### disconnect
+
+For ssh connections,
+
+```
+wsh conn disconnect [user@host]
+```
+
+For wsl connections,
+
+```
+wsh conn disconnect [wsl://]
+```
+
+This command completely disconnects the specified connection. This will apply to all blocks where the connection is being used
+
+### connect
+
+For ssh connections,
+
+```
+wsh conn connect [user@host]
+```
+
+For wsl connections,
+
+```
+wsh conn connect [wsl://]
+```
+
+This command connects to the specified connection but does not create a block for it.
+
+### ensure
+
+For ssh connections,
+
+```
+wsh conn ensure [user@host]
+```
+
+For wsl connections,
+
+```
+wsh conn ensure [wsl://]
+```
+
+This command connects to the specified connection if it isn't already connected.
+
+---
+
+## setconfig
+
+```
+wsh setconfig [config name]=[config value]
+```
+
+This allows setting various options in the `config/settings.json` file. It will check to be sure a valid config option was provided.
+
+---
+
+## file
+
+The `file` command provides a set of subcommands for managing files stored in Wave blocks. Files are referenced using `wavefile://` URLs which specify the zone where the file is stored (e.g., `wavefile://block/mydocs.md` or `wavefile://global/myfile.txt`).
+
+### cat
+
+```bash
+wsh file cat wavefile://global/filename
+```
+
+Display the contents of a wave file. For example:
+
+```bash
+wsh file cat wavefile://block/config.txt
+wsh file cat wavefile://client/settings.json
+```
+
+### write
+
+```bash
+wsh file write wavefile://tab/filename
+```
+
+Write data from stdin to a wave file. The maximum file size is 10MB. For example:
+
+```bash
+echo "hello" | wsh file write wavefile://block/greeting.txt
+cat config.json | wsh file write wavefile://client/settings.json
+```
+
+### append
+
+```bash
+wsh file append wavefile://global/filename
+```
+
+Append data from stdin to an existing wave file, respecting the 10MB total file size limit. This is useful for log files or accumulating data. For example:
+
+```bash
+tail -f app.log | wsh file append wavefile://block/logs.txt
+echo "new line" | wsh file append wavefile://client/notes.txt
+```
+
+### rm
+
+```bash
+wsh file rm wavefile://client/filename
+```
+
+Remove a wave file. For example:
+
+```bash
+wsh file rm wavefile://block/old-config.txt
+wsh file rm wavefile://client/temp.json
+```
+
+### info
+
+```bash
+wsh file info wavefile://client/filename
+```
+
+Display information about a wave file including size, creation time, modification time, and metadata. For example:
+
+```bash
+wsh file info wavefile://block/config.txt
+wsh file info wavefile://client/settings.json
+```
+
+### cp
+
+```bash
+wsh file cp source destination
+```
+
+Copy files between wave storage and the local filesystem. Exactly one of the source or destination must be a wavefile:// URL. For example:
+
+```bash
+# Copy from wave storage to local filesystem
+wsh file cp wavefile://block/config.txt ./local-config.txt
+
+# Copy from local filesystem to wave storage
+wsh file cp ./local-config.txt wavefile://client/config.txt
+```
+
+### ls
+
+```bash
+wsh file ls [flags] [wavefile://zone/path]
+```
+
+List wave files in a zone. If no path is specified, lists all files in `wavefile://client/`.
+
+Examples:
+
+```bash
+# List all files in client zone
+wsh file ls
+
+# List files in a specific zone
+wsh file ls wavefile://block/
+wsh file ls wavefile://workspace/configs/
+
+# Show detailed file information
+wsh file ls -l wavefile://client/
+
+# List files recursively
+wsh file ls -r wavefile://block/
+
+# List one file per line (good for scripting)
+wsh file ls -1 wavefile://client/
+```
+
+Flags:
+
+- `-l, --long` - use long listing format showing size, timestamps, and metadata
+- `-r, --recursive` - list subdirectories recursively
+- `-1, --one` - list one file per line
+- `-f, --files` - list only files (no directories)
+
+When output is piped to another command, automatically switches to one-file-per-line format:
+
+```bash
+# Easy to process with grep, awk, etc.
+wsh file ls wavefile://client/ | grep ".json$"
+```
+
+:::info
+
+Note: Wave file locations can be:
+
+- `wavefile://block/...` - stored in the current block ("this" is also an alias for "block")
+- `wavefile://tab/...` - stored in the current tab
+- `wavefile://workspace/...` - stored in the current workspace ("ws" is also an alias for "workspace")
+- `wavefile://client/...` - stored globally for the client ("global" is also an alias for "client")
+- `wavefile://temp/...` - stored globally, but removed on startup/shutdown
+- `wavefile://[uuid]/...` - an entity id (can be a block, tab, workspace, etc.)
+
+All file operations respect a maximum file size of 10MB.
+
+:::
+
+---
+
+## getvar/setvar
+
+Wave Terminal provides commands for managing persistent variables at different scopes (block, tab, workspace, or client-wide).
+
+### setvar
+
+```bash
+wsh setvar [flags] KEY=VALUE...
+```
+
+Set one or more variables. By default, variables are set at the client (global) level. Use `-l` for block-local variables.
+
+Examples:
+
+```bash
+# Set a single variable
+wsh setvar API_KEY=abc123
+
+# Set multiple variables at once
+wsh setvar HOST=localhost PORT=8080 DEBUG=true
+
+# Set a block-local variable
+wsh setvar -l BLOCK_SPECIFIC=value
+
+# Remove variables
+wsh setvar -r API_KEY PORT
+```
+
+Flags:
+
+- `-l, --local` - set variables local to the current block
+- `-r, --remove` - remove the specified variables instead of setting them
+- `--varfile string` - use a different variable file (default "var")
+- `-b [blockid]` - used to set a specific zone (block, tab, workspace, client, or UUID)
+
+### getvar
+
+```bash
+wsh getvar [flags] [key]
+```
+
+Get the value of a variable. Returns exit code 0 if the variable exists, 1 if it doesn't. This allows for shell scripting like:
+
+```bash
+# Check if a variable exists
+if wsh getvar API_KEY >/dev/null; then
+ echo "API key is set"
+fi
+
+# Use a variable in a command
+curl -H "Authorization: $(wsh getvar API_KEY)" https://api.example.com
+
+# Get a block-local variable
+wsh getvar -l BLOCK_SPECIFIC
+
+# List all variables
+wsh getvar --all
+
+# List all variables with null terminators (for scripting)
+wsh getvar --all -0
+```
+
+Flags:
+
+- `-l, --local` - get variables local to the current block
+- `--all` - list all variables
+- `-0, --null` - use null terminators in output instead of newlines
+- `--varfile string` - use a different variable file (default "var")
+
+Variables can be accessed at different scopes using the `-b` flag:
+
+```bash
+# Get/set at block level
+wsh getvar -b block MYVAR
+wsh setvar -b block MYVAR=value
+
+# Get/set at tab level
+wsh getvar -b tab MYVAR
+wsh setvar -b tab MYVAR=value
+
+# Get/set at workspace level
+wsh getvar -b workspace MYVAR
+wsh setvar -b workspace MYVAR=value
+
+# Get/set at client (global) level
+wsh getvar -b client MYVAR
+wsh setvar -b client MYVAR=value
+```
+
+Variables set with these commands persist across sessions and can be used to store configuration values, secrets, or any other string data that needs to be accessible across blocks or tabs.
+
+
diff --git a/docs/docs/wsh.mdx b/docs/docs/wsh.mdx
index e27f79c92..7bf389092 100644
--- a/docs/docs/wsh.mdx
+++ b/docs/docs/wsh.mdx
@@ -1,656 +1,172 @@
---
sidebar_position: 4
id: "wsh"
-title: "wsh command"
+title: "wsh overview"
---
-import { Kbd } from "@site/src/components/kbd.tsx";
-import { PlatformProvider, PlatformSelectorButton } from "@site/src/components/platformcontext.tsx";
+The `wsh` command provides Wave Terminal's core command line interface, allowing users to interact with both terminal and graphical elements from the command line. This guide covers the basics of using `wsh` and its key features.
-
+See the [wsh reference](/wsh-reference) for a list of all wsh commands and their arguments.
-# wsh command
+## Overview
-The `wsh` command is always available from Wave blocks. It is a powerful tool for interacting with Wave blocks and can bridge data between your CLI and the widget GUIs.
+At its core, `wsh` enables seamless interaction between your terminal commands and Wave's graphical blocks. It allows you to:
----
+- Control graphical widgets directly from the command line
+- Share data between terminal sessions and GUI components
+- Manage your workspace programmatically
+- Connect remote and local environments
+- Send CLI output and files directly to AI conversations
+- Run terminal commands in separate, isolated blocks
-## view
+## Key Concepts
-You can open a preview block with the contents of any file or directory by running:
+### Interacting with Blocks
-```
-wsh view [path]
-```
-
-You can use this command to easily preview images, markdown files, and directories. For code/text files this will open
-a codeedit block which you can use to quickly edit the file using Wave's embedded graphical editor.
-
----
-
-## edit
-
-```
-wsh edit [path]
-```
-
-This will open up codeedit for the specified file. This is useful for quickly editing files on a local or remote machine in our graphical editor. This command will wait until the file is closed before exiting (unlike \`view\`) so you can set your \`$EDITOR\` to \`wsh editor\` for a seamless experience. You can combine this with a \`-m\` flag to open the editor in magnified mode.
-
----
-
-## getmeta
-
-You can view the metadata of any block or tab by running:
-
-```
-# get the metadata for the current terminal block
-wsh getmeta
-
-# get the metadata for block num 2 (see block numbers by holidng down Ctrl+Shift)
-wsh getmeta -b 2
-
-# get the metadata for a blockid (get block ids by right clicking any block header "Copy Block Id")
-wsh getmeta -b [blockid]
-
-# get the metadata for a tab
-wsh getmeta -b tab
-
-# dump a single metadata key
-wsh getmeta [-b [blockid]] [key]
-
-# dump a set of keys with a certain prefix
-wsh getmeta -b tab "bg:*"
-
-# dump a set of keys with prefix (and include the 'clear' key)
-wsh getmeta -b tab --clear-prefix "bg:*"
-```
-
-This is especially useful for preview and web blocks as you can see the file or url that they are pointing to and use that in your CLI scripts.
-
-blockid format:
-
-- `this` -- the current block (this is also the default)
-- `tab` -- the id of the current tab
-- `d6ff4966-231a-4074-b78a-20acc7226b41` -- a full blockid is a UUID
-- `a67f55a3` -- blockids may be truncated to the first 8 characters
-- `5` -- if a number less than 100 is given, it is a block number. blocks are numbered sequentially in the current tab from the top-left to bottom-right. holding will show a block number overlay.
-
----
-
-## setmeta
-
-You can update any metadata key value pair for blocks (and tabs) by using the setmeta command. The setmeta command takes the same `-b` arguments as getmeta.
-
-```
-wsh setmeta -b [blockid] [key]=[value]
-wsh setmeta -b [blockid] file=~/myfile.txt
-wsh setmeta -b [blockid] url=https://waveterm.dev/
-
-# set the metadata for the current tab using the given json file
-wsh setmeta -b tab --json [jsonfile]
-
-# set the metadata for the current tab using a json file read from stdin
-wsh setmeta -b tab --json
-```
-
-You can get block and tab ids by right clicking on the appropriate block and selecting "Copy BlockId" (or use the block number via Ctrl:Shift). When you
-update the metadata for a preview or web block you'll see the changes reflected instantly in the block.
-
-Other useful metadata values to override block titles, icons, colors, themes, etc.
-
-Here's a complex command that will copy the background (bg:\* keys) from one tab to the current tab:
-
-```
-wsh getmeta -b [other-tab-id] "bg:*" --clear-prefix | wsh setmeta -b tab --json -
-```
-
----
-
-## ai
-
-Send messages to new or existing AI blocks directly from the CLI. `-f` passes a file. note that there is a maximum size of 10k for messages and files, so use a tail/grep to cut down file sizes before passing. The `-f` option works great for small files though like shell scripts or `.zshrc` etc.
-
-By default the messages get sent to the first AI block (by blocknum). If no AI block exists, then a new one will be created. Use `-n` to force creation of a new AI block. Use `-b` to target a specific AI block.
-
-```
-wsh ai "how do i write an ls command that sorts files in reverse size order"
-wsh ai -f <(tail -n 20 "my.log") -- "any idea what these error messages mean"
-wsh ai -f README.md "help me update this readme file"
-
-# creates a new AI block
-wsh ai -n "tell me a story"
-
-# targets block number 5
-wsh ai -b 5 "tell me more"
-```
-
----
-
-## editconfig
-
-You can easily open up any of Wave's config files using this command.
-
-```
-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
-```
-
----
-
-## setbg
-
-The `setbg` command allows you to set a background image or color for the current tab with various customization options.
+`wsh` provides direct interaction with Wave's graphical blocks through the command line. For example:
```bash
-wsh setbg [--opacity value] [--tile|--center] [--size value] (image-path|"#color"|color-name)
+# Open a file in the editor
+wsh edit config.json
+
+# Get the current file path from a preview block
+wsh getmeta -b 2 file
+
+# Send output to an AI assistant (the "-" reads from stdin)
+ls -la | wsh ai - "what are the largest files here?"
```
-You can set a background using:
+### Persistent State
-- An image file (displayed as cover, tiled, or centered)
-- A hex color (must be quoted like "#ff0000")
-- A CSS color name (like "blue" or "forestgreen")
-
-Flags:
-
-- `--opacity value` - set the background opacity (0.0-1.0, default 0.5)
-- `--tile` - tile the background image instead of using cover mode
-- `--center` - center the image without scaling (good for logos)
-- `--size` - size for centered images (px, %, or auto)
-- `--clear` - remove the background
-- `--print` - show the metadata without applying it
-
-Supported image formats: JPEG, PNG, GIF, WebP, and SVG.
-
-Examples:
+`wsh` can maintain state across terminal sessions through its variable and file storage system:
```bash
-# Set an image background with default settings
-wsh setbg ~/pictures/background.jpg
-
-# Set a background with custom opacity
-wsh setbg --opacity 0.3 ~/pictures/light-pattern.png
-
-# Set a tiled background
-wsh setbg --tile --opacity 0.2 ~/pictures/texture.png
-
-# Center an image (good for logos)
-wsh setbg --center ~/pictures/logo.png
-wsh setbg --center --size 200px ~/pictures/logo.png
-
-# Set color backgrounds
-wsh setbg "#ff0000" # hex color (requires quotes)
-wsh setbg forestgreen # CSS color name
-
-# Change just the opacity of current background
-wsh setbg --opacity 0.7
-
-# Remove background
-wsh setbg --clear
-
-# Preview the metadata
-wsh setbg --print "#ff0000"
-```
-
-The command validates that:
-
-- Color values are valid hex codes or CSS color names
-- Image paths point to accessible, supported image files
-- The opacity value is between 0.0 and 1.0
-- The center and tile options are not used together
-
-:::tip
-Use `--print` to preview the metadata for any background configuration without applying it. You can then copy this JSON representation to use as a [Background Preset](/presets#background-configurations)
-:::
-
----
-
-## run
-
-The `run` command creates a new terminal command block and executes a specified command within it. The command can be provided either as arguments after `--` or using the `-c` flag. Unless the `-x` or `-X` flags are passed, commands can be re-executed by pressing `Enter` once the command has finished running.
-
-```bash
-# Run a command specified after --
-wsh run -- ls -la
-
-# Run a command using -c flag
-wsh run -c "ls -la"
-
-# Run with working directory specified
-wsh run --cwd /path/to/dir -- ./script.sh
-
-# Run in magnified mode
-wsh run -m -- make build
-
-# Run and auto-close on successful completion
-wsh run -x -- npm test
-
-# Run and auto-close regardless of exit status
-wsh run -X -- ./long-running-task.sh
-```
-
-The command inherits the current environment variables and working directory by default.
-
-Flags:
-
-- `-m, --magnified` - open the block in magnified mode
-- `-c, --command string` - run a command string in _shell_
-- `-x, --exit` - close block if command exits successfully (stays open if there was an error)
-- `-X, --forceexit` - close block when command exits, regardless of exit status
-- `--delay int` - if using -x/-X, delay in milliseconds before closing block (default 2000)
-- `-p, --paused` - create block in paused state
-- `-a, --append` - append output on command restart instead of clearing
-- `--cwd string` - set working directory for command
-
-Examples:
-
-```bash
-# Run a build command in magnified mode
-wsh run -m -- npm run build
-
-# Execute a script and auto-close after success
-wsh run -x -- ./backup-script.sh
-
-# Run a command in a specific directory
-wsh run --cwd ./project -- make test
-
-# Run a shell command and force close after completion
-wsh run -X -c "find . -name '*.log' -delete"
-
-# Start a command in paused state
-wsh run -p -- ./server --dev
-
-# Run with custom close delay
-wsh run -x --delay 5000 -- ./deployment.sh
-```
-
-When using the `-x` or `-X` flags, the block will automatically close after the command completes. The `-x` flag only closes on successful completion (exit code 0), while `-X` closes regardless of exit status. The `--delay` flag controls how long to wait before closing (default 2000ms).
-
-The `-p` flag creates the block in a paused state, allowing you to review the command before execution.
-
-:::tip
-You can use either `--` followed by your command and arguments, or the `-c` flag with a quoted command string. The `--` method is preferred when you want to preserve argument handling, while `-c` is useful for shell commands with pipes or redirections.
-:::
-
----
-
-## deleteblock
-
-```
-wsh deleteblock -b [blockid]
-```
-
-This will delete the block with the specified id.
-
----
-
-## ssh
-
-```
-wsh ssh [user@host]
-```
-
-This will use Wave's internal ssh implementation to connect to the specified remote machine. The `-i` flag can be used to specify a path to an identity file.
-
----
-
-## wsl
-
-```
-wsh wsl [-d ]
-```
-
-This will connect to a WSL distribution on the local machine. It will use the default if no distribution is provided.
-
----
-
-## web
-
-You can search for a given url using:
-
-```
-wsh web
-```
-
-Alternatively, you can search with the configured search engine using:
-
-```
-wsh web
-```
-
-Both of these commands will open a new web block with the desired page.
-
----
-
-## conn
-
-This has several subcommands which all perform various features related to connections.
-
-### status
-
-```
-wsh conn status
-```
-
-This command gives the status of all connections made since waveterm started.
-
-### reinstall
-
-For ssh connections,
-
-```
-wsh conn reinstall [user@host]
-```
-
-For wsl connections,
-
-```
-wsh conn reinstall [wsl://]
-```
-
-This command reinstalls the Wave Shell Extensions on the specified connection.
-
-### disconnect
-
-For ssh connections,
-
-```
-wsh conn disconnect [user@host]
-```
-
-For wsl connections,
-
-```
-wsh conn disconnect [wsl://]
-```
-
-This command completely disconnects the specified connection. This will apply to all blocks where the connection is being used
-
-### connect
-
-For ssh connections,
-
-```
-wsh conn connect [user@host]
-```
-
-For wsl connections,
-
-```
-wsh conn connect [wsl://]
-```
-
-This command connects to the specified connection but does not create a block for it.
-
-### ensure
-
-For ssh connections,
-
-```
-wsh conn ensure [user@host]
-```
-
-For wsl connections,
-
-```
-wsh conn ensure [wsl://]
-```
-
-This command connects to the specified connection if it isn't already connected.
-
----
-
-## setconfig
-
-```
-wsh setconfig [config name]=[config value]
-```
-
-This allows setting various options in the `config/settings.json` file. It will check to be sure a valid config option was provided.
-
----
-
-## file
-
-The `file` command provides a set of subcommands for managing files stored in Wave blocks. Files are referenced using `wavefile://` URLs which specify the zone where the file is stored (e.g., `wavefile://block/mydocs.md` or `wavefile://global/myfile.txt`).
-
-### cat
-
-```bash
-wsh file cat wavefile://global/filename
-```
-
-Display the contents of a wave file. For example:
-
-```bash
-wsh file cat wavefile://block/config.txt
-wsh file cat wavefile://client/settings.json
-```
-
-### write
-
-```bash
-wsh file write wavefile://tab/filename
-```
-
-Write data from stdin to a wave file. The maximum file size is 10MB. For example:
-
-```bash
-echo "hello" | wsh file write wavefile://block/greeting.txt
-cat config.json | wsh file write wavefile://client/settings.json
-```
-
-### append
-
-```bash
-wsh file append wavefile://global/filename
-```
-
-Append data from stdin to an existing wave file, respecting the 10MB total file size limit. This is useful for log files or accumulating data. For example:
-
-```bash
-tail -f app.log | wsh file append wavefile://block/logs.txt
-echo "new line" | wsh file append wavefile://client/notes.txt
-```
-
-### rm
-
-```bash
-wsh file rm wavefile://client/filename
-```
-
-Remove a wave file. For example:
-
-```bash
-wsh file rm wavefile://block/old-config.txt
-wsh file rm wavefile://client/temp.json
-```
-
-### info
-
-```bash
-wsh file info wavefile://client/filename
-```
-
-Display information about a wave file including size, creation time, modification time, and metadata. For example:
-
-```bash
-wsh file info wavefile://block/config.txt
-wsh file info wavefile://client/settings.json
-```
-
-### cp
-
-```bash
-wsh file cp source destination
-```
-
-Copy files between wave storage and the local filesystem. Exactly one of the source or destination must be a wavefile:// URL. For example:
-
-```bash
-# Copy from wave storage to local filesystem
-wsh file cp wavefile://block/config.txt ./local-config.txt
-
-# Copy from local filesystem to wave storage
-wsh file cp ./local-config.txt wavefile://client/config.txt
-```
-
-### ls
-
-```bash
-wsh file ls [flags] [wavefile://zone/path]
-```
-
-List wave files in a zone. If no path is specified, lists all files in `wavefile://client/`.
-
-Examples:
-
-```bash
-# List all files in client zone
-wsh file ls
-
-# List files in a specific zone
-wsh file ls wavefile://block/
-wsh file ls wavefile://workspace/configs/
-
-# Show detailed file information
-wsh file ls -l wavefile://client/
-
-# List files recursively
-wsh file ls -r wavefile://block/
-
-# List one file per line (good for scripting)
-wsh file ls -1 wavefile://client/
-```
-
-Flags:
-
-- `-l, --long` - use long listing format showing size, timestamps, and metadata
-- `-r, --recursive` - list subdirectories recursively
-- `-1, --one` - list one file per line
-- `-f, --files` - list only files (no directories)
-
-When output is piped to another command, automatically switches to one-file-per-line format:
-
-```bash
-# Easy to process with grep, awk, etc.
-wsh file ls wavefile://client/ | grep ".json$"
-```
-
-:::info
-
-Note: Wave file locations can be:
-
-- `wavefile://block/...` - stored in the current block ("this" is also an alias for "block")
-- `wavefile://tab/...` - stored in the current tab
-- `wavefile://workspace/...` - stored in the current workspace ("ws" is also an alias for "workspace")
-- `wavefile://client/...` - stored globally for the client ("global" is also an alias for "client")
-- `wavefile://temp/...` - stored globally, but removed on startup/shutdown
-- `wavefile://[uuid]/...` - an entity id (can be a block, tab, workspace, etc.)
-
-All file operations respect a maximum file size of 10MB.
-
-:::
-
----
-
-## getvar/setvar
-
-Wave Terminal provides commands for managing persistent variables at different scopes (block, tab, workspace, or client-wide).
-
-### setvar
-
-```bash
-wsh setvar [flags] KEY=VALUE...
-```
-
-Set one or more variables. By default, variables are set at the client (global) level. Use `-l` for block-local variables.
-
-Examples:
-
-```bash
-# Set a single variable
+# Store a variable that persists across sessions
wsh setvar API_KEY=abc123
-# Set multiple variables at once
-wsh setvar HOST=localhost PORT=8080 DEBUG=true
+# Store globally
+wsh setvar DEPLOY_ENV=prod
+# Or store in the current workspace
+wsh setvar -b workspace DEPLOY_ENV=staging
-# Set a block-local variable
-wsh setvar -l BLOCK_SPECIFIC=value
-
-# Remove variables
-wsh setvar -r API_KEY PORT
-```
-
-Flags:
-
-- `-l, --local` - set variables local to the current block
-- `-r, --remove` - remove the specified variables instead of setting them
-- `--varfile string` - use a different variable file (default "var")
-- `-b [blockid]` - used to set a specific zone (block, tab, workspace, client, or UUID)
-
-### getvar
-
-```bash
-wsh getvar [flags] [key]
-```
-
-Get the value of a variable. Returns exit code 0 if the variable exists, 1 if it doesn't. This allows for shell scripting like:
-
-```bash
-# Check if a variable exists
-if wsh getvar API_KEY >/dev/null; then
- echo "API key is set"
-fi
-
-# Use a variable in a command
+# Use stored variables in commands
curl -H "Authorization: $(wsh getvar API_KEY)" https://api.example.com
-# Get a block-local variable
-wsh getvar -l BLOCK_SPECIFIC
+# Store a file that can be accessed from any block
+echo "data" | wsh file write wavefile://global/config.txt
-# List all variables
-wsh getvar --all
-
-# List all variables with null terminators (for scripting)
-wsh getvar --all -0
+# Append logs from multiple terminals
+echo "Terminal 1 log" | wsh file append wavefile://workspace/logs.txt
```
-Flags:
+### Block Management
-- `-l, --local` - get variables local to the current block
-- `--all` - list all variables
-- `-0, --null` - use null terminators in output instead of newlines
-- `--varfile string` - use a different variable file (default "var")
-
-Variables can be accessed at different scopes using the `-b` flag:
+Every visual element in Wave is a block, and `wsh` gives you complete control over them (hold Ctrl+Shift to see block numbers):
```bash
-# Get/set at block level
-wsh getvar -b block MYVAR
-wsh setvar -b block MYVAR=value
+# Create a new block showing a webpage
+wsh web open github.com
-# Get/set at tab level
-wsh getvar -b tab MYVAR
-wsh setvar -b tab MYVAR=value
+# Do a web search in a new block
+wsh web open "wave terminal"
-# Get/set at workspace level
-wsh getvar -b workspace MYVAR
-wsh setvar -b workspace MYVAR=value
+# Run a command in a new block and auto-close when done
+wsh run -x -- npm test
-# Get/set at client (global) level
-wsh getvar -b client MYVAR
-wsh setvar -b client MYVAR=value
+# Get information about the current block
+wsh getmeta
```
-Variables set with these commands persist across sessions and can be used to store configuration values, secrets, or any other string data that needs to be accessible across blocks or tabs.
+## Common Workflows
-
+Here are some common ways to use `wsh`:
+
+### Development Workflow
+
+```bash
+# Open directory or markdown files
+wsh view .
+wsh view README.md
+
+# add a -m to open the block in "magnified" mode
+wsh view -m README.md
+
+# Start development server in a new block (-m will magnify the block on startup)
+wsh run -m -- npm run dev
+
+# Open documentation in a web block
+wsh web open http://localhost:3000
+```
+
+### Remote Development
+
+```bash
+# Connect to remote server with optional key
+wsh ssh -i ~/.ssh/mykey.pem dev@server
+
+# Edit remote files
+wsh edit /etc/nginx/nginx.conf
+
+# Monitor remote logs
+wsh run -- tail -f /var/log/app.log
+
+# Share variables between sessions
+wsh setvar -b tab SHARED_ENV=staging
+```
+
+### AI-Assisted Development
+
+```bash
+# Get AI help with code (uses "-" to read from stdin)
+git diff | wsh ai - "review these changes"
+
+# Get help with a file
+wsh ai -f .zshrc "help me add ~/bin to my path"
+
+# Debug issues (uses "-" to read from stdin)
+dmesg | wsh ai - "help me understand these errors"
+```
+
+## Tips & Features
+
+1. **Working with Blocks**
+
+ - Use block numbers (1-9) to target specific blocks within a tab (hold Ctrl+Shift to see block numbers)
+ - Can get full block ids by right click a block's header and selecting "Copy Block Id" (useful for scripting)
+ - Use references like "this", "tab", "workspace", or "global" for different scopes
+
+2. **Data Storage**
+
+ - Use `wsh setvar/getvar` for configuration and secrets
+ - Store file data using `wsh file`, which can be easily referenced in all terminals (local and remote)
+ - Use appropriate storage scopes (block, tab, workspace, global)
+
+3. **Command Execution**
+ - Use `wsh run` to execute commands in new blocks
+ - Send command output and files quickly to AI blocks with `wsh ai`
+
+## Scripting with wsh
+
+wsh commands can be combined in scripts to automate common tasks. Here's an example that sets up a development environment and uses `wsh notify` to monitor a long-running build:
+
+```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"
+```
+
+## Getting Help
+
+You can get help on available commands by running `wsh` with no arguments, or get detailed help for a specific command using `wsh [command] -h`.
+
+For a complete reference of all `wsh` functionality, see the [WSH Command Reference](./wsh-reference).
+
+```
+
+```