The `nyora-cli` command-line tool¶

This page is the complete user manual for nyora-cli, the command-line tool shipped with the Nyora Python package.

Important

nyora-cli and the nyora library are separate things.

The library is what you get with pip install nyora and import nyora — see the library guide.
nyora-cli is a console script that wraps the library for terminal use.

This page documents only the CLI tool.

```{admonition} Bare nyora-cli launches the TUI :class: tip

Running nyora-cli with no subcommand launches the interactive terminal reader (TUI) — it does not print help and exit. See the TUI guide. To script Nyora instead, always pass a subcommand (sources, search, popular, …).

## Installation

The CLI is installed with the package. `rich` and `textual` are core
dependencies, so pretty tables and the TUI work out of the box:

```bash
pip install nyora

Three equivalent entry points are installed (nyora, nyora-cli, nyora-tui). nyora and nyora-cli are the same program (nyora.cli:main); nyora-tui launches the TUI directly. This page uses nyora-cli throughout.

Synopsis¶

nyora-cli [--json] <command> [options]
nyora-cli                       # no command -> launches the TUI
nyora-cli --help                # lists all commands

--json is a global flag and must appear before the subcommand:

nyora-cli --json sources          # correct
nyora-cli sources --json          # WRONG: unknown option to `sources`

Global options¶

Option	Effect
`--json`	Emit raw JSON to stdout instead of pretty tables/text. Must come before the subcommand.
`-h`, `--help`	Show help and exit. Works on the program and on each subcommand.

`-s` / `--source` fuzzy resolution¶

Every command that targets a source (search, popular, latest, details, pages, download) takes a required -s SRC / --source SRC. SRC is matched case-insensitively as a substring against each source’s id and name, and the first match wins (sources are taken in catalog order). So -s mangadex, -s MangaDex, and -s dex typically all resolve to the same source. If nothing matches, the command exits non-zero with error: No bundled source matched '<SRC>'.

To see the exact ids and names available, run nyora-cli sources.

`sources` — list or search available sources¶

List the sources bundled with the parser runtime, optionally filtered.

nyora-cli [--json] sources [--search Q]

Arg / flag	Required	Default	Description
`--search Q`	no	(none)	Case-insensitive substring filter over each source’s `id` and `name`.

Example

nyora-cli sources --search dex

                Sources (1)
┏━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━┓
┃ id       ┃ name     ┃ lang ┃
┡━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━┩
│ mangadex │ MangaDex │ en   │
└──────────┴──────────┴──────┘

JSON (nyora-cli --json sources) emits an array of full source objects (asdict of each Source):

[
  {
    "id": "mangadex",
    "name": "MangaDex",
    "lang": "en",
    "base_url": "https://mangadex.org",
    "engine": "JavaScript",
    "content_type": "Manga",
    "is_installed": true,
    "is_pinned": false,
    "is_nsfw": false,
    "is_obsolete": false,
    "icon_url": "",
    "version": "",
    "notes": "",
    "can_uninstall": false
  }
]

`search` — search a source¶

nyora-cli [--json] search -s SRC [-p PAGE] QUERY

Arg / flag	Required	Default	Description
`-s`, `--source SRC`	yes	—	Source id or fuzzy name (see above).
`-p`, `--page PAGE`	no	`1`	One-based page number.
`QUERY`	yes	—	Free-text search query (positional).

Example

nyora-cli search -s mangadex "berserk"

              Search: berserk (2)
┏━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ # ┃ title      ┃ url                        ┃
┡━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 1 │ Berserk    │ /title/801513ba-a712-...   │
│ 2 │ Berserk... │ /title/15db0fff-95c0-...   │
└───┴────────────┴────────────────────────────┘

JSON emits a SearchPage object: {"entries": [...Manga...], "has_next_page": true}.

`popular` — list popular manga from a source¶

nyora-cli [--json] popular -s SRC [-p PAGE]

Arg / flag	Required	Default	Description
`-s`, `--source SRC`	yes	—	Source id or fuzzy name.
`-p`, `--page PAGE`	no	`1`	One-based page number.

Example

nyora-cli popular -s mangadex -p 2

Output is the same table shape as search (titled Popular (MangaDex)). JSON output is a SearchPage.

`latest` — list latest manga from a source¶

nyora-cli [--json] latest -s SRC [-p PAGE]

Identical flags and output shape to popular, but lists the most recently updated manga (titled Latest (<source name>)).

Example

nyora-cli latest -s mangadex

`details` — fetch manga details and chapters¶

nyora-cli [--json] details -s SRC URL

Arg / flag	Required	Default	Description
`-s`, `--source SRC`	yes	—	Source id or fuzzy name.
`URL`	yes	—	Manga URL (positional). Source-relative URLs like `/title/...` from a listing are accepted.

Example

nyora-cli details -s mangadex "/title/801513ba-a712-4b3e-9b3e-..."

Berserk
Authors: Kentaro Miura
State: ongoing
Tags: Action, Horror, Drama

A grim, brutal dark-fantasy epic...

                 Chapters (372)
