zlib

package module
v0.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 8, 2026 License: MIT Imports: 23 Imported by: 0

README

zlib

A CLI for Z-Library.

Go version CI Release Downloads License

English | 中文

search demo

Features

  • 🔍 Interactive search — browse results with ↑/↓, switch pages with ←/→
  • 📥 Book download — by book ID, from search results, with live progress
  • 📚 Download history — paginated history browser with download support
  • 📖 Send to Kindle — deliver files to your Kindle address
  • 🕒 Usage profile — view daily download quota
  • 🎨 Themes — auto, mocha, latte, dracula, tokyo, nord, gruvbox
  • 🌐 Proxy & custom domain support for restricted networks

Install

Homebrew (macOS / Linux):

brew install heartleo/tap/zlib

winget (Windows):

winget install heartleo.zlib

curl (macOS / Linux):

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

Prebuilt binaries — download from GitHub Releases

Go install (requires Go 1.25+):

go install github.com/heartleo/zlib/cmd/zlib@latest

Build from source:

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

zlib ships a Claude Code plugin, so Claude can search and download books for you.

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

/zlib "the pragmatic programmer" to search and download. /zlib:kindle sends a book to your Kindle.

Quick Start

zlib login
zlib search        # interactive mode
zlib search "dune" # static table

Commands

login

login demo

zlib login
zlib login --email you@example.com --password secret

Saves session to ~/.config/zlib/session.json.

logout
zlib logout

search demo static

Without arguments, opens an interactive picker:

  • type a query and confirm
  • browse results with ↑/↓
  • switch pages with ←/→
  • press Enter to download
zlib search # interactive mode
zlib search "dune" --page 2 # static table
zlib search "dune" --json   # machine-readable output for scripts and plugins

Filter by file format with --ext (or its alias --format), repeatable.

zlib search "python crash course" --ext epub --ext pdf

Use --full-title to disable title truncation

zlib search "civilized to death" --full-title
download
zlib download Gz31nyAV5E
zlib download Gz31nyAV5E --dir ./books --send-to-kindle

Press Ctrl+C to cancel. Incomplete files are removed automatically.

history

history demo

Without flags, opens an interactive history browser:

  • browse with ↑/↓, switch pages with ←/→
  • press Enter to re-download
zlib history
zlib history --download Gz31nyAV5E --dir ./books
zlib history --format epub
zlib history --json   # machine-readable, always non-interactive
profile

profile demo

zlib profile
zlib profile --json
kindle

kindle demo

Configure Kindle delivery settings:

  • recipient Kindle address
  • sender address
  • SMTP host and port

SMTP password is never stored on disk — set ZLIB_SMTP_PWD instead.

zlib kindle                  # configure
zlib kindle send             # pick a file interactively
zlib kindle send ./dune.epub # send a local file

Supported formats: EPUB PDF MOBI TXT DOC DOCX RTF HTML

theme
zlib theme           # show current
zlib theme auto      # follow terminal background
zlib theme nord      # set globally

Available: auto · mocha · latte · dracula · tokyo · nord · gruvbox

Configuration

Keep secrets like ZLIB_SMTP_PWD out of your shell history — put them in an .env file instead of exporting them inline. zlib reads env vars with this precedence: real environment > working-directory .env > ~/.config/zlib/.env. The global file is the recommended home for machine-wide values.

Variable Description
ZLIB_DOMAIN Override the default Z-Library domain
ZLIB_PROXY Proxy URL, e.g. http://127.0.0.1:7890
ZLIB_SMTP_PWD SMTP password for Kindle delivery
ZLIB_THEME Override theme without changing config

Edit the global env file (~/.config/zlib/.env, one KEY=value per line):

mkdir -p ~/.config/zlib && touch ~/.config/zlib/.env && chmod 600 ~/.config/zlib/.env
# open it in your editor:
notepad "$env:USERPROFILE\.config\zlib\.env"   # Windows (PowerShell)
open -t ~/.config/zlib/.env                       # macOS
${EDITOR:-nano} ~/.config/zlib/.env               # Linux

Star History

Star History Chart

Documentation

Index

Constants

