Book Tools

Search and download books from multiple sources through a unified CLI.

Language

Match user's language: Respond in the same language the user uses.

Backends

Preflight

Before any workflow, run preflight to check environment readiness:

python3 ${SKILL_PATH}/scripts/book.py preflight

Returns standardized JSON:

{
  "ready": true,
  "dependencies": { "python3": {"status": "ok"}, "requests": {"status": "ok"} },
  "credentials": { "zlib": {"status": "configured"}, "annas_api_key": {"status": "not_configured"} },
  "services": { "annas_binary": {"status": "ok"} }
}

• If ready: true — proceed directly to the Workflow section.
• If ready: false — follow the Check/Fix table below, then run the Setup flow.

Setup (First-Time Only)

Only run setup when preflight reports ready: false. Guide the user through configuration interactively.

Step 1: Install Dependencies

bash ${SKILL_PATH}/scripts/setup.sh install-deps

Step 2: Configure Credentials

Credentials are stored in ~/.claude/book-tools/.env. Create the file from the skill's bundled template:

mkdir -p ~/.claude/book-tools
# Only copy if .env does not already exist — never overwrite existing credentials
if [ ! -f ~/.claude/book-tools/.env ]; then
  cp ${SKILL_PATH}/scripts/.env.example ~/.claude/book-tools/.env
else
  echo "Existing .env found — skipping copy to preserve your credentials."
fi

The .env file looks like this:

# Z-Library credentials
ZLIB_EMAIL=your_email@example.com
ZLIB_PASSWORD=your_password_here

# Anna's Archive (optional, requires donation for API key)
# ANNAS_SECRET_KEY=your_api_key_here

IMPORTANT: Do NOT ask the user for credentials directly in chat. Instead:

1. Create the .env file (or .env.example template)
2. Tell the user to edit ~/.claude/book-tools/.env with their credentials
3. Wait for the user to confirm they've filled it in
4. Then proceed with search

Step 3: Verify

python3 ${SKILL_PATH}/scripts/book.py preflight

Confirm ready: true before proceeding.

Credential Storage

Canonical path: ~/.claude/book-tools/.env — this is the single place users should edit credentials.

On first successful Z-Library login, session tokens are automatically cached in ~/.claude/book-tools/config.json for performance. This file is auto-managed — do not edit it manually. If login issues occur, delete config.json and the script will re-login using .env credentials.

Workflow

The typical flow is: search → pick → download.

1. Search

# Auto-detect backend (tries zlib first, then annas)
python3 ${SKILL_PATH}/scripts/book.py search "machine learning" --limit 10

# Z-Library with filters
python3 ${SKILL_PATH}/scripts/book.py search "deep learning" --source zlib --lang english --ext pdf --limit 5

# Anna's Archive
python3 ${SKILL_PATH}/scripts/book.py search "reinforcement learning" --source annas

# Chinese books
python3 ${SKILL_PATH}/scripts/book.py search "莱姆 索拉里斯" --source zlib --lang chinese --limit 5

Output (JSON to stdout):

{
  "source": "zlib",
  "count": 5,
  "books": [
    {
      "source": "zlib",
      "id": "12345",
      "hash": "abc123def",
      "title": "Deep Learning",
      "author": "Ian Goodfellow",
      "year": "2016",
      "language": "english",
      "extension": "pdf",
      "filesize": "22.5 MB"
    }
  ]
}

2. Present Results to User

After searching, present results as a numbered table so the user can pick:

| # | Title | Author | Year | Format | Size |
|---|-------|--------|------|--------|------|
| 1 | Deep Learning | Ian Goodfellow | 2016 | pdf | 22.5 MB |
| 2 | ... | ... | ... | ... | ... |

If results span multiple languages or editions, group them by language or category with sub-headings for clarity.

Ask: "Which book would you like to download? (number)"

3. Download

# Z-Library download (needs id + hash from search results)
python3 ${SKILL_PATH}/scripts/book.py download --source zlib --id 12345 --hash abc123def -o ~/Downloads/

# Anna's Archive download (needs MD5 hash from search results)
python3 ${SKILL_PATH}/scripts/book.py download --source annas --hash a1b2c3d4e5 --filename "deep_learning.pdf" -o ~/Downloads/

Output:

{
  "source": "zlib",
  "status": "ok",
  "path": "~/Downloads/Deep Learning (Ian Goodfellow).pdf",
  "size": 23592960
}

4. Report to User

After download, present a structured completion report:

[Book Download] Complete!
Book: [title] by [author]
Source: [zlib/annas]
Path: [file path]
Size: [file size]

If using Z-Library, also mention any remaining daily download quota.

Other Commands

Book Info (Z-Library only)

python3 ${SKILL_PATH}/scripts/book.py info --source zlib --id 12345 --hash abc123def

Returns full metadata: description, ISBN, pages, table of contents, etc.

Check Config

python3 ${SKILL_PATH}/scripts/book.py config show

Check Backend Status

python3 ${SKILL_PATH}/scripts/book.py setup

Error Handling

Degradation

Tips

• Z-Library has a daily download limit (usually 10/day for free accounts). Use info to check a book before downloading to avoid wasting quota.
• Anna's Archive requires an API key for both search and download (obtained via donation).
• For Chinese books, use --lang chinese with Z-Library for best results.
• If Z-Library is unreachable, automatically fall back to Anna's Archive with --source auto.
• When searching for a specific author in multiple languages, run parallel searches (e.g. English name + Chinese name) and merge results into one table.