Skip to main content

wsh Command

wsh is the command-line companion to Termia. It talks to the same wavesrv backend that drives the graphical app, so anything you can do by clicking — opening a file preview, creating a terminal, reading a variable a different block stored, connecting to a host — you can also do from a shell prompt. It is the bridge between your terminal commands and Termia's blocks, tabs, and workspaces.

Where it runs​

wsh is already on your PATH in every terminal block you open, on your local machine and on any remote host you connect to over SSH or WSL. You do not install or configure anything to get it — Termia sets it up automatically.

  • Local terminals: Termia copies the wsh binary into its own data directory and injects that directory onto PATH through the shell startup files it manages for zsh, bash, fish, and PowerShell. This happens before your regular .zshrc/.bashrc runs.
  • Remote hosts (SSH): the first time you connect to a host, Termia probes it for an existing wsh and, if it is missing, copies the right binary for that host's OS/architecture to ~/.termia/bin/wsh over the same SSH session. From then on, every terminal block connected to that host has wsh on its PATH too. If installation ever fails or gets out of date, you can force it with wsh conn ensure or wsh conn reinstall.
  • WSL: the same mechanism applies to wsl:// connections.

To find where wsh and its data actually live on your machine, ask wsh itself rather than guessing a path:

wsh wavepath config   # settings.json, presets.json, widgets.json, ...
wsh wavepath data     # the wsh binary, shell integration files, local block storage
wsh wavepath log      # the wavesrv log file
wsh wavepath log --tail   # print the last 100 lines of the log

Referring to blocks​

Most wsh commands act on a block, tab, or workspace, and take a -b/--block flag to say which one. If you leave it out, the command uses the block your terminal is running in. -b accepts several shorthand forms:

ValueMeaning
this (default)The block your terminal is running in
tabThe current tab
workspace (or ws)The current workspace
client (or global)Client-wide scope, shared across every window
5The 5th block in the current tab, numbered top-left to bottom-right
tab:2The 2nd tab in the current workspace
term or term:2The 1st (or 2nd) block whose view is term in the current tab
a67f55a3A block/tab id truncated to its first 8 characters
d6ff4966-231a-4074-b78a-20acc7226b41A full id

Hold Ctrl+Shift (same physical key on macOS, Windows, and Linux) to show the block-number overlay on every block in the current tab, or right-click a block's header and choose Copy BlockId to get its full id for scripting.

A tour of the most useful commands​

Open things​

# Preview or edit a file (directories, images, markdown, and code all work)
wsh view ./README.md
wsh view .

# Force the graphical editor, and wait until it's closed (handy as $EDITOR)
wsh edit ./notes.txt

# Open a URL in a web block
wsh web open https://example.com

# Open a new terminal in a directory
wsh term ./myproject

# Run a command in its own block, and close the block once it exits cleanly
wsh run -x -- npm test

Metadata, variables, and files on a block​

# See everything wavesrv knows about the block you're typing in
wsh getmeta

# See it for block number 3 instead
wsh getmeta -b 3

# Read one key
wsh getmeta file

# Change the connection a block is using
wsh setmeta -b 3 connection=myhost

# Store a value that survives restarts, scoped to the whole client
wsh setvar DEPLOY_ENV=staging

# Read it back from any terminal
echo $(wsh getvar DEPLOY_ENV)

# Stash a file that any block, local or remote, can read
echo "hello" | wsh file write wavefile://client/greeting.txt
wsh file cat wavefile://client/greeting.txt

Connections and servers​

# See every SSH/WSL connection and whether it's currently connected
wsh conn status

# List saved servers (Vault hosts plus ad-hoc connections.json entries) together
wsh server list

# Connect this terminal to a remote host
wsh ssh myuser@myhost

# Open a new terminal already attached to a saved server, using its Vault password if it has one
wsh server open myuser@myhost

See Hosts and Vaults for how servers get into that list in the first place, and Connections for the connection lifecycle in more depth.

Termia Agent from the command line​

# Open a new terminal on a remote host and hand it straight to Termia Agent with a task
wsh task myuser@myhost "check disk usage and clean up anything in /tmp older than a week"

Inside any terminal block, typing tt and pressing Enter starts Termia Agent interactively in that block. wsh task does the same thing in one step for a host you haven't opened a terminal on yet — it makes sure the connection is up, opens a terminal, and starts the agent with an initial prompt. See Termia Agent for what the agent can do once it's running.

Everything else​

# Set a tab's background image or color
wsh setbg ./wallpaper.jpg
wsh setbg "#1a1a2e"
wsh setbg --clear

# Fire a desktop notification from a script
long-build-command && wsh notify "Build finished"

# Launch a configured widget by its id
wsh launch sysinfo

Getting help​

Use the installed helper help to confirm available commands and flags.
Use the installed helper help to confirm available commands and flags.View full size ↗

Every command supports -h/--help, and running wsh with no arguments prints the full command list. wsh version prints the version of the CLI; wsh version -v also prints your config and data directories and the update channel you're on.

Next steps​