┏━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ # ┃ title        ┃ url                     ┃
┡━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 1 │ Chapter 1    │ /chapter/aaaa-...       │
│ 2 │ Chapter 2    │ /chapter/bbbb-...       │
└───┴──────────────┴─────────────────────────┘

JSON emits a MangaDetails object: {"manga": {...Manga...}, "chapters": [...MangaChapter...]}.

`pages` — fetch chapter page image URLs¶

Resolve a chapter to its ordered list of image URLs (does not download).

nyora-cli [--json] pages -s SRC [--branch BRANCH] CHAPTER_URL

Arg / flag	Required	Default	Description
`-s`, `--source SRC`	yes	—	Source id or fuzzy name.
`--branch BRANCH`	no	(none)	Scanlation branch/translation to select, when the source has multiple.
`CHAPTER_URL`	yes	—	Chapter URL (positional).

Example

nyora-cli pages -s mangadex "/chapter/aaaa-bbbb-cccc"

https://cdn.example.org/data/abc/1.jpg
https://cdn.example.org/data/abc/2.jpg
https://cdn.example.org/data/abc/3.jpg

JSON emits an array of MangaPage objects, each {"url": "...", "headers": {...}}. The headers are the request headers the source requires to fetch each image (e.g. a Referer).

`download` — download a chapter as a `.cbz`¶

Resolve a chapter’s pages and pack them into a single .cbz archive — a standard Comic Book ZIP readable by any comic reader (Tachiyomi/Mihon, CDisplayEx, YACReader, Komga, etc.). Each page is fetched with a browser User-Agent, the source-required per-page headers, and a Referer derived from the image origin when one is not already supplied. Inside the archive the pages are stored in-order, named by zero-padded index with an extension inferred from the URL or the response Content-Type (e.g. 001.jpg, 002.webp).

nyora-cli [--json] download -s SRC [--branch BRANCH] [-o OUT] CHAPTER_URL

Arg / flag	Required	Default	Description
`-s`, `--source SRC`	yes	—	Source id or fuzzy name.
`--branch BRANCH`	no	(none)	Scanlation branch/translation to select.
`-o`, `--out OUT`	no	`<chapter>.cbz` in the current directory	Output path, not an image folder. If it ends in `.cbz` it is used as the file; otherwise it is treated as a directory that will contain `<chapter-slug>.cbz` (created if missing; `~` is expanded). The chapter slug is derived from the last path segment of `CHAPTER_URL`.
`CHAPTER_URL`	yes	—	Chapter URL (positional).

Example — write a named archive:

nyora-cli download -s mangadex -o ./berserk-ch1.cbz "/chapter/aaaa-bbbb-cccc"

Saved 3/3 pages to berserk-ch1.cbz

Example — drop a <chapter>.cbz into a directory (the path does not end in .cbz, so it is treated as a folder):

nyora-cli download -s mangadex -o ./comics "/chapter/aaaa-bbbb-cccc"

Saved 3/3 pages to comics/aaaa-bbbb-cccc.cbz

With no -o, the archive is written as <chapter-slug>.cbz in the current directory, where the slug is the last path segment of the chapter URL.

Individual page failures are reported to stderr (error: page N: ...) and skipped; the command still packs the rest. It exits 1 only when nothing was saved (no pages, or every page failed) — in that case no .cbz is written.

JSON emits the archive path and counts:

{
  "file": "berserk-ch1.cbz",
  "pages": 3,
  "total": 3
}

(pages is how many were fetched successfully; total is the chapter’s page count.)

`batch` — download every chapter of a manga as `.cbz` archives¶

Fetch a manga’s details and download every chapter, writing one .cbz archive per chapter into the output directory. Each file is named after a filesystem-safe version of the chapter title (<safe-chapter-title>.cbz). A chapter that yields no pages or fails to download is reported to stderr and skipped; the batch keeps going.

nyora-cli [--json] batch -s SRC [-o DIR] MANGA_URL

Arg / flag	Required	Default	Description
`-s`, `--source SRC`	yes	—	Source id or fuzzy name.
`-o`, `--out DIR`	no	`nyora-batch`	Output directory for the per-chapter `.cbz` files (created if missing; `~` is expanded).
`MANGA_URL`	yes	—	Manga URL (positional).

Example

nyora-cli batch -s mangadex -o ./berserk "/title/801513ba-a712-..."

Fetching manga details...
Found 372 chapters. Saving .cbz archives to berserk...

[1/372] Downloading Chapter 1...
  -> Chapter_1.cbz (18 pages)

[2/372] Downloading Chapter 2...
  -> Chapter_2.cbz (20 pages)

Batch complete. Wrote 372 .cbz archives (7012 pages total).

Each .cbz is a standard Comic Book ZIP, so the whole output directory drops straight into any comic reader or library server.

`update` — apply over-the-air parser updates¶

Fetch the latest OTA parser bundle and source catalog (SHA-256 verified) into the per-user cache. See OTA updates for the mechanism.

nyora-cli [--json] update [--force]

