heartleo/zlib: a Go CLI for Z-Library search, download and Kindle delivery

What heartleo/zlib solves, and for whom

Z-Library access from a terminal is normally a sequence of manual steps: find a mirror that is not blocked, log in through a browser, locate the book, download it, then move the file somewhere useful. heartleo/zlib collapses that into one binary written in Go. It handles login, search, download, download history, a daily quota view, and delivery to a Kindle address, all from the command line.

The audience is narrow and specific. This is for people who already use Z-Library and want it scriptable, and for people running Claude Code or Codex who want an agent to fetch a book on request. The README ships plugins for both: a Claude Code plugin installed through a marketplace command, and a skills-only Codex plugin. The README also describes a --json flag on search, which is the intended path for scripts and plugins rather than screen-scraping the table output.

It is not a general ebook manager. There is no library organisation, no metadata editing, no conversion. It fetches files and sends them onward.

How the mirror probe, EAPI mode and session storage fit together

The design centres on one problem the README states plainly: Z-Library mirrors change often, and most current web domains put automated requests behind DiamWall, so there is no default domain that stays correct. Every command resolves its mirror from ZLIB_DOMAIN before anything else.

The doctor subcommand probes candidate domains and classifies each one. The README lists healthy, challenged, diamwall_blocked, http_error, redirect_loop and network_error as the possible results. A challenged domain answered with Z-Library's own JavaScript proof-of-work page; the client solves that challenge automatically, so challenged is as usable as healthy. Only the last four are unusable. That distinction matters because it means a naive check for HTTP 200 would reject domains this tool can actually use.

EAPI is the unofficial mobile app API, selected with --eapi. The README says search, profile, history, book details, downloads and Kindle delivery then use the EAPI path where needed, and that book references switch to id:hash form, for example 115066162:e9f13b. The README points to docs/eapi.md for the endpoint list and stability notes, and calls the API unofficial.

Sessions land in ~/.config/zlib/session.json. A successful login also records the domain it used as ZLIB_DOMAIN in ~/.config/zlib/.env, leaving other keys in that file untouched. Two things outrank that file: a real environment variable, and a .env in the working directory. A stale value in either shadows what login wrote, which is the mechanism behind the failure the README calls the single most common cause of a login that succeeds and a next command that fails.

Installing heartleo/zlib and running a first search

The README lists five install paths. Homebrew and winget cover macOS, Linux and Windows; a curl script covers macOS and Linux; go install and a source build cover everything else. The Go toolchain must be 1.25 or newer, as stated in the README badge and in go.mod.

brew install heartleo/tap/zlib

On Windows the equivalent is winget install heartleo.zlib. For a source build, clone the repository and build the cmd/zlib package.

git clone https://github.com/heartleo/zlib
cd zlib
go build -o zlib ./cmd/zlib

Before logging in, probe candidate mirrors. The README's recommended setup is to run doctor with --eapi, pick a domain it reports as healthy or challenged, export it, then log in.

zlib doctor --eapi
export ZLIB_DOMAIN=https://z-lib.gd
zlib login --eapi
zlib search "dune"

The domain in that example is the one the README uses, not a recommendation. You should substitute whatever doctor reports as usable from your network. After login, the domain is written to ~/.config/zlib/.env so later shells do not need the export.

Search without arguments opens an interactive picker: type a query, browse with the arrow keys, switch pages with left and right, press Enter to download. For scripted use, ask for a table or JSON.

zlib search "dune" --page 2
zlib search "dune" --json
zlib search "python crash course" --ext epub --ext pdf

The --ext filter is repeatable, and --full-title disables title truncation. Downloads take a book reference and accept a directory and Kindle delivery in the same call.

zlib download Gz31nyAV5E --dir ./books --send-to-kindle

The README notes that --dir expands a leading tilde itself, so it works whether or not the shell already expanded it, and that ZLIB_DOWNLOAD_DIR can be set once to avoid repeating the folder.

Where heartleo/zlib breaks, and what it will not do for you

