The wsh Command
wsh is the command-line companion to Termia. It talks to the same wavesrv backend the
graphical app talks to, so a lot of what you'd otherwise do by clicking — opening a file
preview, creating a terminal, reading a value another pane stored, firing a notification — you
can also do from a shell prompt. It is the bridge between your terminal and the app's panes,
tabs and windows.
Where it runs
wsh is already on your PATH in every terminal pane you open, whether that pane is running
locally on this Mac or connected to a remote host over SSH. You don't install or configure
anything yourself.
- The binary. Termia ships prebuilt
wshbinaries for the platforms it supports, one per OS/architecture, alongsidewavesrvin the app's bundled resources. On a normal install that's inside the.appbundle; the app locates them relative towavesrvat startup, the same lookup that findswavesrvitself. - Local terminals. Termia copies the right
wshbinary into its own data directory and injects that directory ontoPATHthrough the shell startup files it manages for zsh, bash and fish. These run before your own.zshrc/.bashrc, sowshis there from the first prompt in a new pane. - Remote hosts (SSH). The first time you connect to a host, Termia checks it for an
existing, current
wshand, if it's missing, copies the matching binary for that host's OS/architecture over the same SSH session and drops it at~/.termia/bin/wsh. From then on, every pane connected to that host haswshon itsPATHtoo.
To see where wsh and its data actually live, ask it rather than guessing a path:
wsh wavepath config # settings.json and friends
wsh wavepath data # the wsh binary, shell integration files, local block storage
wsh wavepath log # the wavesrv log file
wsh wavepath log --tail # last 100 lines of the log
On a remote host
The remote copy lives at ~/.termia/bin/wsh. Termia only re-pushes it automatically when your
app's version is newer than the version already sitting on the host — a plain version compare,
not a content check. That means if the shell-integration files it writes alongside wsh (rc
snippets, PATH setup) ever change without a version bump, a host you've already connected to
once won't pick up the new copy on its own.
For that case there's a manual action: open a terminal pane connected to that host, click its gear icon, and choose Reinstall remote wsh… (this item only appears for remote panes — there's nothing to reinstall on your local machine). It re-transfers the binary and rewrites the rc files over the existing SSH session; new terminals on that host pick up the refreshed integration, and terminals already open are unaffected. See The pane title bar for where this sits among the rest of the gear menu.
The same thing is available from the command line, useful for scripting or for a connection you're not looking at right now:
wsh conn ensure myuser@myhost # install wsh if it's missing or out of date
wsh conn reinstall myuser@myhost # force a reinstall regardless of version
wsh conn status # see every connection and whether wsh is current
If wsh is missing at startup
Termia checks for a bundled wsh binary when it starts. If none is found, a persistent
notification appears — "Some features are unavailable" — saying: "The remote shell component
wsh is missing; SSH features won't be available." This is a warning, not a startup failure: the
app still opens and local terminals still work, but connecting to a remote host won't be able to
install shell integration there. It means the install is damaged — reinstall the app to restore
it. See Troubleshooting for the other startup and connection banners
Termia shows.
Referring to a pane
Most wsh commands act on a pane, tab, or window, and take a -b/--block flag to say which
one — the flag is still called --block because it addresses the same backend object a pane is
built from. Leave it out and the command uses the pane your terminal is running in. -b accepts
several shorthand forms:
| Value | Meaning |
|---|---|
this (default) | The pane your terminal is running in |
tab | The current tab |
workspace (or ws) | The current window (Termia calls a window's identity a workspace) |
client (or global) | Client-wide scope, shared across every window |
5 | The 5th pane in the current tab, numbered top-left to bottom-right |
tab:2 | The 2nd tab in the current window |
term or term:2 | The 1st (or 2nd) pane whose view is term in the current tab |
a67f55a3 | A pane/tab id truncated to its first 8 characters |
d6ff4966-231a-4074-b78a-20acc7226b41 | A full id |
Hold ⌃⇧ to show the pane-number overlay in the top-left corner of every pane in the current
tab, so you can match a number to the pane you mean before you type it.
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 pane
wsh web open https://example.com
# Open a new terminal in a directory
wsh term ./myproject
# Run a command in its own pane, and close the pane once it exits cleanly
wsh run -x -- npm test
Metadata, variables, and files on a pane
# See everything wavesrv knows about the pane you're typing in
wsh getmeta
# See it for pane number 3 instead
wsh getmeta -b 3
# Read one key
wsh getmeta file
# Change the connection a pane 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 pane, local or remote, can read
echo "hello" | wsh file write wavefile://client/greeting.txt
wsh file cat wavefile://client/greeting.txt
Connections
# See every SSH connection and whether it's currently connected
wsh conn status
# List saved hosts (Vault entries plus ad-hoc addresses) together
wsh server list
# Connect this terminal to a remote host
wsh ssh myuser@myhost
# Open a new terminal already attached to a saved host, using its stored password if it has one
wsh server open myuser@myhost
See Hosts for how a host gets into that list in the first place, and Plugins for installing tools (including agentic CLIs) onto whichever machine a pane is connected to.
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"
Typing tt inside any terminal pane starts Termia Agent interactively in that pane. 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 pane, and starts the agent with an initial prompt.
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
How wsh talks back to the app
A few wsh commands don't just ask wavesrv for data — they ask the running app itself to do
something, over the same connection the app uses for everything else. On macOS that request is
answered by exactly the same set of commands as the Windows/Linux app implements, so nothing here
is missing relative to the other platform:
wsh notify— shows a system notification (and the same event also lands in the in-app Notifications panel).- focusing a window — used internally when a command needs to bring a particular window to the front, opening it first if it isn't already open.
- the update channel query behind
wsh version -v— on macOS this always answersnone, since this build doesn't yet have an auto-update channel; on Windows/Linux it can report a real channel. It's a real answer, not an error, just a different one. - the CSS-selector query behind
wsh web get— evaluated against the actual web pane's page content, the same as on the other platform.
Any command outside that set that tries to reach the app directly gets an explicit error back —
not a silent no-op and not a multi-second timeout — naming the command it doesn't recognize. In
practice this only affects internal/experimental commands; the ones in the tour above don't touch
this path at all (they create or query objects through wavesrv directly, which works
identically regardless of which app is running).
Getting help

Every command supports -h/--help, and running wsh with no arguments prints the full command
list. wsh version prints the CLI's version; wsh version -v also prints your config and data
directories and the update channel you're on.
Next steps
- wsh Reference — the full command list, with every flag.
- Hosts — where the hosts
wsh serverandwsh connoperate on come from, and how connecting works. - Files and Transfers — the SFTP view and transfer centre
wsh fileshares its backend with. - Plugins — installing terminal tools onto this Mac or a remote host.
- Troubleshooting — the backend and connection banners Termia shows when something's wrong.