TUI: the terminal interface

Running kranz opens the keyboard-first TUI. It is an operator view over the same runtime used by the CLI and MCP, so a command or coding agent can inspect the stack without opening a second copy.

What is on screen

Area	What it shows	Focus key
Services / Tags	Services, dependencies, actions, groups, tags, selection, and lifecycle state	1
Details	The focused item's command, health, dependencies, ports, and current operation	2
Logs	Captured service, action, and lifecycle output with follow, wrap, timestamps, and regex search	3

The header summarizes the runtime and active work. The footer shows the most relevant keys for the current focus. Press ? at any time for in-application help.

Read state at a glance

The dot beside a service is its lifecycle state, not a health verdict:

Indicator	Meaning
Green	The process or detached resource is running
Gray	It is stopped
Yellow	A start, stop, dependency wait, or lifecycle operation is in progress
Red	It failed or exited unsuccessfully

Readiness and liveness are separate. Details names the configured probes and their latest result; a missing probe is shown as not configured, never as a successful health check. Runtime-discovered ports and the PID that owns them appear in the same panel.

The focused row and selected rows are also different. Focus chooses what Details and Logs show. Selection chooses the targets for the next lifecycle operation. This lets you inspect one service while preparing an operation on several others.

A first session

1. Use ↑ / ↓ or j / k to focus a service.
2. Press Space to select it, or a to select all services.
3. Press s to start the selection and its dependencies.
4. Press 2 to inspect readiness, liveness, dependencies, and ports.
5. Press 3 to follow logs; press / to search them.
6. Return to panel 1 and press s again to review and confirm the stop plan.

Actions appear below their service or project group. Focus an action and press s to run it. Its output is multiplexed into the Logs panel and labeled with the exact OWNER/ACTION#run identity.

Review lifecycle plans

Starting a service includes its transitive dependencies. Stopping it includes running dependents in reverse order. Restarting follows the same resolved graph. Before a destructive operation Kranz opens a confirmation view with the exact targets and execution waves; the TUI does not hide graph expansion behind a single service name.

Use Shift+S only when you deliberately want the selected targets without graph expansion. The confirmation view calls out that override so it cannot be mistaken for the safe default.

Work with logs

Panel 3 follows the focused service by default. Shift+3 pins it while you move elsewhere. Search with /, then use Tab to switch between filtering and highlighting; n and Shift+N move between highlighted matches. Toggle wrap with w, captured-at timestamps with i, and following with f.

WRAP and TIME appear in the log header when enabled. The panel keeps its selected row while output arrives, including wrapped, filtered, and pinned views.

Service output survives a crash or stop for as long as the runtime exists. Every service start and action execution has a run number, so logs remain attributable across restarts instead of becoming one ambiguous stream.

Actions, history, and notifications

Actions live below their service or project action group. Run a focused action with s; confirmation is shown when its configuration requests it. Completed actions remain available by their OWNER/ACTION#run identity, including their captured output and exit status.

Press c on a parameterized action to open its form. When radio or checkbox choices exceed the available width, the form puts every choice on its own aligned line; long labels wrap without hiding options.

Press n outside an active log-highlight search to open notifications. Press h from Logs for recorded health transitions. Both views explain what changed without requiring you to reconstruct it from raw output.

Attach to a background runtime

kranz up -d starts a runtime and returns the shell. Open the same runtime in the TUI later with:

kranz attach

Every TUI is attached to an independently owned runtime, including the one opened by bare kranz. The quit confirmation always shows which managed processes and configured detached resources will stop and which external resources will remain active. Confirm shutdown with Enter or y, press d to detach the TUI and keep the complete runtime running, or press c for Close & choose: stop this runtime and immediately choose another in the same TUI process. Use Esc or n to stay.

The CLI workflow and MCP guide operate the same live runtime. A restart from either is reflected immediately in this TUI.

Switch between local runtimes

One TUI can work with several projects. Press p to list local runtimes, with the current runtime first. Press Enter on another compatible runtime to attach, or on the current runtime to close the list. Esc also closes it.

On another runtime, press s to review the same shutdown plan shown by the quit confirmation, then confirm stopping it without attaching. The TUI stays open on the current runtime. The current row has no s action; use q to review its shutdown choices. A runtime with an incompatible protocol cannot be attached, but it can be stopped after confirmation. That confirmation shows verified managed processes and warns that detached resources may remain running because their stop plan is unavailable.

Runtime and Run history tables adapt to the terminal width. Wide terminals show their complete detail; narrower ones remove secondary columns first and wrap shortcut groups onto additional footer rows, keeping the selection and close controls visible without horizontal clipping.

Each runtime you visit keeps its own selection, log filters, pinned log, and scroll position for as long as this TUI process runs, so returning to one looks exactly as you left it. Switching never stops, restarts, or otherwise touches the runtime you are leaving: an operation it already accepted keeps running, and you see its result if you switch back before it finishes.

Starting kranz outside a project directory behaves the same way it always has once one is found. Without one, if any local runtime is already running, the same list opens immediately instead of failing; if none is, Kranz prints an error and exits.

If the runtime the dashboard is currently showing stops — the process crashed, or was stopped from elsewhere — the TUI shows a recovery screen instead of closing, offering r to restart that project or c to choose another running one. See the switching runtimes reference for the complete key list, row states, and recovery behavior.

Close & choose uses this same live list after intentionally stopping the current runtime. An empty list is a normal state; q exits and Esc returns to the recovery actions.

Common keys

Key	Meaning
1, 2, 3	Focus Services/Tags, Details, or Logs
Tab, Shift+Tab	Move between panels
Enter	Expand or collapse the focused row
Space	Select or unselect a service or tag
s	Start, stop with confirmation, or run a focused action
r	Review and confirm a restart
/	Search logs with a regular expression
x	Toggle Combined/Single run logs
[ / ]	Move to the previous/next run
v	Open run history; filter and select with keyboard or mouse
e / Shift+E	Export the selected run to clipboard / a chosen file
p	Switch to another local Kranz runtime
m	Open the configuration map
Ctrl+T	Open the theme and appearance picker
Ctrl+L	Reload configuration
?	Open help
q	Open the quit confirmation

The complete controls reference covers selection overrides, log navigation, health history, notifications, shell handoff, mouse interaction, and shutdown behavior. The guides for actions, lifecycle, logs, runs, and ports, and appearance include focused recordings of those workflows.