heartleo/zlib

zlib

A Z-Library CLI to search, download, and send books to Kindle, for you and AI agents like Claude Code and Codex.

English | 简体中文

Install · Quick start · Terminal interface · Commands · Agent setup · Docs

Features

🔍 Search — filter by year, language, and format; sort results\ 📚 Browse — favorites, recommendations, popular books, and download history\ 📥 Download — view book details and choose a download directory\ 📖 Send to Kindle — deliver files to your Kindle address\ 🕒 Profile — check your daily download quota\ 🎨 Themes — switch color themes with /theme\ 🌐 Network — find working mirrors with zlib doctor, or use a proxy\ 🤖 AI Agent Integration — integrate with Claude Code and Codex through Agent plugins

Install

macOS / Linux with Homebrew:

brew install heartleo/tap/zlib

macOS / Linux with the install script (installs to /usr/local/bin, may ask for sudo):

curl -fsSL https://raw.githubusercontent.com/heartleo/zlib/main/install.sh | sh

Windows with winget:

winget install --id heartleo.zlib --exact

Or download a binary from Releases and put it on your PATH. See Installation for Go installation, source builds, and upgrades.

Quick start

You need a Z-Library account. First, find a domain reachable from your network:

zlib doctor

Log in with a domain from the results. Replace the example URL below with one from your results; enter your email and password in the prompt:

zlib login --domain https://z-lib.gd
zlib tui

Press /, choose /search, enter a title, author, or ISBN, and press Ctrl+S. You can also type /search dune and press Enter. Select a book and press Enter to confirm the download.

Downloads default to the current directory. You can choose another folder before downloading. Login is saved locally; subsequent sessions only need zlib tui.

If no domain works or login fails, see Troubleshooting. Existing browser sessions can be imported as cookies.

Terminal interface

zlib tui opens one persistent shell. Every screen lists its keys at the bottom; these cover a first session:

| Key | Action | | --- | --- | | / | Open the command list: search, favorites, history, profile, settings, themes | | ↑/↓ or j/k | Select a book | | ←/→ | Previous or next page of results | | Enter | Download the selected book, after a confirmation | | Ctrl+F | Change the query and filters of the current search | | Esc | Go back | | /quit | Exit |

Settings live under /config (network, downloads, Kindle). See Terminal interface for every screen and key.

Commands

Pass a query for table output, or add --json for scripts:

zlib search "dune" --ext epub
zlib search "dune" --ext epub --json --count 10

| Task | Command | | --- | --- | | Browse favorites | zlib favorites | | Browse recommendations | zlib recommended | | Browse popular books | zlib most-popular | | Browse download history | zlib history | | Check account and quota | zlib profile | | Send to Kindle | zlib kindle send ./book.epub |

To download, replace id:hash with a book's complete id from the results:

zlib download "id:hash"

Run zlib --help for flags. Usage covers filters, pagination, and download options.

Agent setup

Install the plugin. If zlib is missing, the agent installs it on first use. Log in yourself with zlib login so your password stays out of chat.

Claude Code

Run inside Claude Code:

/plugin marketplace add heartleo/zlib
/plugin install zlib@zlib-plugin-cc

Codex

Run in your terminal:

codex plugin marketplace add heartleo/zlib
codex plugin add zlib@zlib

Then ask your agent:

Use zlib to find The Pragmatic Programmer in EPUB. Show the results before downloading.

Documentation

| Guide | Covers | | --- | --- | | Installation | Install methods, source builds, zlib update | | Usage | Search, downloads, favorites, history | | Terminal interface | Commands and keyboard controls | | Configuration | Domains, proxies, folders, configuration paths | | Themes | Available palettes and preview controls | | Kindle | SMTP setup and delivery | | Troubleshooting | Login and network problems |

Report bugs in Issues with your zlib version, OS, command, and error. Omit passwords, cookies, and session files. Report security vulnerabilities privately as described in SECURITY.md.

Star History