Skip to main content

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 wsh binaries for the platforms it supports, one per OS/architecture, alongside wavesrv in the app's bundled resources. On a normal install that's inside the .app bundle; the app locates them relative to wavesrv at startup, the same lookup that finds wavesrv itself.
  • Local terminals. Termia copies the right wsh binary into its own data directory and injects that directory onto PATH through the shell startup files it manages for zsh, bash and fish. These run before your own .zshrc/.bashrc, so wsh is 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 wsh and, 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 has wsh on its PATH too.

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:

ValueMeaning
this (default)The pane your terminal is running in
tabThe 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
5The 5th pane in the current tab, numbered top-left to bottom-right
tab:2The 2nd tab in the current window
term or term:2The 1st (or 2nd) pane whose view is term in the current tab
a67f55a3A pane/tab id truncated to its first 8 characters
d6ff4966-231a-4074-b78a-20acc7226b41A 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 answers none, 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​

Check help from the installed helper before applying commands from another version.
Check help from the installed helper before applying commands from another version.View full size ↗

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 server and wsh conn operate on come from, and how connecting works.
  • Files and Transfers — the SFTP view and transfer centre wsh file shares 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.