Metadata-Version: 2.4
Name: ktoolbox
Version: 1.1.0b1
Summary: An asynchronous CLI and typed Python client for downloading public Pawchive posts
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: pawchive,cli-app,downloader,asyncio,pydantic,os-independent
Author: Ljzd-PRO
Author-email: me@ljzd.link
Requires-Python: >=3.10,<3.15
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Terminals
Provides-Extra: urwid
Provides-Extra: uvloop
Provides-Extra: webui
Provides-Extra: winloop
Requires-Dist: aiofiles (>=23.2.1,<24.0.0)
Requires-Dist: aiosqlite (>=0.20,<1.0) ; extra == "webui"
Requires-Dist: argon2-cffi (>=23.1,<26.0) ; extra == "webui"
Requires-Dist: croniter (>=6.0,<7.0)
Requires-Dist: cryptography (>=45.0.1,<49.0) ; extra == "webui"
Requires-Dist: cyclopts (>=4.21.1,<5.0.0)
Requires-Dist: docstring-parser (>=0.16,<1.0) ; extra == "webui"
Requires-Dist: docutils (>=0.21,<0.23) ; extra == "webui"
Requires-Dist: fastapi (>=0.115,<1.0) ; extra == "webui"
Requires-Dist: fastmcp (>=3.4,<4) ; extra == "webui"
Requires-Dist: filelock (>=3.18,<4.0) ; extra == "webui"
Requires-Dist: httpx[socks] (>=0.24.1,<0.29.0)
Requires-Dist: loguru (>=0.7.2,<0.8.0)
Requires-Dist: pathvalidate (>=3.2.0,<4.0.0)
Requires-Dist: pillow (>=10.2,<12) ; extra == "webui"
Requires-Dist: pydantic (>=2.4.2,<3.0.0)
Requires-Dist: pydantic-settings (>=2.0.3,<3.0.0)
Requires-Dist: python-dotenv (>=1.2,<2.0)
Requires-Dist: pyyaml (>=6,<7) ; extra == "webui"
Requires-Dist: rich (>=14.1.0,<15.0.0)
Requires-Dist: settings-doc (>=4.3.1,<5.0.0)
Requires-Dist: tenacity (>=8.2.3,<10.0.0)
Requires-Dist: tomlkit (>=0.13.3,<1.0.0)
Requires-Dist: tzdata (>=2025.2)
Requires-Dist: tzlocal (>=5.3,<6.0)
Requires-Dist: urwid (>=2.6.16,<3.0.0) ; (sys_platform != "win32") and (extra == "urwid")
Requires-Dist: urwid[curses] (>=2.6.16,<3.0.0) ; (sys_platform == "win32") and (extra == "urwid")
Requires-Dist: uvicorn (>=0.34,<1.0) ; extra == "webui"
Requires-Dist: uvloop (>=0.22.1,<0.23) ; (sys_platform != "win32") and (extra == "uvloop")
Requires-Dist: winloop (>=0.6.3,<0.7) ; (sys_platform == "win32") and (extra == "winloop")
Project-URL: Bug Tracker, https://github.com/Ljzd-PRO/KToolBox/issues
Project-URL: Documentation, https://ktoolbox.readthedocs.io/
Project-URL: Homepage, https://ktoolbox.readthedocs.io/
Project-URL: Repository, https://github.com/Ljzd-PRO/KToolBox
Description-Content-Type: text/markdown

<div align="center">

# KToolBox

