The interactive terminal reader (TUI)

Nyora ships an interactive terminal reader for browsing sources, searching, reading chapters, and syncing a library without writing any code. It drives the same cloud nyora.Nyora client used everywhere else, so it needs no local server and no Node process.

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 a source sidebar, a results pane, and an in-terminal webtoon reader that renders chapter pages as images. Used whenever textual is importable (it is, in the default install).

2. Rich — an interactive prompt with formatted tables, used if textual is unavailable. This frontend also exposes the cloud sync account menu and synced library.

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 — in the Textual frontend the chapter’s images are downloaded and rendered inline as a continuous webtoon view (using the Kitty terminal graphics protocol where available, falling back to pixel rendering). In the Rich and Plain frontends the page image URLs are listed. To save a chapter to disk, use nyora-cli download for a .cbz archive.

Cloud sync in the reader

The Rich frontend has a built-in account menu and a synced library, backed by nyora.sync.NyoraSync (see the sync guide). At the “Filter sources” prompt you can type:

Input	Action
sync (or account)	Open the account menu — sign in with email + password, or sign out. When signed in, the prompt shows your email.
lib (or library)	Open your synced library — the favourites you have pushed to the cloud, joined with their manga metadata.

Sign-in tokens persist to ~/.config/nyora/sync.json, so the reader stays signed in across runs. When you open a manga’s details while signed in, the reader offers a “Favourite to library?” prompt — press f to push that manga to your cloud library (it lands in the nyora_manga and nyora_favourite tables). An empty library shows a hint to favourite manga with f from details.

Keybindings and controls

Textual frontend

Key	Where	Action
type text	source filter box (ctrl+f)	Live-filter the source list.
type text	search box (ctrl+s)	Set the search query for the current source.
Enter	filter / search box	Submit; the source list gains focus, or the search refetches.
↑ / ↓, Enter	any list	Move the selection and open the highlighted item.
ctrl+f	anywhere	Focus the source filter box.
ctrl+s	anywhere	Focus the search box.
j / k / Space	pages screen	Scroll the webtoon down / up / page-down.
b / Esc	results / details / pages	Go back one screen.
Esc	sources screen	Focus the source list.
q	anywhere	Quit the app.

The header shows Nyora; the footer lists the active keybindings for the current screen. Fetches and image downloads run on background workers, so the UI stays responsive while loading.

Rich frontend (fallback)

Interaction is prompt-driven. At the source prompt, sync/lib open the account and library views described above. At each list 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 from anywhere.

• 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 cloud nyora.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.