docs~/terminal/tui.md
/esc
~/terminal/tui.md
terminal/tui.md · 9 min · updated 2026-11-15 · as markdown

# The terminal app

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). It is built for macOS.

Start it

rsva tui comes with rsva: install it as 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, 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). 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.