Guides
View-only workspace TUI
inferlab tui opens a persistent, read-only view of one InferLab workspace.
It uses the same upward discovery as other workspace commands. Select a
workspace explicitly with --workspace, and an alternate machine-local
bindings file with --local, when needed:
inferlab tuiinferlab --workspace /path/to/workspace tuiinferlab tui --refresh-interval 2sThe refresh override applies only to that invocation; inferlab tui --help
prints the current default interval. Declared workspace definitions and the
workspace dirty state refresh on a slower cadence of at least a minute; press
r to re-read every source, including those, immediately. Opening,
refreshing, searching, and closing the TUI do not write a UI session or launch
an InferLab workflow.
At startup the TUI asks the terminal for its background color, then falls back
to COLORFGBG, and otherwise assumes a dark background; it then uses a palette
tuned for that background. When the terminal reports its exact color, panels
are tinted from it. Press t to switch to the other palette for the rest of the
session, for example when a terminal that does not report its colors is light;
the switched palette is not tinted.
Views and sources
Section titled “Views and sources”- Overview groups rows into ATTENTION, NOW, RECENT, and WORKSPACE.
ATTENTION leads with failed, stale, and unavailable objects; top-level
workflow failures appear before abnormal child servers. NOW holds active
operations and running servers; an operation that reports an item position
shows a progress bar, and its glyph animates while it runs. RECENT groups
completed records by calendar day. Running and abnormal recipe-owned servers
remain visible without being counted again as top-level workflows. The
refresh indicator shows the configured automatic cadence while complete
generations arrive normally. It shows
WAITINGbefore the first complete generation and switches to an elapsedLAST REFRESHage only when no new generation has completed for two configured refresh intervals. - Operations shows concurrent workspace CLI invocations. Each command owns
one atomic JSON observation under
.inferlab/runtime/observations/. A normal completion removes it; abrupt residue stays visible and is classified from its host, boot, PID, and process-start identity. A workspace command fails withE5002before continuing when it cannot establish this required observation; update failures remove the previous live observation and are reported rather than silently degrading. - Records shows top-level records as a timeline grouped by calendar day.
Recipe-owned server and measurement records remain explicit children of the
recipe rather than being flattened: a parent marked
▸expands with→to show them beneath it (▾), each named relative to its parent, and←collapses them again from the parent or a child. A child is selectable with its own detail and metrics; a referenced child whose record cannot be read stays beneath its parent as unavailable. Details open with status and authority pills, then human-readable start, finish, duration, and age; a workload record shows its case metrics as one table with a column per case and a trend across the cases, followed by case state. Exact record identifiers, paths, child references, scratchpad references, and explicitly referenced logs remain available farther down the detail surface; case stdout and stderr artifacts remain mapped to their owning case under Case Artifacts. Bench records additionally show the recorded terminal and capture outcomes and identify the request, linear-session, or agentic-replay source. Request details include population, prompt authority, prefix-cache reset, and token reconciliation. Linear-session details keep warmup and profiling session/request counts, reconciliation, and failed-session diagnostics distinct. Agentic details keep source verification, acquisition, run/scenario validity, warmup handoff, profiling populations, branch/join counters, unavailable dimensions, and raw artifact references distinct. Older records without tagged source evidence remain navigable and say that the source is unavailable instead of inferring one. For a workload record with case metrics,mopens a record-local comparison surface. It selects one available metric at a time and draws horizontal bars for every case in that record; it does not combine records or add an SLO interpretation. - Workspace groups declared models, stacks, servers, Evals, Benches, workload suites, recipes, images, and external images by kind, followed by scratchpad entries. A Bench definition identifies its request, linear-session, or agentic-replay source and shows only the applicable source identity, prompt, population, load, and prefix-sharing declarations.
Every fact is labeled by its authority: declared workspace configuration, recorded evidence or journal text, ephemeral command progress, or an observed live check. The TUI does not convert an observation into evidence or reconstruct a record from definitions.
A list row is one line: a status glyph (✓ succeeded, × failed, ◆
warning, ● live or running, a spinner for an active operation), the kind, the
name with its summary, the lifecycle, a subdued DECL, REC, EPH, or OBS
authority badge, and the age. A successful read is intentionally implicit;
only exceptional read health is added to a row, for example refresh stale or
refresh unavailable.
A record row therefore presents its authoritative recorded lifecycle
(running, stopped, failed, or a workload outcome) without making a
successful file read look like another lifecycle. Detail surfaces keep source
authority and read health under Source Health, separate from Progress,
Outcome, Process Liveness, Metrics, Context, and Technical References.
For a server record whose recorded status is running, each refresh uses the
existing bounded server-status observation to report OBS process alive, OBS process dead, OBS process stale, or OBS process unavailable. A successfully
observed dead process is Attention rather than Active. One failed probe does
not affect other objects; after an earlier successful probe its last value
remains visible as stale. Terminal server records such as stopped are not
probed because their recorded lifecycle is already authoritative and no running
process is claimed.
The Metrics selector groups recorded names into throughput, observed input,
request latency, TTFT, TPOT, cache, speculation, SLO, and OTHER families.
Acceptance length uses tokens; acceptance rate and good-request ratio use
percentages; goodput uses requests per second. It defaults to request throughput
when that metric exists and retains unknown recorded metric names unchanged
under OTHER without inventing a unit. Concurrency and request-rate cases form separate chart regions and are ordered
by their typed effective load values, including the explicit request evidence
for adaptive probes; case identifiers are not parsed to recover load. A case
whose selected metric is absent remains visible as —, and its recorded state
remains distinct from a numeric zero. Wide terminals place the selector beside
the chart. Narrow terminals devote the body to the chart while keeping the
selected metric, metric position, and visible case window in view. Metric
values use compact, stable human precision rather than raw floating-point
serialization.
Source Health distinguishes a current read from stale, unavailable, or
incompatible data. A current read condenses to its authority and observation
time; an exceptional read lists every observation fact. A failed refresh after
an earlier success retains the last successful value as stale with its
observation time and age. A malformed or
newer operation schema is isolated to that operation. Refresh generations do
not overlap; missed ticks coalesce, and the prior complete generation remains
navigable while the next one is read. The refresh indicator describes that
display schedule only; workspace and object observation health remains on
the corresponding row and detail surface.
Navigation and search
Section titled “Navigation and search”| Key | Effect |
|---|---|
1–4 |
Select Overview, Operations, Records, or Workspace |
Tab, arrows, j/k |
Move views and selection; scroll detail, select a Find result, or select a metric while Metrics is open |
→ / ← in Records |
Expand a collapsed parent’s child records / collapse them from the parent or a child; otherwise open and leave detail |
f |
Cycle the Overview or Records status filter through all, issues (failed, stale, or unavailable), and running |
PageUp / PageDown |
Scroll detail or a referenced log by ten lines, or advance the Metrics case window |
Enter / Esc |
Open detail / return or close search |
m |
Open Metrics for the selected workload record, or return to its record detail |
[ / ] |
Select the previous or next explicitly referenced log |
Ctrl+K |
Find operations, top-level records, definitions, and scratchpad entries by typed fields |
/ |
Filter the current list, or search the selected explicitly referenced log tail |
r |
Request one immediate non-overlapping refresh |
t |
Switch between the dark and light palettes for this session |
q, Ctrl+C |
Exit and restore the terminal |
The widest terminals add a sidebar beside list and detail: the workspace name, revision and dirty state, the four views with their counts, the status filter with a count per status (Overview and Records), and the refresh indicator. Below that width a header carries the same facts. Wide terminals show list and detail together. Intermediate and narrow terminals show one pane at a time so neither pane is squeezed into unreadable columns. Panels have rounded borders, and the focused one is drawn in the brand blue. List and detail titles retain the selected object and list position while the content scrolls. Long labels and workspace paths use a visible ellipsis instead of silent clipping. Empty collections, an empty filter result, and an unavailable source have different messages. Refresh and quit remain visible down to the supported minimum; below it, the TUI reports both required and current dimensions.
Global Find is a dedicated cross-view result surface. Results are labeled by
object kind and authority, with contiguous kinds sectioned visually. The arrow
keys select a result while the query remains open, and Enter opens that
selected object. Matching is case-insensitive and ranks exact, prefix, and contains matches before bounded
fuzzy matches. Each typed field is matched independently, so characters from an
identifier cannot combine with characters from a status or another field to
create a false result. Find never searches raw JSON, environments, artifacts,
arbitrary files, or logs.
/ filters the current list. After a record or operation detail has loaded an
explicit log reference, / opens a search scoped only to the currently selected
log. The sticky detail title identifies the log number and filename; [ and ]
switch among references. Search results retain original tail line numbers and a
match count, and searching never changes the selected record or operation.
Strict view-only boundary
Section titled “Strict view-only boundary”The TUI cannot start or stop servers, launch Eval or Bench work, execute a
recipe, build an image, install tools, edit definitions or notes, clean state,
download data, synchronize logs, or reset caches. Run every such action as a
separate explicit inferlab command. This keeps the CLI as the action authority
and records as the durable evidence authority.