An easy-to-use WebUI, CLI, and Python client for downloading public works from [Pawchive](https://pawchive.pw/).

[![PyPI](https://img.shields.io/pypi/v/ktoolbox?logo=python)](https://pypi.org/project/ktoolbox/)
[![Python](https://img.shields.io/badge/Python-3.10--3.14-blue)](https://www.python.org/)
[![License](https://img.shields.io/github/license/Ljzd-PRO/KToolBox)](LICENSE)
[![Documentation](https://readthedocs.org/projects/ktoolbox/badge/?version=latest)](https://ktoolbox.readthedocs.io/latest/)

[English](README.md) | [简体中文](README_zh-CN.md) | [繁體中文](README_zh-Hant.md) | [Русский](README_ru.md) | [日本語](README_ja.md) | [한국어](README_ko.md) | [Français](README_fr.md)

</div>

> [!WARNING]
> KToolBox v1 is a new major version and has not yet received enough real-world validation. Some features may still fail. Please report anything unexpected.
>
> Kemono is no longer available, so KToolBox now uses the Pawchive mirror by default.

## Start with the WebUI

The WebUI is the recommended way to use KToolBox. It covers downloads, creator synchronization, automatic schedules, naming, filters, progress, and project configuration without requiring you to edit commands or configuration files first.

1. Install KToolBox with the WebUI:

    ```bash
    pipx install "ktoolbox[webui]"
    ```

2. Create a project directory and start it:

    ```bash
    mkdir ktoolbox-project
    cd ktoolbox-project
    ktoolbox webui .
    ```

3. The browser opens automatically. Sign in with the username and random password printed in the terminal.
4. Add creators on **Creators**, then create a synchronization or download task on **Tasks**.

KToolBox creates `ktoolbox.toml` when it is missing and downloads to the project's `downloads` directory by default.

![KToolBox WebUI overview](docs/assets/webui/40-overview-showcase-desktop-light.png)

Read the short [WebUI guide](https://ktoolbox.readthedocs.io/latest/webui/) for the next steps, or open the [documentation home](https://ktoolbox.readthedocs.io/latest/) to choose a specific workflow.

## What the WebUI includes

- Single-work downloads and concurrent synchronization of many creators.
- A reusable creator roster, filters, naming templates, and automatic synchronization plans.
- Persistent task history, live progress, aggregate speed, retries, pause, stop, rerun, and safe cleanup.
- Project-level settings with readable descriptions and filesystem pickers where appropriate.
- Seven interface languages, responsive layouts, light and dark themes, and optional NSFW media previews.
- A built-in MCP service for Codex, Claude, Cursor, VS Code, and compatible clients.

## Optional setup

The generated login is convenient for a first run. For a stable password, generate a hash and add it to the project's `.env`:

```bash
ktoolbox webui hash-password
```

```dotenv
KTOOLBOX_WEBUI__USERNAME=owner
KTOOLBOX_WEBUI__PASSWORD_HASH='$argon2id$...'
```

For local-only access, start with `--host 127.0.0.1`. The built-in server uses HTTP, so use a trusted network or an HTTPS reverse proxy for remote access.

## Advanced use

The command line remains available for scripts and terminal workflows:

```bash
ktoolbox download https://pawchive.pw/fanbox/user/6570768/post/1836570
ktoolbox sync fanbox:123 patreon:456 --length 10
```

See the [CLI guide](https://ktoolbox.readthedocs.io/latest/commands/guide/) for commands, the [MCP guide](https://ktoolbox.readthedocs.io/latest/mcp/) for AI clients, and the [Python API guide](https://ktoolbox.readthedocs.io/latest/api/) for integrations.

## Upgrading from v0

Back up `.env`, `prod.env`, and existing downloads before upgrading. WebUI detects legacy naming settings and guides you through configuration and directory conversion. Read the [v1 migration guide](https://ktoolbox.readthedocs.io/latest/migration-v1/) before changing an existing project; see [troubleshooting](https://ktoolbox.readthedocs.io/latest/faq/) if a migration or task fails.

## Development

```bash
poetry install --with test,docs,dev
poetry run pytest --cov
poetry run mkdocs build --strict
cd webui && npm ci && npm run test && npm run build
```

Default tests are offline and must not contact Pawchive or any other remote service.

## License

KToolBox is licensed under the [BSD 3-Clause License](LICENSE).

