
zlib
io.github.heartleo/zlib
Search and download Z-Library books, fix e-book metadata, and send books to Kindle or WeRead.
Documentation
A Z-Library CLI for you and your AI agents.
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, choose a download directory
🖼️ Covers — show book covers in the terminal
🏷️ Metadata — look up and edit e-book metadata
📖 Send to Kindle — deliver files to your Kindle address
🌏 Send to WeRead — import books into your WeRead shelf
🕒 Profile — check your daily download quota
🎨 Themes — change the color theme
🌐 Network — check which mirrors work, trust your own mirror, 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-cli
[!IMPORTANT] The Homebrew formula was renamed from
zlibtozlib-cli.
Use the command above. The installed command is stillzlib.
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, metadata, 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 |
On a terminal with Kitty graphics or Sixel support, at least 100 columns by 20
rows, the selected book's card shows its cover; other terminals show text only
(Book covers). /meta opens a file picker, then looks the
chosen e-book up online and lets you review each field before writing it. It
needs no login (E-book metadata).
Settings live under /config (network, downloads, search formats, metadata, Kindle, WeRead). 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 |
| Send to WeRead | zlib weread import ./book.epub |
| Show a file's metadata | zlib meta book.epub |
| Look up a file's metadata | zlib meta book.epub --fetch |
| Edit a file's metadata | zlib meta book.epub -t "Dune" -a "Frank Herbert" --rename |
To download, replace id:hash with a book's complete id from
the results:
zlib download "id:hash"
Run zlib <command> --help for flags. Usage covers filters,
pagination, and download options.
Agent setup
Install the plugin, or register the MCP server (zlib mcp). The plugin brings
the skills and the MCP server. If zlib is missing, the skills install it on
first use; the MCP server needs it on PATH. Log in yourself with zlib login
so your password stays out of chat.
Claude Code
Plugin:
/plugin marketplace add heartleo/zlib
/plugin install zlib@zlib-plugin-cc
Codex
Plugin:
codex plugin marketplace add heartleo/zlib
codex plugin add zlib@zlib
Grok
Plugin:
grok plugin marketplace add heartleo/zlib
grok plugin install zlib --trust
MCP server
Register zlib mcp as a local stdio server. zlib must be on PATH and signed in:
# Claude Code
claude mcp add -s user zlib -- zlib mcp
# Codex
codex mcp add zlib -- zlib mcp
# Grok
grok mcp add zlib -- zlib mcp
Add --read-only after mcp to hide download, history deletion, Kindle
delivery, WeRead import and metadata editing. See MCP server for other clients, flags, and tools.
Documentation
| Guide | Covers |
|---|---|
| Installation | Install methods, source builds, zlib update |
| Usage | Search, downloads, favorites, history |
| Terminal interface | Commands and keyboard controls |
| Book covers | Supported terminals, limits and cache |
| E-book metadata | Lookup sources, editing, renaming, formats |
| Configuration | Domains, proxies, folders, configuration paths |
| Themes | Available palettes and preview controls |
| Kindle | SMTP setup and delivery |
| WeRead | QR login and imports into WeRead |
| MCP server | Client setup, flags, and tools for zlib mcp |
| 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
https://github.com/heartleo/zlib/releases/download/v0.0.15/zlib_0.0.15_linux_x86_64.mcpb# mcpb: https://github.com/heartleo/zlib/releases/download/v0.0.15/zlib_0.0.15_linux_x86_64.mcpbhttps://github.com/heartleo/zlib/releases/download/v0.0.15/zlib_0.0.15_linux_arm64.mcpb# mcpb: https://github.com/heartleo/zlib/releases/download/v0.0.15/zlib_0.0.15_linux_arm64.mcpbhttps://github.com/heartleo/zlib/releases/download/v0.0.15/zlib_0.0.15_darwin_x86_64.mcpb# mcpb: https://github.com/heartleo/zlib/releases/download/v0.0.15/zlib_0.0.15_darwin_x86_64.mcpbhttps://github.com/heartleo/zlib/releases/download/v0.0.15/zlib_0.0.15_darwin_arm64.mcpb# mcpb: https://github.com/heartleo/zlib/releases/download/v0.0.15/zlib_0.0.15_darwin_arm64.mcpbhttps://github.com/heartleo/zlib/releases/download/v0.0.15/zlib_0.0.15_windows_x86_64.mcpb# mcpb: https://github.com/heartleo/zlib/releases/download/v0.0.15/zlib_0.0.15_windows_x86_64.mcpbhttps://github.com/heartleo/zlib/releases/download/v0.0.15/zlib_0.0.15_windows_arm64.mcpb# mcpb: https://github.com/heartleo/zlib/releases/download/v0.0.15/zlib_0.0.15_windows_arm64.mcpb