kaizoku-client 0.1.0

Unofficial CLI and Python client for the Kaizoku.NET API

kaizoku-client

Unofficial CLI and Python client for the Kaizoku.NET API.

This project is not affiliated with, endorsed by, or maintained by the Kaizoku.NET project.

Naming

• PyPI package: kaizoku-client
• Import package: kaizoku
• CLI command: kaizoku

Usage

Prerequisite: a running Kaizoku.NET server with its API reachable from your machine. The default API base URL is http://127.0.0.1:9833.

Run without installing permanently:

uvx --from kaizoku-client kaizoku --help

Install as a persistent CLI tool:

uv tool install kaizoku-client
kaizoku --help

Other install options:

pipx install kaizoku-client
pip install kaizoku-client

Override the API endpoint with --url or KAIZOKU_URL.

KAIZOKU_URL=http://127.0.0.1:9833 kaizoku metrics
kaizoku --url http://127.0.0.1:9833 providers --table
kaizoku --version

CLI Examples

kaizoku --help
kaizoku metrics
kaizoku providers --table
kaizoku search-sources --table
kaizoku search "Absolute Regression" --languages en --table
kaizoku library --table
kaizoku downloads --status waiting --table

Destructive commands are guarded. retry, delete, and cleanup --yes mutate the Kaizoku.NET server download queue; this CLI does not directly delete local files.

kaizoku delete "<download-id>" --yes
kaizoku cleanup --status completed
kaizoku cleanup --status completed --yes

cleanup is a dry run unless --yes is passed. Cleaning up running downloads requires --force-running.

Python Client

from kaizoku import KaizokuClient

client = KaizokuClient()
print(client.metrics())

Pass a custom base URL explicitly:

from kaizoku import KaizokuClient

client = KaizokuClient("http://127.0.0.1:9833")

Development

uv run kaizoku --help
uv run --group dev ruff check .
uv run --group dev ruff format --check .
uv run --group dev mypy
uv run --group dev pytest
uv build

Release

Releases are published from GitHub Actions with trusted publishing.

Before running the release workflow, manually bump version in pyproject.toml, run uv lock, update CHANGELOG.md, and commit those changes. The release workflow publishes exactly the version already committed to pyproject.toml; it does not bump versions automatically.

The workflow fails if the version already exists as a git tag, GitHub Release, TestPyPI release, or PyPI release.

Configure these GitHub environments before the first release:

• testpypi
• pypi

Configure trusted publishers for .github/workflows/release.yml on both TestPyPI and PyPI. The release workflow publishes to TestPyPI first, verifies an install with uvx, then publishes the same artifacts to PyPI.