Shell command

Output

Captured text or a structured JSON result from a shell command. No symbol is added by default. Scripts run through /bin/sh -c and inherit the bar’s environment.

Example

{
  "id": "hostname",
  "type": "command",
  "symbol": "desktopcomputer",
  "command": {
    "script": "hostname -s",
    "timeout": 5,
    "maxLength": 80
  },
  "refresh": { "mode": "interval", "seconds": 60, "event": "refresh" }
}

Configuration

Use the item-level text template to customise or hide the label. The provider options below control its data, symbols, colours, and visibility.

All fields below are inside command.

Text and JSON output

Text mode captures combined stdout/stderr unless output: "stdout" is set. JSON mode always reads stdout. Excluded stderr is discarded. The bar collapses whitespace and line breaks into spaces, then truncates the text to maxLength with an ellipsis. Empty successful text is allowed.

For structured output, set format: "json". The script must emit one JSON object:

{
  "text": "3 updates",
  "symbol": "shippingbox.fill",
  "tint": "#FFCC00",
  "hidden": false
}

A complete command item can emit that result directly:

{
  "id": "updates",
  "type": "command",
  "command": {
    "script": "printf '%s\n' '{\"text\":\"3 updates\",\"symbol\":\"shippingbox.fill\",\"tint\":\"#FFCC00\"}'",
    "format": "json",
    "onError": "keepLast"
  }
}

Invalid JSON or invalid field values count as failures. Result data is never executed. A result glyph must include its own font, for example {"glyph":"X","font":"Menlo","size":14}.

State appearance and errors

Symbol precedence is item-level symbol, configured state symbol, then JSON result symbol. No symbol appears if none is supplied. Configured glyphs inherit command.symbols.font and optional size, with per-glyph overrides; see font glyph symbols. SF Symbols use symbolFontWeight. showSymbol: false hides every symbol source.

Configured state tints override the result tint; otherwise the result tint applies, then normal item/theme styling. Colours accept #RRGGBB or #RRGGBBAA.

Nonzero exits, timeouts, output-limit failures, and invalid JSON follow the selected policy. While rerunning, the previous successful result remains visible with any configured running appearance; before the first result, the value is …. A retained result keeps its JSON symbol, tint, and hidden state, subject to configured state overrides.

To change command, edit the configuration file. sbar set cannot change this block.

Shared item options cover styling, symbols, actions, priority, and enabled state.

Text templates

The item-level text setting supports id, value, symbol, status, error. See text templates for syntax and field meanings. value keeps the command’s truncation and error policy. Templates cannot look up arbitrary JSON result fields. Result text is literal data, not a template.

Updates

Commands run once at startup, including in manual mode. Item-ID triggers rerun them even without a refresh configuration; named refresh events also trigger runs. Rapid triggers coalesce for 50 milliseconds and replace a running command.

Interval delays begin after completion; a trigger restarts that schedule. Changes to the script, timeout, output selection, format, or refresh settings rerun the command. Appearance changes do not. See refresh policies.

Current limits

Captured output is limited to 64 KB. Timeout, cancellation, and completion terminate the process group. Commands run to completion rather than streaming continuous updates; use a process plugin for streamed output.