Prompts and Widgets

Prompts and widgets

The REPL reads $prompt, whose native Prompt type accepts a String or a zero-argument function returning String. A function returns its prompt; printing through echo is not the return protocol. An unsuitable prompt falls back to the base prompt.

Put status where it belongs

Before evaluating the prompt, Shelly invokes each function in $widgets. A nonempty returned String becomes [text]; an empty String contributes nothing, including no brackets. The combined result is available as $rendered_widgets only during prompt evaluation.

import std::widgets::{ clock_widget, git_widget }
$widgets = [$widgets..., `clock_widget, `git_widget]
$prompt = fn (): String
{
    "\n${USER}@${HOSTNAME} ${rendered_widgets}\n: ${pwd}\n"
}

Place ${rendered_widgets} elsewhere in the returned String to move the widgets. Use std::terminal::color for prompt segments that adapt to the terminal. $widget_color: String supplies widget text escapes; its default is the logo's cyan. Widget brackets use darker gray. Monochrome mode removes color styling.

Available widgets

Function in std::widgets	Appears as
clock_widget	Current time, 24-hour clock.
clock_12_widget	Current time, 12-hour clock.
git_widget	Repository branch and change summary.
command_time_widget	Time taken by the preceding command.
venv_widget	Python environment status inside a Python workspace.
node_widget	Current Node version and expected version when different.

$last_cmd_time is consumed/reset at every prompt, including an empty one. It formats elapsed time as minutes:seconds, adding hours and days when needed.

Python workspace detection walks parent directories for pyproject.toml, setup.py, setup.cfg, requirements.txt, or local .venv/venv directories. The widget reports the active environment name or an inactive indication.

Node expectations come from .nvmrc, then .node-version, then package.json's engines.node. The widget compares these with node --version; when they agree, it shows only the current version.

Widget functions run before each prompt. Keep custom widgets cheap: avoid long network calls or scanning large trees on every command.

---

Related: Startup · Terminal formatting · REPL