Terminal State Bar

Since WebSSH 29.3 a "State Bar" is available at the top (iOS / iPadOS) or bottom (macOS) of the terminal. It displays near real-time information about the current session: built-in items provided by WebSSH, and your own items written in JavaScript.

In this section

This page: how the State Bar works, how to show / hide it, and how to compose it.
JavaScript API: everything your own items can use ($ssh, $mosh, $terminal, $vars, console).
Examples: ready to paste items.

Anatomy of the State Bar

From left to right:

Menu button (waveform icon): opens the State Bar menu (Refresh, Pause / Resume, hide the bar, Help, Restart, Customize). It is the only fixed element: it always sits on the left and cannot be removed.
Your list of items, in the order you chose, scrolling horizontally when they do not fit: system items, built-in items, layout items and your own items. On macOS and iPadOS with a pointer, the item under the cursor is highlighted. An item can be tinted (orange, red, green), carry a badge, a progress ring or a sparkline, and has its own appearance.

Until 32.10 the connection information, the progress and the recording button were fixed next to the menu button. They are now ordinary items: move them, restyle them or remove them.

Show or hide the State Bar

The State Bar is enabled by default. Three levels control it:

Global setting: Settings → Advanced Settings → SSH → State Bar Strategy: Visible (shown when the terminal opens), Hidden (available, but hidden until you show it) or Disabled (never available).
Per connection: the State Bar option in the terminal section of the connection form: Inherit (use the global setting), Enabled, Hidden or Disabled.
In the terminal: the State Bar entry of the terminal menu (⋯) toggles the bar for the current session, and the bar's own menu can hide it too.

One more setting lives next to State Bar Strategy:

State Bar Background Color: use the terminal selection color (default) or the terminal background color. The foreground color is adjusted automatically when the contrast is not sufficient.

The former Recording Button setting is gone: keep or remove the Recording item in your list instead.

Not available for every session

The State Bar is not available when the session goes through a jump host ("Connect Through"), nor on Telnet sessions. It is available on SSH and mosh sessions.

Compose the State Bar

Go to Settings → Terminal → State Bar (or tap Customize in the State Bar menu of any terminal).
Use the add button (top right):
- Add: create your own item, written in JavaScript (see below).
- Built-in Items: pick an item provided by WebSSH (see below).
- WebSSH Library: import a ready-made item from the library.
Drag the handles to reorder the items. Long press (or right click) an item to delete it.

Free version

Without WebSSH PRO the list holds up to 10 items, every row included (system items, separators and spaces too); the count is shown under the list. Once the limit is reached the add button opens the PRO upgrade. Nothing is ever removed or locked: a longer list coming from iCloud stays complete and editable, only adding is limited. WebSSH PRO removes the limit.

The ⋯ menu offers Export Items… and Import Items…, to save the whole list in a JSON file and load it back, on another account or to share a setup. The export contains every item in order with its appearance and settings; built-in items are stored as references, your own items with their script. An import first checks the file, then asks for a confirmation since it replaces all your current items. Only import files you trust: scripts can run commands on your servers. Built-in items unknown to your version of WebSSH are skipped.

The same menu offers Reset to Defaults: after a confirmation, every saved item is deleted, your own scripts included, and the bar gets its original items back. As the list is synchronized through iCloud, the reset applies to your other devices too.

A preview of the bar sits above the list and follows every change: order, appearance, separators and flexible spaces are exact. The Progress item is shown with a sample value so you can see where it will appear. The preview uses the theme of the open session, and scrolls sideways when the bar is wider than the screen.

The preview has two modes, shown under it:

