ftvcli

A TUI + CLI for browsing and mass-downloading Kindle firmware recorded by ftvdb.com, enriched with device names from kindlemodding.org.

FTVDB stores metadata and public source links only. ftvcli downloads directly from the source URLs in that database (official Amazon S3/CloudFront links); it does not host, mirror, or reupload anything, and it only covers Kindle e-readers — not Fire TV, Fire Tablet, Echo, or system component packages.

 ftvcli Kindle firmware · 32 devices · 639 firmware    db 2h ago · aria2c (auto) · names nickname · out .
────────────────────────────────────────────────────────────────────────────────────────────────────────
╭ Devices (32) ─────────────────┬╭ Versions — KT6 · Kindle Basic 5 (2024) ────────────────────────────────╮
│○ KT6 Kindle Basic 5 (2024) 17 ││○ 5.18.1        2025-03-25  s3                                        │
│○ PW6 Kindle Paperwhite 6   17 ││✓ 5.18.5        2025-09-16  s3                                        │
│○ KOA3 Kindle Oasis 3       36 ││○ 5.19.6        2026-08-03  s3                                        │
╰────────────────────────────────╯╰───────────────────────────────────────────────────────────────────────╯
 / kindle-basic-5 5.18.1-5.18.5
 Space select · d download · a all · u none · s sort · n names · e engine · t theme · ? help

Features

• All 32 Kindle devices / 639 deduplicated firmware records from FTVDB.
• Display names from kindlemodding (KT6), Amazon names, or FTVDB titles — toggle with n.
• Compact search: device names/nicknames/aliases plus version expressions.
• Download one version, all versions of a device, or a multi-device selection.
• Uses aria2c when available (multi-connection, resume), curl otherwise.
• Progress, speed, ETA, md5 verification, cancel/retry, resume via .part files.
• Cache with a 24 h TTL (background refresh), works offline afterwards.
• Dark/light adaptive TUI theme, auto-detected per terminal.

Install

Requires a Rust toolchain on x86_64 Linux:

cargo build --release
install -m755 target/release/ftvcli ~/.local/bin/ftvcli

Runtime: at least one of aria2c or curl on PATH.

TUI

Run ftvcli with no arguments.

Key	Action
/	focus search; Esc clears
Tab	switch devices / versions pane
Up/Down, PgUp/PgDn, g/G	navigate
Space	select device (all its versions) or a version
a / u	select all in pane / clear selection
d	download selection, or the focused device's versions
s	toggle version sort
i / Enter	details for the focused row
n	name mode: nickname → amazon → ftvdb
e	engine: auto → aria2c → curl
t	theme: auto → dark → light
r	refresh the database
o / O	set output directory / path template
x / c / C	downloads: clear finished / cancel item / cancel all
? / q	help / quit (or back)

Query language

Tokens are ANDed. Device tokens match nicknames, aliases, Amazon names, FTVDB titles, models, and package ids, ignoring punctuation. Version tokens support:

Form	Meaning
5.18.1	exact
5.18.*	prefix
5.18.1-5.18.5	inclusive range (5.18.1-, -5.18.5 allowed)
>=5.18.1, >, <=, <	comparison
~5.18	>=5.18, <5.19
@latest	newest matching version per device
@all	every matching version (required for device-only get)

kindle-basic-5 5.18.1-5.18.5
pw6 5.19.*
KT6 @latest
scribe @all
>5.18.0 <5.19.0

CLI

ftvcli devices [QUERY] [--name nickname|amazon|ftvdb] [--json]
ftvcli list    [QUERY] [--json] [--url-only]
ftvcli get     QUERY [--out DIR] [--template T] [-j N] [--engine auto|aria2c|curl]
                        [--force] [--dry-run] [--url-only] [--no-verify]
                        [--delete-on-mismatch]
ftvcli refresh [--force]
ftvcli config  path|show|init

Examples:

# preview the exact files and URLs for a range
ftvcli get 'kindle-basic-5 5.18.1-5.18.5' --dry-run

# download every Basic 5 (KT6) firmware with 4 parallel jobs
ftvcli get 'KT6 @all' -o ~/kindle-fw -j 4

# pipe URLs into your own tooling
ftvcli get 'rose @latest' --url-only | xargs -n1 curl -O

# newest Paperwhite 6 firmware into a flat layout
ftvcli get 'PW6 @latest' --template 'kindle/{version}_{filename}'

Exit codes: 0 success, 1 download/verification failures, 2 environment or usage error (e.g. no engine found), 3 nothing matched. A device-only get without @all/@latest prints matches and exits 3 to avoid accidental multi-gigabyte downloads.

Output layout

Default template: firmware/{nickname}/{filename} (relative to -o, default .), which produces e.g. firmware/KT6/update_kindle_11th_2024_5.18.5.bin.

Placeholders: {nickname}, {amazon}, {title}, {model}, {version}, {year}, {filename}, {md5}, {host}. When a nickname is shared by several packages (K2/K3/K4/DX families), {nickname} expands to {nickname}-{model} (e.g. K3-K3WIFI-2010). Path components are sanitized.

Downloads go to a <file>.part temp file and are renamed and md5-verified on completion. Existing verified files are skipped unless --force.

Configuration

~/.config/ftvcli/config.toml (create with ftvcli config init):

[ui]
theme = "auto"           # auto | dark | light
glyphs = "unicode"       # unicode | ascii
name_mode = "nickname"   # nickname | amazon | ftvdb

[download]
jobs = 3
template = "firmware/{nickname}/{filename}"
out_dir = "."
engine = "auto"

[db]
ttl_hours = 24

Device-name overrides: ~/.config/ftvcli/models.map.toml

[map]
"com.lab126.eink.sauza.os" = "KT"   # any generation_nickname from models.json

Environment: FTVCLI_CACHE_DIR, FTVCLI_CONFIG_DIR, FTVCLI_THEME, FTVCLI_NAME, NO_COLOR. Precedence: CLI flag > env > config > default.

Cache lives in ~/.cache/ftvcli/ and is refreshed automatically after 24 h or with r / ftvcli refresh.

Credits

Firmware metadata: FTVDB (MIT). Device names and model data: kindlemodding.org. All trademarks belong to their respective owners. Verify checksums and compatibility yourself; firmware listed here is downloaded from third-party public sources that FTVDB and this tool do not control.

Development

cargo test          # unit + offline CLI integration tests
cargo fmt --check
cargo clippy --all-targets -- -D warnings

See SPEC.md for the full design.