---
title: The terminal app
summary: What rsva tui shows, how it signs in, where it keeps its copy, and the keys and mouse that drive it.
---

`rsva tui` is the live app in a terminal. It keeps a copy of the workspace on disk and stays connected to the server, as a browser tab does: reading and editing are local and immediate, and other people's changes arrive as they are made. It lists issues, opens them, changes them, takes comments, and starts agents on them ([Dispatch an agent](/docs/terminal/dispatch)). It is built for macOS.

## Start it

`rsva tui` comes with `rsva`: install it as [Getting rsva](/docs/terminal/cli#getting-rsva) says. Then sign in and start it:

```sh
rsva login
rsva tui
```

Or start it with a token, the way the other commands run: `RSVA_TOKEN=rsva_… rsva tui` (and `RSVA_URL` for your own server).

`rsva tui` needs a terminal. It goes as the first credential it finds:

1. One you name: `RSVA_SESSION`, `RSVA_TOKEN` or `RSVA_KEYCHAIN`.
2. The session of [`rsva login`](/docs/terminal/cli), kept in the Keychain. It opens every workspace you are in. A session the server has ended is skipped.
3. Your own token, in the Keychain under `rsva-own` (or the service `RSVA_OWN_KEYCHAIN` names). It opens that token's one workspace.
4. The agents' token, under `rsva-bot`. The head then says `as <agent's email>`.

Signed in with `rsva login`, the TUI opens on the workspace you were last in. **Change workspace…** in the palette switches to another; each workspace opens from its own copy and on its own last query.

Without a connection the TUI opens from its copy: on the last workspace when signed in with `rsva login`, and with a token only when `RSVA_WS` names the workspace.

When you quit, it prints a short report of what it measured: the time to the first frame and to the data, key-to-frame times and memory.

## Where it keeps its copy

The copy lives under your user's cache folder, `~/Library/Caches/rsva` on macOS, in a folder per credential. The folder is named by a hash of the credential, never the credential, and only you can read it. Next to the copy the TUI remembers the workspace it was last in, the last query in each workspace, and the theme you picked.

`rsva logout` deletes the copies made with that session.

## The screen

- **The head**: the list's name (Open issues, My issues, or Query), the workspace, how many issues, the query, and how many agents are running or waiting.
- **The list**, grouped by state. Started states come first, then unstarted ones such as Todo, then the backlog, then the closed ones. The first start shows every open issue (`-group:completed,cancelled`); later starts open on the last query. Within a state the order is the query's `order:`, else the newest change first.
- **The card** of the selected issue under the list: its description on the left and its properties on the right. At 80 columns it folds to five rows; under 20 rows there is no card.
- **The status line**: the connection, what the last action did, and the Rex session's name when the TUI runs in Rex.
- **The keys line**: the keys that act now. `?` shows every key of the screen.

`↵` opens the **issue screen**: the title and a line of chips, then the description, the sub-issues and the activity (comments and history) as one feed. From 120 columns wide the properties are in a panel on the right; below that, `i` shows them above the text.

## List keys

| Key | What it does |
| --- | --- |
| `j` `k`, `↑` `↓` | Move. |
| `PgUp` `PgDn` | A page up, down. |
| `Home` `End` | The first, the last issue. |
| `↵` | Open the issue. |
| `f` | Filter with a query. |
| `/`, `Ctrl+K` | The palette: commands, issues, views. |
| `c` | A new issue. |
| `C` | A sub-issue of the selected issue. |
| `s` | Change the state. |
| `p` | Change the priority. |
| `a` | Change the assignees. |
| `l` | Change the labels. |
| `.` | The issue's menu: everything it can do, the cycle, dates, parent and relations too. |
| `d` | Dispatch to an agent. |
| `r` | Reply: a comment on the issue. |
| `g q` | A queue through this list. |
| `o` | Open in the browser. |
| `e` | Edit the description in `$EDITOR`. |
| `y` | Copy the link. |
| `Y` | Copy the key. |
| `m` | Move to another project. |
| `D` | Move to the trash, after a yes. |
| `u` | Undo the last change made here. |
| `Esc` | Back to Open issues. |
| `?` | Every key of the screen. |
| `q`, `Ctrl+C` | Quit. |

`q` quits from every screen except while you type in a field.

## Issue screen keys

| Key | What it does |
| --- | --- |
| `↑` `↓` | Scroll a line. |
| `Space` `b`, `PgDn` `PgUp` | A page down, up. |
| `Tab` `Shift+Tab` | The next, the previous heading: sub-issues, activity. |
| `g g`, `Home` | The top. |
| `G`, `End` | The end, the newest activity. |
| `j` `k`, `→` `←`, `]` `[` | The next, the previous issue of the list. |
| `i` | The properties, under 120 columns. |
| `f` | Filter the list with a query. |
| `Esc` | Back. |

The issue keys of the list work here too: `s` `p` `a` `l` `r` `d` `.` `c` `C` `o` `e` `y` `Y` `m` `D` `u`, and `/` for the palette.

## Typing

- **Filter** (`f`): the query language of the app's `/` field ([Query language](/docs/finding/query)). The list narrows as you type and completions follow the word. `Tab` completes, `↵` applies, `Ctrl+U` clears, `Esc` cancels.
- **New issue** (`c`, `C`): one line, `#project @person !priority +label` and the title, with the query's completions. The card at the bottom shows the issue as it will be created, with up to three open issues that look like it. `Ctrl+E` writes a description in `$EDITOR`. `↵` creates; `Esc` keeps nothing.
- **Reply** (`r`): a box under the activity. `↵` sends, `Shift+Enter` makes a new line, `@` offers people and `Tab` completes the mention, `Ctrl+E` opens `$EDITOR`. `Esc` leaves the reply and keeps its draft for the next `r`.
- **Description** (`e`): the description in your editor (`$VISUAL`, then `$EDITOR`, else `vi`), saved when it changed. It is refused while the copy is behind the server, so it never writes over newer text.
- **Trash** (`D`): asks first. `y` or `↵` deletes, `Esc` or `n` does not. `u` brings it back.
- **Undo** (`u`): puts back the last change made in this TUI, then the one before. A field someone else changed since is left as it is.

## The palette

`/` or `Ctrl+K` opens the palette. It finds commands, issues, saved views and places: Open issues, My issues, each project and, signed in with `rsva login`, your other workspaces. A command that picks a value opens a page of values. Among the commands:

- **Go to project…**, **Open view…**, **Change workspace…**
- **Order issues by…**, which writes `order:` into the query
- **Change theme…**: the web's themes, dark and light, each shown as the cursor rests on it; the one picked is remembered
- **Dispatch queue**, **Create an issue…**, **Filter with a query…**, **Undo the last change**, **Quit**
- every action on the selected issue, with its key

`Esc`, or `Backspace` in an empty field, goes back to all commands.

## The queue

`g q` goes through the current list one card at a time.

| Key | What it does |
| --- | --- |
| `↵` | Read the whole issue. |
| `d` | Dispatch to Claude. |
| `→` | Approve: the project's first unstarted state (Todo in the default workflow), without an agent. Takes the `proposed` label off. |
| `←` | Skip: nothing changes. |
| `c` | Cancel the issue. |
| `o` | Open in the browser. |
| `u` | Undo the last decision. |
| `Esc` | Back to the list. |

The card of an issue labelled `proposed` says it was proposed by an agent and lists up to three open issues that look like it.

## The mouse

- A click on a row selects it; a click on the selected row opens it.
- A click on a key in the keys line, or on a hint in a panel, presses that key.
- A click on a link or a pull request opens it in the browser, `http` and `https` only. A click on an issue's key opens that issue. A click on a property opens its picker.
- A click outside an open palette, picker or `?` sheet closes it.
- The wheel scrolls.
- The TUI takes the mouse, so the terminal's own text selection needs `Shift`.

## Images

On the issue screen, images in the description and comments are drawn where the terminal speaks the kitty graphics protocol: Rex, Ghostty and kitty, but not inside tmux. Elsewhere an image shows as its caption. `RSVA_TUI_IMAGES=1` or `0` decides for any terminal.

Only files of the workspace on this server are fetched, with the TUI's own credential; an image from another host is never fetched. An image that is not a PNG, or is larger than 1200 pixels, is converted with macOS's `sips`. Images hide under panels.

## Pager and editor

The full log of a dispatch opens in your pager: `RSVA_PAGER`, then `PAGER`, else `less`. The TUI owns the screen, so `cat` or an empty value still means `less` here. Texts open in `$VISUAL`, then `$EDITOR`, else `vi`. While the pager or the editor runs, the TUI gives the terminal back and returns when it closes.

## Rex

Rex is Superlogical's terminal. The TUI knows it:

- In Rex the TUI reports itself as the program `recursiva` while its screen is up, and clears that when it leaves the screen.
- The status line shows the name of the Rex session the TUI runs in.
- Each dispatched agent runs in a Rex session of its own. The list shows the agent's state on its issue's row, and the head counts the agents running and waiting. See [Dispatch an agent](/docs/terminal/dispatch).