View Source 
const (
	DefaultDomain = "https://z-lib.sk"
	TorDomain     = "http://bookszlibb74ugqojhzhg2a63w5i2atv5bqarulgczawnbmsb6s6qead.onion"
	EnvDomain     = "ZLIB_DOMAIN"
	EnvProxy      = "ZLIB_PROXY"
)

Variables

View Source 
var (
	ErrLoginFailed    = errors.New("zlibrary: login failed")
	ErrNotLoggedIn    = errors.New("zlibrary: not logged in, call Login first")
	ErrNoDomain       = errors.New("zlibrary: no working domain found")
	ErrEmptyQuery     = errors.New("zlibrary: search query is empty")
	ErrNoID           = errors.New("zlibrary: no book ID provided")
	ErrInvalidProxy   = errors.New("zlibrary: proxy_list must be a non-empty slice")
	ErrParseFailed    = errors.New("zlibrary: failed to parse page")
	ErrSessionExpired = errors.New("zlibrary: session expired, run `zlib login` to re-authenticate")
	ErrPhraseMinWords = errors.New("zlibrary: phrase search requires at least 2 words")
)
View Source 
var (
	Version = "dev"
	Commit  = "none"
	Date    = "unknown"
)

Functions

func BuildBookURL 

func BuildBookURL(domain, bookID string) string

func BuildDownloadsPageURL 

func BuildDownloadsPageURL(domain string, page int) string

func BuildDownloadsURL 

func BuildDownloadsURL(domain string) string

func BuildFullTextSearchURL 

func BuildFullTextSearchURL(domain, query, searchType string) string

func BuildHistoryURL 

func BuildHistoryURL(domain string, page int) string

func BuildSearchURL 

func BuildSearchURL(domain, query string) string

func CurrentDefaultDomain 

func CurrentDefaultDomain() string

func SendToKindle 

func SendToKindle(filePath string, cfg KindleConfig, smtpPassword string) error

func SetDefaultDomain 

func SetDefaultDomain(domain string)

Types

type Book 

type Book struct {
	ID          string   `json:"id"`
	ISBN        string   `json:"isbn,omitempty"`
	URL         string   `json:"url"`
	Cover       string   `json:"cover,omitempty"`
	Name        string   `json:"name"`
	Authors     []string `json:"authors,omitempty"`
	Publisher   string   `json:"publisher,omitempty"`
	Year        string   `json:"year,omitempty"`
	Language    string   `json:"language,omitempty"`
	Extension   string   `json:"extension,omitempty"`
	Size        string   `json:"size,omitempty"`
	Rating      string   `json:"rating,omitempty"`
	Quality     string   `json:"quality,omitempty"`
	Description string   `json:"description,omitempty"`
	Categories  string   `json:"categories,omitempty"`
	Edition     string   `json:"edition,omitempty"`
	DownloadURL string   `json:"download_url,omitempty"`
}

type Booklist 

type Booklist struct {
	Name        string `json:"name"`
	URL         string `json:"url"`
	Description string `json:"description,omitempty"`
	Author      string `json:"author,omitempty"`
	Count       string `json:"count,omitempty"`
	Views       string `json:"views,omitempty"`
}

type BooklistResult 

type BooklistResult struct {
	Lists      []Booklist `json:"lists"`
	Page       int        `json:"page"`
	TotalPages int        `json:"total_pages"`
}

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func NewClient 

func NewClient(opts ...ClientOption) *Client

func (*Client) Cookies 

func (c *Client) Cookies() map[string]string

func (*Client) Domain 

func (c *Client) Domain() string

func (*Client) Download 

func (c *Client) Download(downloadURL, destDir string, progressFn func(written, total int64)) (DownloadResult, error)

func (*Client) DownloadHistory 

func (c *Client) DownloadHistory(page int) (DownloadHistoryResult, error)

func (*Client) DownloadWithContext 

func (c *Client) DownloadWithContext(ctx context.Context, downloadURL, destDir string, progressFn func(written, total int64)) (DownloadResult, error)

func (*Client) FetchBook 

func (c *Client) FetchBook(id string) (Book, error)

func (*Client) FetchBookDetails 

func (c *Client) FetchBookDetails(ids []string) map[string]Book

func (*Client) FullTextSearch 

func (c *Client) FullTextSearch(query string, page, count int, opts *FullTextSearchOptions) (SearchResult, error)

