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

<PlatformProvider>

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

```sh
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

```sh
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:

```sh
# 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 <Kbd k="Ctrl:Shift"/> 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.

```sh
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:

```sh
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.

```sh
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.

```sh
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.

```sh
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:

```sh
# 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.

```sh
# 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:

```sh
# 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

```sh
wsh deleteblock -b [blockid]
```

This will delete the block with the specified id.

---

## ssh

```sh
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

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

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:

```sh
wsh web open [url]
```

Alternatively, you can search with the configured search engine using:

```sh
wsh web open [search-query]
```

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.

```sh
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:

```sh
# 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

```sh
wsh conn status
```

This command gives the status of all connections made since waveterm started.

### reinstall

For ssh connections,

```sh
wsh conn reinstall [user@host]
```

For wsl connections,

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

This command reinstalls the Wave Shell Extensions on the specified connection.

### disconnect

For ssh connections,

```sh
wsh conn disconnect [user@host]
```

For wsl connections,

```sh
wsh conn disconnect [wsl://<distribution name>]
```

This command completely disconnects the specified connection. This will apply to all blocks where the connection is being used

### connect

For ssh connections,

```sh
wsh conn connect [user@host]
```

For wsl connections,

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

This command connects to the specified connection but does not create a block for it.

### ensure

For ssh connections,

```sh
wsh conn ensure [user@host]
```

For wsl connections,

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

This command connects to the specified connection if it isn't already connected.

---

## setconfig

```sh
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 across different storage systems, such as `wavefile`, `wsh` remote servers, and S3.

:::note

Wave Terminal is capable of managing files from remote SSH hosts, S3-compatible
systems, and the internal Wave filesystem. Files are addressed via URIs, which
vary depending on the storage system. If no scheme is specified, the file will be treated as a local connection.

URI format: `[profile]:[uri-scheme]://[connection]/[path]`

Supported URI schemes:

- `wsh` - Used to access files on remote hosts over SSH via the WSH helper. Allows for file streaming to Wave and other remotes.

  Profiles are optional for WSH URIs, provided that you have configured the remote host in your "connections.json" or "~/.ssh/config" file.

  If a profile is provided, it must be defined in "profiles.json" in the Wave configuration directory.

  Format: `wsh://[remote]/[path]`

  Shorthands can be used for the current remote and your local computer:
  `[path]` a relative or absolute path on the current remote
  `//[remote]/[path]` a path on a remote
  `/~/[path]` a path relative to the home directory on your local computer

- `s3` - Used to access files on S3-compatible systems.
  Requires S3 credentials to be set up, either in the AWS CLI configuration files, or in "profiles.json" in the Wave configuration directory.

  If no profile is provided, the default from your AWS CLI configuration will be used. Profiles from the AWS CLI must be prefixed with "aws:".

  Format:

  - `s3://[bucket]/[path]`
  - `aws:[profile]:s3://[bucket]/[path]`
  - `[profile]:s3://[bucket]/[path]`

- `wavefile` - Used to retrieve blockfiles from the internal Wave filesystem.

  Format: `wavefile://[zoneid]/[path]`

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

:::

### cat

```sh
wsh file cat [file-uri]
```

Display the contents of a file. For example:

```sh
wsh file cat wavefile://block/config.txt
wsh file cat wavefile://client/settings.json
```

### write

```sh
wsh file write [file-uri]
```

Write data from stdin to a file. The maximum file size is 10MB. For example:

```sh
echo "hello" | wsh file write wavefile://block/greeting.txt
cat config.json | wsh file write //ec2-user@remote01/~/config.json
```

### append

```sh
wsh file append [file-uri]
```

Append data from stdin to a file, respecting a 10MB total file size limit. This is useful for log files or accumulating data. For example:

```sh
tail -f app.log | wsh file append wavefile://block/logs.txt
echo "new line" | wsh file append wavefile://client/notes.txt
```

### rm

```sh
wsh file rm [flag] [file-uri]
```

Remove a file. For example:

```sh
wsh file rm wsh://user@ec2/home/user/config.txt
wsh file rm wavefile://client/settings.json
```