Sample values: built-in items show their real value when a session is open (read locally, nothing is sent to the server) and your own items show their icon and name. No script runs.
Live: the preview runs your items for real, with the same engine as the State Bar of a terminal: remote commands, $http requests, refresh intervals, tints, badges and sparklines (which start from the history of the session's bar). When you open the settings from the Customize… entry of a State Bar, the preview is live on that session straight away. Otherwise tap ▶︎ and choose one of the open sessions; ■ goes back to the sample values. With no open session, ▶︎ still runs the items that use $http, while $ssh.exec returns null.

In live mode the preview behaves like the bar of the chosen session: an item whose tags do not match that connection is not run and is drawn dimmed. An item that returns nothing (hidden in the real bar) keeps its icon and name here, so that it stays visible while you edit. The $vars of the preview are its own, and the State Bar of that session is paused while the preview runs (one engine at a time on the connection), then resumes when you leave. When you leave the settings after a change, the State Bars of the open sessions are rebuilt with the new list: no need to restart them.

To find which element of the bar a row stands for, on iPhone and iPad choose Locate in the Bar in the context menu of the row (long press): the preview scrolls to the item and flashes it, which is especially handy for spaces, flexible spaces and separators. On the Mac, simply hovering a row highlights its item, which also works with a pointer on iPad.

Changes are saved immediately and synchronized through iCloud like the rest of your data. When the settings were opened from a State Bar menu, that bar is rebuilt when you leave them; other open terminals pick up the changes with Restart in their State Bar menu.

First launch

Until you compose your own list, the State Bar shows Connection info, Progress and Recording, each followed by a Separator, then Connection name, a Flexible Space and Terminal size, which puts the terminal size on the right edge. If you already had a list before 32.10, the three system items and their separators were added once at its head.

System items

Since WebSSH 32.10, the three elements that used to be fixed are items of the Built-in Items picker, listed first among the other built-in items. Their content is driven by the terminal, not recomputed on a timer, so they have no refresh interval. Each can be added once.

Item	Shows	Tap
Connection info (since 32.9)	Icon only when everything is fine, icon + label when the state degrades (orange for a warning, red for an error, for example a mosh session waiting for the server or a lost SSH connection)	Opens the connection information sheet (key exchange, cipher, host key fingerprint, jump hosts, mosh transport…)
Progress	Only visible while a job reports its progress through the `OSC 9;4` escape sequence: ring + percentage, red triangle on error, orange pause icon, spinner when indeterminate, green check when the job completes	None. Its context menu clears a stuck indicator
Recording	Record icon, red while recording	Start / stop a session recording, add markers, review or list recordings

Removing Connection info does not remove the feature: the sheet stays available from the terminal menu (⋯).

Built-in items

Since WebSSH 32.10, built-in items are provided and computed by WebSSH itself. They cannot be edited (a lock is shown in the list) but they can be reordered and deleted, and they are updated automatically with the app: no JavaScript involved.

Item	Shows	Available on
Connection name	The connection icon and name (or host when the name is empty)	All sessions
Duration	Time elapsed since the session started	All sessions
Address	The resolved address handed to the SSH engine. With the passthrough DNS strategy this is the hostname itself	SSH
Terminal size	Columns × rows	All sessions
User	The login user	SSH, mosh
Server identifier	The SSH server banner (eg. `SSH-2.0-OpenSSH_9.6`)	SSH, mosh (bootstrap)
Cipher	The negotiated cipher (incoming / outgoing when they differ)	SSH, mosh (bootstrap)
Round-trip time	The smoothed round-trip time of the mosh transport. Numeric: can show a sparkline	mosh
Date & Time	The local date and time of the device, with settings: date style, time style, seconds, or a custom pattern. Set its refresh interval to 1 second when you show the seconds	All sessions, can be added several times
Ephemeris	Sunrise and sunset, the next sun event, the day progress (a ring filling from sunrise to sunset with the remaining daylight as label), or the moon phase. Computed on the device from a latitude / longitude entered in the settings: no network, no location permission	All sessions, can be added several times

An item that does not apply to the current session is simply hidden. Each built-in item can be added only once, except Date & Time and Ephemeris.

Built-in item settings

Tap a built-in item in the list (or Edit in its context menu) to open its settings: a live preview at the top when the item has parameters (Date & Time, Ephemeris), its appearance, its refresh interval, the Graph setting for numeric items (Round-trip time), then the item's own parameters. Settings are saved when you leave the sheet and synchronized with the rest of the item.

Layout items

Three built-in items only affect the layout and can be added as many times as you want:

Separator: a thin vertical line, to delimit groups of items. Like in a toolbar, separators that end up side by side are merged (for example around the Progress item while no job is running), and a separator at the very start or end of the bar is not drawn. Tap a separator in the list to choose its height: short (10 % of the bar), medium (50 %, the default) or the full height of the bar.
Space: a small fixed gap between two items.
Flexible Space: pushes the items on either side of it apart. One flexible space aligns everything after it to the right edge; two of them center what stands between them. When the items do not fit in the bar, flexible spaces collapse and the bar scrolls as usual.

Appearance

Since WebSSH 32.10, every item (system, built-in or your own) has three appearance settings. For your own items they are in the item editor; for the others, tap the row in the list to open their settings.

Style: Plain (content only, the default), Bordered (thin rounded outline) or Filled (light rounded background). A tint returned by a script still colours every style. To delimit items, use the Separator layout item.
Content: Icon and label, Icon only or Label only, to compact a busy bar without touching the script. A progress ring or a badge stays visible in Label only, as they live in the icon slot. When Graph is set to Sparkline, Graph only shows nothing but the curve (the item falls back to icon and label until there are two values to draw).
Minimum label width: in points, empty for automatic. The label keeps at least this width, so an item whose value changes length (a CPU usage going from 9 % to 10 %) no longer pushes its neighbours around.
Maximum label width: in points, empty for none. A longer label is truncated with …; tapping the item still shows and copies the full value.

As every non-layout item now has settings, they show a chevron in the list, and so does the Separator; Space and Flexible Space keep the lock.

Your own items

Since WebSSH 29.3 you can write your own items. An item is defined by:

Name: only used to identify the item in the settings (and as the title of the menu shown when you tap the item).
Tags: link the item to one or more connections. Read more about WebSSH Tags. Leave empty (or *) to show the item on every connection. The default items only exist while your list is empty: once you have a list, a connection that matches none of your tagged items shows just the items that apply to it (system and built-in items always do).
Icon: the SF Symbol displayed before the label. The script can change it at every run. The icon row shows the symbol name, and in the icon picker a long press (or right click) on any symbol shows its name with a Copy name action: handy to find the names a script can return in icon, no Mac needed. The picker's list mode shows all the names.
Graph: off by default: Details only or Sparkline. See below.
Network Access: off by default. See below.
Variables: shown when the script has some. See below.
JavaScript: the code executed to compute the item. See the JavaScript API and the examples.

A script can also colour its item (tint), add a badge on the icon or replace the icon with a progress ring: see the Item Result Object.

Graph

Since WebSSH 32.10, an item can draw a sparkline of its last values without any work in the script: WebSSH keeps the last 30 numeric values (the value field of the result, or the first number found in the label) and draws a small curve next to the label. Graph has three settings: Off, Details only (the history is kept and the graph appears in the item details, the bar is unchanged) and Sparkline (the curve is also drawn in the bar; what is shown next to it is the Content setting, which then also offers Graph only). The history lives in memory: it starts again when the bar is restarted or the session reopened. When the values barely move (less than 5 %), a flat line is drawn instead of amplifying noise.

Variables

Since WebSSH 32.10 a script can declare variables, with the same syntax as snippets: {{{ CITY : Paris }}}. The item editor then shows a Variables section with one field per variable, and WebSSH replaces each placeholder by its value every time the item runs. You change the city, the URL or the token without touching the script, and items of the WebSSH Library keep your values when their script is updated.

Syntax	Field
`{{{ NAME }}}`	free text, empty by default
`{{{ NAME : default }}}`	free text, prefilled
`{{{ NAME : "https://example.com" }}}`	double quotes protect `:` and `\|` (mandatory for a URL)
`{{{ NAME : first : second : third }}}`	list of choices, `first` selected
`{{{ NAME \| secret }}}`	masked field, for a token or a password

Variables come from the script: add one by writing a placeholder in the script (the field appears when you come back to the item editor), remove one by deleting its placeholder (its value is discarded when you save). This works for your own items as well as for items imported from the library.

No need to remember the syntax: in the script editor, the { } button opens an Insert Variable form (name, type, default value or list of choices) and writes the placeholder at the cursor, with the double quotes a URL needs. Leave Insert as a String on to get '{{{ NAME }}}' ready to use, turn it off when the cursor is already inside a string.

Write a placeholder inside a JavaScript string: let city = '{{{ CITY : Paris }}}'. The value is escaped, so a quote or a backslash in it cannot break the script. A name used several times is asked once. The Allowed Hosts field accepts variables too: with {{{ URL }}} the host is taken from the value (https://ha.local:8123/api gives ha.local).

Values are stored with the item and synchronized like it. The values of secret variables are left out of exported files. On a version of WebSSH older than 32.10 an item with variables is hidden.

Network access

Since WebSSH 32.10 a script can call web services with $http: a weather service, a status page, your Home Assistant, the API of your monitoring… It also gives items something to show on mosh sessions, where $ssh.exec is not available. Requests are sent by your device, not by the server.

Nothing reaches the network unless you allow it, item by item:

turn on Network Access in the item editor: until then $http does not exist for that script;
list the Allowed Hosts the script may contact, separated by commas: api.example.com, 192.168.1.10. Use *.example.com for a domain and all its subdomains. A pasted URL is reduced to its host. Any other host is refused, including through a redirect.

WebSSH never asks anything while the bar is running: a refused request simply returns null and writes a warning that the test panel shows live. With Network Access on, the item is refreshed every 10 seconds at most (shorter refresh intervals are not offered), and eval and Function are disabled in the script so that a downloaded text can never be executed.

When you import items from a file, Network Access is always switched off on the imported items (the host list is kept): open the item, check its script and its hosts, then turn it back on.

Test your item

Since WebSSH 32.10 you can test an item while you write it, without saving anything. The test needs a session that is already open (SSH or mosh, where the State Bar is available): with no open session the test is not offered.

In the item editor, tap Test under the script.
In the script editor, tap the ▶︎ button: it runs the text being edited, saved or not. On iPhone and iPad the panel opens half height and the script stays editable behind it.

The panel runs the script on the selected session exactly like the State Bar does, remote commands included, and shows:

the real rendering of the item with the colours of that session's theme (tint, badge, progress ring, sparkline);
the returned value and whether the item is shown or hidden;
the duration of the run, orange above 1 second and red above 3 seconds;
the console output (console.log, console.warn…);
errors with their line and column: from the script editor, tap the error to jump to the line;
warnings for values WebSSH tolerates but you probably did not intend: unknown SF Symbol, unknown tint, progress outside 0…1, long badge, $http used while Network Access is off.

Run once executes a single run. Run every N s reproduces the real rhythm of the item, using its refresh interval, which scripts keeping state in $vars and sparklines need. The $vars of the test persist between runs and are separate from the real bar; Reset clears them along with the sparkline history and the console.

Leaving the item editor with unsaved changes now asks to save, discard or cancel.

Refresh interval

Since WebSSH 32.10, each item that is recomputed (your own items and the built-in value items) has its own refresh interval: 1, 2, 3 (the default), 5, 10, 15 or 30 seconds, then 1, 2, 5 or 10 minutes. It is in the item editor for your items, and in the settings of a built-in item. Keep a short interval for cheap local values such as a clock, and prefer a long one for scripts that run remote commands: a command that runs every minute costs twenty times less than the default, and a value that rarely changes (pending updates, certificate expiry…) is fine at 5 or 10 minutes. Items with Network Access start at 10 seconds. A run that is still in progress is never started again by the next beat, so a slow script simply refreshes less often than asked.

Items are only recomputed while you are not typing. Typing in the terminal pauses the updates until you stop. The Pause entry of the State Bar menu pauses them explicitly (diagonal stripes are drawn over the bar), Refresh forces a run, Restart rebuilds the bar.

Item details

Since WebSSH 32.10, tap (or click) an item to open its details: a popover on Mac and iPad, a sheet on iPhone.

the full value, even when the bar only shows an icon, a curve or a truncated label, with its badge and progress;
a large graph of the history when Graph is not off: up to 120 values (the bar draws the last 30) on a real time axis, with minimum, average, maximum and last value. Touch or hover the curve to read a value and its time. Values use the unit returned by the script (12.3 MB/s rather than 12309214); rates, durations and percentages are drawn from zero;
a donut of the composition returned by the script (parts): CPU time by kind, memory used / cached / free, containers by state… Touch a slice to read its share;
the details returned by the script, when it provides some (the list of pending packages, the names of the unhealthy containers, every mount point…): see detail;
when it was last updated, its refresh interval and how long the last run took (orange above 1 second, red above 3);
actions: Copy, Refresh (this item only, right now), Edit (opens the item in the settings) and, for an item of the library, View Source.

Pin keeps an item under your eyes while you work: a compact card (value, graph or donut, last update) floats over the terminal, refreshed with the bar. Drag it where you want, resize it from its lower right corner, close it with its cross, tap it to reopen the full details. Several items can be pinned at once, and typing always stays in the terminal. Pins last for the session by default. Turn on Remember Pinned Cards (Settings → Advanced → SSH, Terminal State Bar) to have each host remember its own pinned cards, with their place and size: they come back the next time you open that host, in every pane of it. This memory stays on the device (it never syncs through iCloud, since the layout depends on the screen) and is dropped when the item or the host is deleted, or when the item list is reset.

Right click (or long press) an item to copy its label without opening the details. System items keep their own action (connection information, recording menu…).

Items with errors

A script that throws an error hides its item, so nothing in the bar tells you which one failed. When at least one item is failing, the menu button of the State Bar (the first icon) wears a red badge, and its menu shows Items with Errors (n): the console sheet then opens with the error message of each item, its line, and an Edit button. The entry disappears as soon as every item runs fine again.

Console

A script can also say something without failing: console.warn and console.error (see the JavaScript API) reach the State Bar itself, not only the log file.

An item that is visible wears a small orange or red count of its unread warnings and errors, in its top right corner. Opening the item's details reads them: the details show the last lines of that item, and the count disappears.
When the item is hidden (its script returned null or threw), the count moves to the menu button, added to the failing items: the first icon is where you learn about what you cannot see in the bar.
console.log never counts. It is only shown in the console sheet and in the item details.

Console in the menu of the State Bar (with the number of unread warnings and errors, when there are some) opens the journal of the session: the failing items first, then every line written by every script, newest first, with its item, its time and, when the same line repeats, how many times (identical consecutive lines are merged, and each item keeps its last 60 lines). Clear empties it. The journal lives in memory for the session only; nothing is written to disk. The live preview of the settings has the same counts and the same sheet.

Known Issues / Limitations

When using $ssh.exec, avoid long running commands: they block the State Bar until they finish. Use the Linux timeout command to limit the execution time.
The State Bar is not available through a jump host ("Connect Through"), nor on Telnet sessions.
On a mosh session, $ssh.exec always returns null (there is no SSH session any more once mosh-server is started). See $mosh.
With poor or no network, $ssh.exec may freeze the State Bar and other UI elements. Disable the State Bar for that connection to avoid it.

Last update: September 26, 2026