func (*Client) GetLimits 

func (c *Client) GetLimits() (DownloadLimit, error)

func (*Client) Login 

func (c *Client) Login(email, password string) error

func (*Client) Logout 

func (c *Client) Logout()

func (*Client) Search 

func (c *Client) Search(query string, page, count int, opts *SearchOptions) (SearchResult, error)

func (*Client) SetCookies 

func (c *Client) SetCookies(cookies map[string]string)

func (*Client) SetDomain 

func (c *Client) SetDomain(domain string)

type ClientOption 

type ClientOption func(*Client)

func WithDomain 

func WithDomain(domain string) ClientOption

func WithOnion 

func WithOnion(proxyURL string) ClientOption

func WithProxy 

func WithProxy(proxyURL string) ClientOption

type DownloadHistoryItem 

type DownloadHistoryItem struct {
	// ID is the alphanumeric book ID extracted from URL. The parser leaves it
	// empty; consumers that need it (e.g. the CLI's --json output) derive it
	// from URL.
	ID          string `json:"id,omitempty"`
	Name        string `json:"name"`
	URL         string `json:"url"`
	DownloadURL string `json:"download_url,omitempty"`
	Extension   string `json:"extension,omitempty"`
	Size        string `json:"size,omitempty"`
	Date        string `json:"date"`
}

type DownloadHistoryResult 

type DownloadHistoryResult struct {
	Items      []DownloadHistoryItem `json:"items"`
	Page       int                   `json:"page"`
	TotalPages int                   `json:"total_pages"`
}

type DownloadLimit 

type DownloadLimit struct {
	DailyAmount    int    `json:"daily_amount"`
	DailyAllowed   int    `json:"daily_allowed"`
	DailyRemaining int    `json:"daily_remaining"`
	DailyReset     string `json:"daily_reset"`
}

type DownloadResult 

type DownloadResult struct {
	FilePath string
	Size     int64
}

type Extension 

type Extension string
const (
	ExtTXT  Extension = "TXT"
	ExtPDF  Extension = "PDF"
	ExtFB2  Extension = "FB2"
	ExtEPUB Extension = "EPUB"
	ExtLIT  Extension = "LIT"
	ExtMOBI Extension = "MOBI"
	ExtRTF  Extension = "RTF"
	ExtDJV  Extension = "DJV"
	ExtDJVU Extension = "DJVU"
	ExtAZW  Extension = "AZW"
	ExtAZW3 Extension = "AZW3"
)

func (Extension) String 

func (e Extension) String() string

type FullTextSearchOptions 

type FullTextSearchOptions struct {
	SearchOptions
	Phrase bool
}

type KindleConfig 

type KindleConfig struct {
	To       string `json:"to"`
	From     string `json:"from"`
	SMTPHost string `json:"smtp_host"`
	SMTPPort int    `json:"smtp_port"`
}

func (KindleConfig) Validate 

func (c KindleConfig) Validate() error

type Language 

type Language string
const (
	LangEnglish    Language = "english"
	LangChinese    Language = "chinese"
	LangRussian    Language = "russian"
	LangFrench     Language = "french"
	LangGerman     Language = "german"
	LangSpanish    Language = "spanish"
	LangJapanese   Language = "japanese"
	LangKorean     Language = "korean"
	LangItalian    Language = "italian"
	LangPortuguese Language = "portuguese"
	LangArabic     Language = "arabic"
	LangDutch      Language = "dutch"
	LangPolish     Language = "polish"
	LangTurkish    Language = "turkish"
	LangHindi      Language = "hindi"
)

type OrderOption 

type OrderOption string
const (
	OrderPopular OrderOption = "popular"
	OrderNewest  OrderOption = "date_created"
	OrderRecent  OrderOption = "date_updated"
)

func (OrderOption) String 

func (o OrderOption) String() string

type SearchOptions 

type SearchOptions struct {
	Exact      bool
	FromYear   int
	ToYear     int
	Languages  []Language
	Extensions []Extension
}

type SearchResult 

type SearchResult struct {
	Books      []Book `json:"books"`
	Page       int    `json:"page"`
	TotalPages int    `json:"total_pages"`
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
zlib command
internal
cli
config
tableprinter

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.