Terminal UI

When the TUI starts

vectron start launches the TUI when stdout is attached to a supported terminal. Otherwise Vectron falls back to plain output mode.

The Two Focus Areas

The TUI has two interactive areas:

• Logs
• Scope

Use Tab to switch focus between them.

Scope is the panel that shows:

• Groups when grouped processes exist
• Services when no groups exist, or after entering a group

Only the process group field affects this view. Startup labels are not displayed as TUI groups.

This is the core model for the keyboard UX: navigation keys act on the focused area, and stop / play / restart act on the active scope currently shown by the TUI.

How Scope Selection Works

Lifecycle actions use the active scope shown in the TUI:

• when focus is Logs, the active scope comes from the current log filter
• when focus is Scope, the active scope comes from the selected row
• when no log filter is active, the logs-side scope is the whole workspace
• in Scope focus, lifecycle actions require a selected row; they do not fall back to the logs filter

Typical examples:

• Focus: Logs | Scope: all
• Focus: Logs | Scope: proc:web
• Focus: Scope | Scope: group:edge
• Focus: Scope | Scope: inst:api#2

Live Tail vs Historical View

The logs pane has two user-visible modes:

• live tail: the viewport follows incoming logs
• historical view: the viewport is frozen around a selected log

You enter historical view when you select a log, open log details, jump to a search result, or jump to an error-ish log. In that state, new logs may still arrive, but the current viewport stays stable.

This historical viewport is anchored to the selected log. If wrapping changes because the terminal is resized, Vectron re-anchors the view around that same selection instead of jumping back to the tail.

Use End or G to return to the live tail. Esc also clears the current logs-side state and returns to live view.

Keyboard Controls

Global

• q or Ctrl+C: quit; if processes are still running, Vectron stops them first
• ?: toggle help
• Tab: switch focus between Logs and Scope
• Esc: close overlays, cancel search editing, clear active filter/state, then return to Logs
• m: toggle CPU and RSS metrics
• Left: return from a group’s Services view to Groups, regardless of focus

Logs

• Up / k: select the previous visible log
• Down / j: select the next visible log
• PageUp / Ctrl+B: page up
• PageDown / Ctrl+F: page down
• Home / g: jump to the top of the current log buffer
• End / G: return to the live tail and clear the current historical logs state
• Space: pause or resume live updates
• [ / ]: jump to the previous or next error-ish log
• Enter: open or close details for the selected log
• Esc: clear the current logs-side state and return to live tail This includes the active log filter, paused historical selection, and manual scrollback.

Search

• /: open the search prompt
• Enter: apply the current query
• Esc: cancel prompt editing
• n / N: move to the next or previous result
• Ctrl+L: clear the active search

Search navigation also enters historical view: the viewport jumps to the matching log and remains stable until you explicitly go live again.

Scope

• Up / k: move selection up
• Down / j: move selection down
• PageUp / Ctrl+B: move one page up
• PageDown / Ctrl+F: move one page down
• Home / g: jump to the first row
• End / G: jump to the last row
• Enter: open the selected group, or filter logs by process from a service row
• Shift+Enter / Ctrl+Enter: filter logs by instance from a service row
• Esc: clear the active filter or scope context; if nothing is active, return focus to Logs
• s: stop the selected scope
• p: start the selected scope
• r: restart the selected scope

Log Details

• click a log line, or press Enter on the selected log, to open details
• Esc or Enter: close the modal
• Up / k: move to the previous log while keeping details open
• Down / j: move to the next log while keeping details open
• PageUp / Ctrl+B: page up
• PageDown / Ctrl+F: page down
• Home / g: jump to the top of the details view
• End / G: jump to the bottom of the details view
• c: copy the raw log message

c is reserved for copying in the log-details modal. It does not clear filters or selections in normal mode.

Lifecycle Actions

The main lifecycle keys are:

• s: stop
• p: play
• r: restart

These keys always act on the active scope currently shown by the TUI. This is why the focus-and-scope hint matters: it tells you exactly what will be affected before you press the key.

Metrics

The TUI can display CPU and RSS values per process tree. Thresholds come from vectron.toml.

Use m to toggle metrics while the TUI is running.

Use vectron doctor or vectron doctor tui to inspect terminal and metrics capability support.