Terminal integration

Once reports build, test, lint, and run status to supporting terminals using the Program Status Protocol (OSC 7501). A terminal can show that work is running, finished, failed, or cancelled without trying to interpret progress spinners or command output. The terminal decides whether to display a tab indicator, a notification, or another status view.

Status reporting works without a reporting account or network connection. Once reports preparation as working, success as done, and failure as error. When the existing connected-run cancellation handler processes a signal, Once reports idle before exiting by that signal. Unconnected runs retain the default signal behavior; terminals clear transient working status when they observe process exit or the next shell prompt.

Once does not guess progress percentages or report scheduler and memory waits as requests for user input. Literal commands executed through once exec do not receive Once's own program-status reports, so captured child status sequences cannot be confused with Once's execution state.

Open a live run#

When a reporting service creates a build, test, or script run and returns its dashboard URL, Once prints the link immediately:

On an interactive terminal, the URL is an OSC 8 hyperlink. In redirected logs it remains plain text. Once uses the canonical URL supplied by the service, rather than constructing a provider-specific route, and prints it only once across reconnects. The link remains above the progress panel instead of being overwritten by redraws. Captured output shown by the build and test progress reporter is rendered without terminal escapes so child output cannot replace Once's status or leave a hyperlink or synchronized frame open. Original captured output remains unchanged in the cache. Application output from once run and literal output from once exec retain their existing pass-through behavior.

No extra wait is added for the link. For a fast cached run, it can arrive after the completion summary while reporting drains. --quiet suppresses the dashboard announcement. Machine-output modes retain the existing plain-text link on stderr; they never receive hyperlink escape sequences from Once.

Synchronized redraws#

Once uses DEC private mode 2026 to present each progress-panel redraw as one frame on supporting terminals. Synchronization covers only the redraw, never execution or a wait for work. Frames use a bounded buffer, with ordinary output as the fallback when a frame exceeds that bound.

Disable terminal controls#

Terminal controls are automatic for human output on an interactive stderr terminal. They are disabled for redirected output, machine-output formats, TERM=dumb, and detected CI environments. No terminal-brand environment variable or interactive capability query is required. Unsupported terminals ignore the protocol sequences. On Windows, controls also require successful virtual-terminal initialization.

To disable status reports, hyperlinks, and synchronized redraws:

The default is --terminal-controls=auto. This setting is independent of color: --color=never and NO_COLOR disable colors, not terminal integration. --quiet suppresses the progress panel and dashboard announcement but retains invisible program-status reports.