﻿The TUI runs in your terminal. It connects to a daemon on the same machine over
its socket, or to a remote daemon over HTTP.

```bash
runwisp                                       # start the local daemon if needed, then open the TUI
runwisp tui                                   # open the TUI for a daemon that is already running
runwisp tui --url https://runwisp.example.com # connect to a remote daemon
```

Locally, no password is needed. With `--url`, the TUI logs in with the Web UI
password: it reads `RUNWISP_PASSWORD` or asks once, then remembers the session.
See [Authentication](/operations/auth/).

Press <kbd>?</kbd> at any time for the full list of keys. The bar at the bottom
shows the keys for whatever is focused.

## Layout

The sidebar on the left starts with **Home**, followed by your tasks and
services (grouped by [`group`](/configuration/tasks/#group)), then **Info**
and **Debug** at the bottom. `▸` marks what the right pane shows. Moving the
cursor does nothing until you press <kbd>Enter</kbd>.

A mark after a task's name shows its state: `●` running, `✗` last run failed,
`■` stopped service, `‖` paused schedule. Press <kbd>?</kbd> to see the list.

## Home

_Screenshot: TUI Home page: sidebar listing task groups, right pane showing Open Web UI row, Web UI URL, masked password, and a recent-activity table with status, duration, and trigger columns._

- **Open Web UI**: opens your browser, already logged in. Without a browser, the
  TUI copies the link to your clipboard, or shows it for you to copy. Over plain
  `http://` to a remote host, it asks first, because the login link would travel
  unencrypted.
- **Web UI**: the address. <kbd>Enter</kbd> copies it.
- **Password**: shown only when the daemon generated the password.
    <kbd>Enter</kbd> copies it.
- **Recent activity**: the latest runs across all tasks. On a terminal at
  least 143 columns wide, it also shows CPU, RAM and OUTPUT. Each run is colored
  against its own task, as in [Task detail](#task-detail).

Press <kbd>n</kbd> to open the notifications panel. If some tasks come from
crontabs that cron still runs, the header shows how many are
[held](/coming-from/cron/#held-jobs). It also counts paused schedules.

## Task detail

Select a task or service in the sidebar to see its schedule, its run history,
and buttons for what you can do to it right away, without opening a run:

- A task has **Run Now** (<kbd>r</kbd>) and, if it has a cron schedule,
  **Pause** or **Resume** (<kbd>p</kbd>).
- A service has **Restart** (<kbd>r</kbd>) and **Stop** (<kbd>s</kbd>). A stopped
  service has **Start** (<kbd>r</kbd>) instead.

Click a button or press its key. **Run Now** asks for confirmation, or opens a
form if the task has [parameters](/concepts/parameters/). Restart, Start and
Stop ask first too.

_Screenshot: TUI task detail for healthcheck-api: header with task name, cron schedule, next-fire countdown, and Run Now button; run history table below showing status, start time, duration, and trigger columns._

Each run shows its duration, CPU time, peak memory, and how many lines it
printed. A running run shows its live CPU and memory use and the lines printed so far instead. Duration, CPU and RAM turn amber or red when the run used much more
than the task usually does. OUTPUT turns amber when it printed far more or far
less than usual.

- <kbd>f</kbd> filters the runs by status. A banner shows while a filter is active.
- <kbd>i</kbd> shows the task's full definition and recent health.
- <kbd>p</kbd> [pauses or resumes](/concepts/scheduling/#pausing-a-schedule) the task's schedule.
  <kbd>u</kbd> undoes it while its notice is showing.
- <kbd>space</kbd> selects runs, <kbd>a</kbd> selects all that match the filter. Then <kbd>d</kbd>
  deletes, <kbd>c</kbd> cancels, and <kbd>e</kbd>
  re-runs them. <kbd>u</kbd> undoes a delete while its notice is showing.

## Following a run

Press <kbd>Enter</kbd> on a run to open it. The log streams live, with line
numbers, under a header with the run ID, start time, duration, and status.

_Screenshot: TUI run detail for reindex-search: header with Back button, run ID, timestamp, duration, and status badge; line-numbered log output below._

- The log follows new lines. Scrolling up pauses that; <kbd>G</kbd> jumps back
  to the end and follows again.
- <kbd>f</kbd> shows only the log, full screen, for copying.
- <kbd>d</kbd> downloads the log. Without a browser, you get the download link instead.
- <kbd>r</kbd> runs it again, <kbd>s</kbd> stops it. Both ask first.
- <kbd>i</kbd> shows the run's exit code, trigger, timing, and retries. For a retry,
  <kbd>Enter</kbd> jumps to the attempt it retried.

_Screenshot: TUI fullscreen log view: no sidebar, no header, pure log lines filling the terminal._

## Reading a failure

The run header tells you what went wrong before you read the log:

- **Status**: why the run ended: `failed`, `timeout`, `crashed`, `stopped`,
  `skipped`, `log full`, and others.
- **Exit code**: what the command returned. `-1` means the run was skipped and
  never started ([`on_overlap = "skip"`](/configuration/tasks/#on_overlap)).
  `-2` means the daemon died during the run (`crashed`). A timeout usually shows
  `143` (SIGTERM) or `137` (SIGKILL).

In the sidebar, a task whose last run failed has a red `✗`. With
[retries](/concepts/retries/), every attempt is its own run with its own log.

## Info and Debug

**Info** shows CPU and memory graphs, run counts, version, and uptime.

_Screenshot: TUI Info page: CPU and memory sparklines, activity summary, daemon version and Web UI address, configuration, and task list._

**Debug** shows the daemon's own log. Reconnect messages appear here when the
connection drops. The TUI reconnects by itself.

## Keyboard shortcuts

| Key                                                 | Action                                                |
| --------------------------------------------------- | ----------------------------------------------------- |
| <kbd>?</kbd>                                        | Show all keys                                         |
| <kbd>q</kbd> / <kbd>Ctrl+C</kbd>                    | Quit                                                  |
| <kbd>↑</kbd><kbd>↓</kbd> / <kbd>k</kbd><kbd>j</kbd> | Move                                                  |
| <kbd>←</kbd><kbd>→</kbd> / <kbd>h</kbd><kbd>l</kbd> | Switch between sidebar and main pane                  |
| <kbd>Enter</kbd>                                    | Open, activate, or copy a field                       |
| <kbd>Esc</kbd> / <kbd>⌫</kbd>                       | Back                                                  |
| <kbd>/</kbd>                                        | Filter tasks (sidebar) or search the task's logs      |
| <kbd>r</kbd>                                        | Run now (task), restart or start (service), or retry  |
| <kbd>s</kbd>                                        | Stop a service, or the open run                       |
| <kbd>p</kbd>                                        | Pause or resume a task's schedule                     |
| <kbd>R</kbd>                                        | Reload `runwisp.toml` ([Reload](/operations/reload/)) |
| <kbd>n</kbd>                                        | Notifications panel (on Home)                         |
| <kbd>i</kbd>                                        | Task or run details                                   |
| <kbd>f</kbd>                                        | Filter runs, or full-screen log in a run              |
| <kbd>d</kbd> / <kbd>D</kbd>                         | In a run: download the log / delete the run           |
| <kbd>g</kbd> / <kbd>G</kbd>                         | Jump to the top / end of the log                      |

## Quitting

Press <kbd>q</kbd>. If the TUI started the daemon (you ran `runwisp` and no
daemon was running yet), it asks whether to keep the daemon running in the
background or shut it down. <kbd>Esc</kbd> cancels.

_Screenshot: TUI quit confirmation dialog: modal asking "Keep the daemon running in the background?" with Keep Running and Shut Down buttons._

If the daemon was already running (a systemd or launchd service, `runwisp tui`,
or `--url`), <kbd>q</kbd> closes the TUI right away and the daemon keeps
running. Use `runwisp stop` to stop it.