Flags:

- `-r, --recursive` - recursively deletes directory entries

### info

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

Display information about a file including size, creation time, modification time, and metadata. For example:

```sh
wsh file info wsh://user@ec2/home/user/config.txt
wsh file info wavefile://client/settings.json
```

### cp

```sh
wsh file cp [flags] [source-uri] [destination-uri]
```

Copy files between different storage systems. For example:

```sh
# Copy a wave file into your local filesystem
wsh file cp wavefile://block/config.txt ./local-config.txt

# Copy a local file into the wave filesystem
wsh file cp ./local-config.txt wavefile://block/config.txt

# Copy a remote file into the wave filesystem
wsh file cp wsh://user@ec2/home/user/config.txt wavefile://client/config.txt

# Recursively copy a directory between two remote computers
wsh file cp wsh://user@ec2-1/home/user/.config wsh://user@ec2-2/home/user/.config -r
```

Flags:

- `-r, --recursive` - copies all files in a directory recursively
- `-f, --force` - overwrites any conflicts when copying
- `-m, --merge` - does not clear existing directory entries when copying a directory, instead merging its contents with the destination's

### mv

```sh
wsh file mv [flags] [source-uri] [destination-uri]
```

Move files between different storage systems. The source file will be deleted once the operation completes successfully. For example:

```sh
# Move a wave file into your local filesystem
wsh file mv wavefile://block/config.txt ./local-config.txt

# Move a local file into the wave filesystem
wsh file mv ./local-config.txt wavefile://block/config.txt

# Move a remote file into the wave filesystem
wsh file mv wsh://user@ec2/home/user/config.txt wavefile://client/config.txt

# Recursively move a directory between two remote computers
wsh file mv wsh://user@ec2-1/home/user/.config wsh://user@ec2-2/home/user/.config -r
```

Flags:

- `-r, --recursive` - moves all files in a directory recursively
- `-f, --force` - overwrites any conflicts when moving

### ls

```sh
wsh file ls [flags] [file-uri]
```

List files in a directory. By default, lists files in the current directory for the current terminal session.

Examples:

```sh
wsh file ls wsh://user@ec2/home/user/
wsh file ls wavefile://client/configs/
```

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:

```sh
# Easy to process with grep, awk, etc.
wsh file ls wavefile://client/ | grep ".json$"
```

---

## launch

The `wsh launch` command allows you to open pre-configured widgets directly from your terminal.

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

The command will search for the specified widget ID in both user-defined widgets and default widgets, then create a new block using the widget's configuration.

Flags:

- `-m, --magnify` - open the widget in magnified mode, overriding the widget's default magnification setting

Examples:

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

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

The widget's configuration determines the initial block settings, including the view type, metadata, and default magnification state. The `-m` flag can be used to override the widget's default magnification setting.

:::tip
Widget configurations can be customized in your `widgets.json` configuration file, which you can edit using `wsh editconfig widgets.json`
:::

---

## getvar/setvar

Wave Terminal provides commands for managing persistent variables at different scopes (block, tab, workspace, or client-wide).

### setvar

```sh
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:

```sh
# 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

```sh
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:

```sh
# 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:

```sh
# 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.

## wavepath

The `wavepath` command lets you get the paths to various Wave Terminal directories and files, including configuration, data storage, and logs.

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

This command returns the full path to the requested Wave Terminal system directory or file. It's useful for accessing Wave's configuration files, data storage, or checking logs.

Flags:

- `-o, --open` - open the path in a new block
- `-O, --open-external` - open the path in the default external application
- `-t, --tail` - show the last ~100 lines of the log file (only valid for log path)

Examples:

```sh
# 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
```

The command will show you the full path to:

- `config` - Where Wave Terminal stores its configuration files
- `data` - Where Wave Terminal stores its persistent data
- `log` - The main Wave Terminal log file

:::tip
Use the `-t` flag with the log path to quickly view recent log entries without having to open the full file. This is particularly useful for troubleshooting.
:::

</PlatformProvider>
