Skip to main content

wsh overview

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 for a list of all wsh commands and their arguments.

Overview​

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

Key Concepts​

Interacting with Blocks​

wsh provides direct interaction with Wave's graphical blocks through the command line. For example:

# 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?"

Persistent State​

wsh can maintain state across terminal sessions through its variable and file storage system:

# Store a variable that persists across sessions
wsh setvar API_KEY=abc123

# Store globally
wsh setvar DEPLOY_ENV=prod
# Or store in the current workspace
wsh setvar -b workspace DEPLOY_ENV=staging

# Use stored variables in commands
curl -H "Authorization: $(wsh getvar API_KEY)" https://api.example.com

# Store a file that can be accessed from any block
echo "data" | wsh file write wavefile://global/config.txt

# Append logs from multiple terminals
echo "Terminal 1 log" | wsh file append wavefile://workspace/logs.txt

Block Management​

Every visual element in Wave is a block, and wsh gives you complete control over them (hold Ctrl+Shift to see block numbers):

# Create a new block showing a webpage
wsh web open github.com

# Do a web search in a new block
wsh web open "wave terminal"

# Run a command in a new block and auto-close when done
wsh run -x -- npm test

# Get information about the current block
wsh getmeta

Common Workflows​

Here are some common ways to use wsh:

Development Workflow​

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

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

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

#!/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.