The interactive terminal reader (TUI)

Nyora ships an interactive terminal reader for browsing sources, searching, and listing chapter pages without writing any code. It is built on the same in-process nyora.direct.Nyora client used everywhere else, so it needs no helper, no Node, and no JVM.

Note

The TUI is part of the base install (pip install nyora pulls in rich and textual as core dependencies). There is nothing extra to install.

Starting it

There are two equivalent ways to launch it:

nyora-cli      # bare command, no subcommand -> launches the TUI
nyora-tui      # dedicated launcher

Important

Running nyora-cli with no subcommand launches the TUI. Any subcommand (nyora-cli sources, nyora-cli search ..., …) runs the non-interactive CLI instead — see the CLI manual. Both nyora-cli and nyora-tui ultimately call nyora_tui.app.main().

Requirements: an interactive terminal

The reader draws a full-screen UI and reads keystrokes, so it requires a real TTY on both stdout and stdin.

If stdout (or stdin) is not a TTY — for example under CI, when piped (nyora-cli | cat), or redirected to a file — the reader does not start. Instead it prints a short notice and exits cleanly with code 0:

Nyora terminal reader needs an interactive terminal (a TTY).
stdout is not a TTY here (piped, redirected, or non-interactive shell).
Run 'nyora-cli' (or 'nyora-tui') directly in a terminal to use it.
For scripting, use subcommands instead, e.g. 'nyora-cli sources'.

This is intentional: it means a bare nyora-cli is always safe to run from a script or hook without hanging or crashing. For automation, use the CLI subcommands (with --json) or the library directly.

Three frontends (automatic fallback)

The reader picks the richest frontend your environment supports, in order:

1. Textual — a full-screen app with panes, lists, and a footer. Used whenever textual is importable (it is, in the default install).

2. Rich — an interactive prompt with formatted tables, used if textual is unavailable.

3. Plain — a minimal numbered-list input() loop, used if neither rich nor textual is available.

All three share the same navigation flow and back-end, and all three degrade gracefully on network/parse errors (an error is shown in place; the UI never crashes).

Navigation flow

Every frontend walks the same path:

Sources  ->  Results (popular / search)  ->  Details + chapters  ->  Chapter pages

1. Sources — filter the source catalog by name or id, then open one.

2. Results — type a query to search, or leave it blank for popular. Browse the entries; pick one to open it.

3. Details — see authors, state, tags, and description, plus the chapter list. Pick a chapter.

4. Pages — the chapter’s image URLs are listed (the reader resolves them; it does not download images — use nyora-cli download to save a chapter as a .cbz archive).

Keybindings and controls

Textual frontend

Key	Where	Action
type text	source filter / search box	Live-filter sources, or set the search query.
Enter	filter/search box	Submit; moves focus into the list (search refetches from page 1).
↑ / ↓, Enter	any list	Move the selection and open the highlighted item.
n	results screen	Next page (when more results are available).
p	results screen	Previous page.
Esc	results / details / pages	Go back one screen.
Esc	sources screen	Quit the app.
q	anywhere	Quit the app.

The header shows Nyora — embedded parser runtime; the footer lists the active keybindings for the current screen. Fetches run on background workers, so the UI stays responsive while loading.

Rich frontend (fallback)

Interaction is prompt-driven. At each prompt you type:

Input	Action
a number	Select that numbered row.
text	(Re)search with that text (on the results prompt) or filter sources.
+	Next page (results prompt, when a next page exists).
-	Previous page (results prompt).
b	Go back.
q	Quit.

On the chapter-pages view it prints the image URLs and waits for Enter to go back.

Plain frontend (last-resort fallback)

A numbered list with a single prompt accepting: a number to select, text to search, b to go back, and q to quit. The pages view prints the URLs and waits for Enter.

Exiting

• Textual: q or Esc from the sources screen.

• Rich/Plain: q at any prompt.

• Ctrl+C (or end-of-input) anywhere exits cleanly.

In all cases the process returns exit code 0, and the embedded nyora.direct.Nyora client is closed on the way out.

When to use the CLI instead

The TUI is for interactive exploration. For anything scripted or automated — listing sources, batch downloads, machine-readable output — use the nyora-cli subcommands with --json, or drive the library and the AI-agent guide directly.