The largest limitation is stated in the README itself: there is no default domain, because a default would not stay correct. If every candidate you probe comes back diamwall_blocked, http_error, redirect_loop or network_error, the tool cannot proceed, and the README directs you to a troubleshooting section for the DiamWall issue. That is not a bug to wait out. It is a dependency on an external, moving target that the project cannot control.

The second limitation is the EAPI path. The README calls it the unofficial mobile app API and points to a separate document for stability notes. Anything built on an unofficial endpoint can change without notice, and the fallback the README describes, where an EAPI login that is refused falls back to the HTML form and continues in EAPI mode, is a mitigation rather than a guarantee. The README argues the fallback session is not degraded because the EAPI authenticates on nothing but remix_userid and remix_userkey, and the HTML form hands out the same pair. That reasoning is sound as far as it goes, but it assumes the HTML form keeps issuing that pair.

Third, cookie import is a credential-handling path. The README says --cookies imports a Netscape/Mozilla-format file and that only unexpired root cookies matching --domain are saved to the session, and it warns that cookie files contain reusable credentials and should be kept private. That is a real operational constraint, not a footnote.

Finally, this is not the right tool if you want a stable programmatic interface to a book catalogue. It is a CLI over a service whose access points rotate, and its own README treats mirror churn as the primary support burden.

heartleo/zlib compared with a general download manager

A general download manager such as aria2 or curl takes a URL and writes bytes. heartleo/zlib takes a title or a book reference and does the work in between: it authenticates against Z-Library, resolves the book, applies format filters, tracks a daily quota, keeps a paginated download history, and can hand the resulting file to a Kindle address over SMTP. The .env.example file lists ZLIB_SMTP_PWD alongside ZLIB_DOMAIN, ZLIB_PROXY and ZLIB_DOWNLOAD_RETRIES, which is where the Kindle delivery credentials live.

The difference in approach is that a download manager is agnostic and therefore indifferent to whether the source is reachable, while this tool is specialised and therefore responsible for reachability. That responsibility is why domain_probe.go, domain_policy.go and challenge.go exist in the repository tree alongside client.go and download.go. If you only need to fetch a file whose URL you already have, a download manager is simpler and has no mirror problem. If you need to go from a title to a file on your Kindle, the download manager has nothing to offer and this tool does.

Maintenance, release cadence and the MIT licence

The last push to the repository was on 2026-09-07, and the repository is not archived. Releases are frequent and small: v0.0.6 on 2026-07-08, v0.0.7 on 2026-08-23, and v0.0.8 on 2026-09-04. The version numbers are still in the 0.0.x range, which is consistent with a tool whose interface can move between releases.

Upgrade cost is mostly the cost of re-probing mirrors. Because the domain is recorded in ~/.config/zlib/.env at login time, a mirror that dies after you logged in will not fix itself; the README's own guidance is to run doctor again and set a new ZLIB_DOMAIN. Budget for that as recurring work rather than a one-time setup step.

The licence is MIT, which is permissive and places few obligations on how you redistribute or modify the code. That says nothing about the legality of what you download through it. The tool is a client for a third-party service, and the copyright status of the material you retrieve is a separate question the repository does not address. Nothing here is legal advice, and the MIT grant covers the software, not the content.

Editorial conclusion

Adopt heartleo/zlib if you already know which Z-Library mirror answers from your network and you want search, download and Kindle delivery in one binary, or if you are wiring book retrieval into Claude Code or Codex. Skip it if you expect a tool that finds a mirror for you, if you cannot keep ZLIB_DOMAIN current, or if you need a stable API: the project is at v0.0.8 and documents EAPI as unofficial. Verify two things before committing: run zlib doctor --eapi against your candidate domains and confirm at least one reports healthy or challenged, and confirm on your own hardware that the session written to ~/.config/zlib/session.json survives a shell restart. If doctor reports only diamwall_blocked, http_error, redirect_loop or network_error for every candidate, the tool has nothing to work with.

Frequently asked questions

Official sources

1. heartleo/zlib on GitHub
2. License: MIT
3. Project website
4. README
5. Releases