Arg / flag	Required	Default	Description
`--force`	no	off	Re-download and reinstall even when already up to date.

Example

nyora-cli update

Updated to OTA version 42
  bundle:  /Users/you/Library/Caches/nyora/ota/parsers.bundle.js
  sources: /Users/you/Library/Caches/nyora/ota/sources.json

When already current it prints Already up to date (OTA version 42).

JSON emits:

{
  "updated": true,
  "version": 42,
  "bundlePath": "/Users/you/Library/Caches/nyora/ota/parsers.bundle.js",
  "sourcesPath": "/Users/you/Library/Caches/nyora/ota/sources.json"
}

`serve` — run the REST helper-compatible server¶

Start NyoraServer, a stdlib HTTP server exposing the helper-compatible REST API backed by the embedded runtime. It writes the bound port to the standard helper port file, so other Nyora apps can attach. Runs in the foreground until Ctrl+C.

nyora-cli [--json] serve [--host HOST] [--port PORT]

Arg / flag	Required	Default	Description
`--host HOST`	no	`127.0.0.1`	Interface to bind.
`--port PORT`	no	`0`	Port to bind, or `0` for an ephemeral free port.

Example

nyora-cli serve --port 8765

Nyora server listening at http://127.0.0.1:8765
Press Ctrl+C to stop.

JSON emits {"baseUrl": "http://127.0.0.1:8765"} and then keeps serving.

The REST endpoints (/health, /sources, /sources/popular|latest|search, /manga/details, /manga/pages) are documented in the server guide and the AI-agent guide.

`version` — show package and OTA versions¶

nyora-cli [--json] version

Takes no options.

Example

nyora-cli version

nyora 0.3.0
OTA parsers: 42

OTA parsers shows the installed cache version, or bundled when nothing has been fetched yet (the package’s shipped fallback is in use).

JSON emits {"package": "0.3.0", "ota": 42} (ota is null when bundled).

Exit codes¶

Code	Meaning
`0`	Success. For `download`, at least one page was saved. The bare-`nyora-cli` TUI also returns `0` on a clean exit and when no interactive terminal is attached.
`1`	A `NyoraError` or `LookupError` was raised — e.g. an unresolved `-s/--source`, a parser/network failure, or (for `download`) no pages could be saved. The message is printed to stderr as `error: <message>`.
`2`	argparse usage error (unknown command/option, missing required argument).
`130`	Interrupted with `Ctrl+C` (`KeyboardInterrupt`).

Recipes¶

Pipe JSON into jq. Remember --json goes before the subcommand.

nyora-cli --json sources | jq -r '.[].id'

Get the first popular title’s URL, then its chapter count:

url=$(nyora-cli --json popular -s mangadex | jq -r '.entries[0].url')
nyora-cli --json details -s mangadex "$url" | jq '.chapters | length'

Download the first chapter of the top popular manga as a .cbz:

url=$(nyora-cli --json popular -s mangadex | jq -r '.entries[0].url')
ch=$(nyora-cli --json details -s mangadex "$url" | jq -r '.chapters[0].url')
nyora-cli download -s mangadex -o ./out "$ch"   # writes ./out/<chapter>.cbz

Download a chapter and print just the saved .cbz path:

nyora-cli --json download -s mangadex "$ch" | jq -r '.file'

Download every chapter of a manga, one .cbz each, into a folder:

nyora-cli batch -s mangadex -o ./berserk "$url"

List just the page image URLs of a chapter:

nyora-cli --json pages -s mangadex "$ch" | jq -r '.[].url'

Keep parsers current before a batch job:

nyora-cli update --force && nyora-cli --json sources | jq 'length'

Serve the REST API for another tool to attach to:

nyora-cli serve --port 8765 &
curl -s http://127.0.0.1:8765/sources | jq '.sources | length'

Open the interactive reader (must be a real terminal):

nyora-cli            # or: nyora-tui

The nyora-cli command-line tool¶

Synopsis¶

Global options¶

-s / --source fuzzy resolution¶

sources — list or search available sources¶

search — search a source¶

popular — list popular manga from a source¶

latest — list latest manga from a source¶

details — fetch manga details and chapters¶

pages — fetch chapter page image URLs¶

download — download a chapter as a .cbz¶

batch — download every chapter of a manga as .cbz archives¶

update — apply over-the-air parser updates¶

serve — run the REST helper-compatible server¶

version — show package and OTA versions¶

Exit codes¶

Recipes¶

The `nyora-cli` command-line tool¶

`-s` / `--source` fuzzy resolution¶

`sources` — list or search available sources¶

`search` — search a source¶

`popular` — list popular manga from a source¶

`latest` — list latest manga from a source¶

`details` — fetch manga details and chapters¶

`pages` — fetch chapter page image URLs¶

`download` — download a chapter as a `.cbz`¶

`batch` — download every chapter of a manga as `.cbz` archives¶

`update` — apply over-the-air parser updates¶

`serve` — run the REST helper-compatible server¶

`version` — show package and OTA versions¶