# KToolBox puts a WebUI, a CLI and an MCP server in front of the Pawchive archive

> KToolBox is a BSD licensed Python tool for downloading public works from the Pawchive mirror, with a FastAPI web interface, a command line client, an MCP service for AI coding agents and a typed Python API. It suits someone who wants scheduled creator synchronisation with naming templates and filters, and version 1 is explicitly flagged as a new major release without enough real world validation yet.

**Ljzd-PRO/KToolBox** — Downloader for Pawchive (Kemono) with High Customizability | 高度可自定义性的 Pawchive (Kemono) 下载器

- Repository: https://github.com/Ljzd-PRO/KToolBox
- Website: https://ktoolbox.readthedocs.io
- Stars: 590 · Forks: 28
- Language: TypeScript
- License: BSD-3-Clause
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/ljzd-pro-ktoolbox

## One tool, three front ends, and a mirror that moved

KToolBox is described as an easy-to-use WebUI, CLI and Python client for downloading public works from Pawchive, and the project description calls it a downloader for Pawchive, the Kemono service, with high customizability.

The first thing to know is a change of source. The documentation carries a warning: Kemono is no longer available, so KToolBox now uses the Pawchive mirror by default. That is not a small detail, because it is the kind of change that breaks a downloader. A mirror can reorganise its URLs, change its response shape or disappear, and a tool built against one host's paths has to follow.

The second thing is the shape of the tool. There are three front ends over one core. The WebUI is a browser interface, the CLI is for scripts and terminal workflows, and there is a typed Python API for integrations. The package metadata describes it as an asynchronous CLI and typed Python client for downloading public Pawchive posts, with a console script entry point of ktoolbox = ktoolbox.__main__:main.

The WebUI is the recommended path for new users, and the documentation is explicit about why. It covers downloads, creator synchronisation, automatic schedules, naming, filters, progress and project configuration without requiring you to edit commands or configuration files first.

## The WebUI workflow is four steps from a clean install

The getting started path is short and worth following exactly.

The install pulls in the web interface extra.

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

Then you make a project directory and start it there.

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

The browser opens automatically, and you sign in with the username and random password printed in the terminal. You add creators on the Creators page, then create a synchronisation or download task on the Tasks page.

Two details make this feel like a designed tool rather than a script. KToolBox creates a ktoolbox.toml when it is missing, so a first run does not fail on a missing config file, and downloads go to the project's downloads directory by default, so everything for one collection of creators lives in one place.

The WebUI feature list is where the actual scope sits: single-work downloads and concurrent synchronisation of many creators, a reusable creator roster with filters and naming templates, automatic synchronisation plans, persistent task history with live progress, aggregate speed, retries, pause, stop, rerun and safe cleanup, and project-level settings with readable descriptions and filesystem pickers. There are seven interface languages, responsive layouts, light and dark themes, and optional NSFW media previews.

And there is a built-in MCP service, which the documentation lists for Codex, Claude, Cursor, VS Code and compatible clients. That is the part that makes this different from a plain downloader: the same engine can be driven by an AI coding agent.

## The generated password is for a first run, not for a server

The authentication story is short and has one important warning in it.

The generated login is convenient for a first run, and for a stable password the documentation tells you to generate a hash and add it to the project's .env file.

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

The two settings you write are the username and the hash.

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

The double separator in the variable names is the nested settings convention, matching the pydantic-settings dependency in the package metadata, so the WebUI section is a namespace rather than a flat set of keys.

For network exposure the guidance is blunt. For local-only access, start with --host 127.0.0.1, and note that the built-in server uses HTTP, so for remote access you should use a trusted network or an HTTPS reverse proxy.

That is a sensible default posture for a tool that downloads and serves files. The interface is not designed to be exposed directly, and the argon2 hash is stored in a file in the project directory, which is where a real deployment's secrets management decisions have to come in.

## The CLI and the Python API for scripted work

The command line remains available for scripts and terminal workflows, and the two examples in the documentation show the two shapes of use.

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

The first is a single work addressed by URL, with the site, the creator id and the post id in the path. The second is a synchronisation across two sources at once, with the source and creator given as a colon separated pair, and --length 10 bounding how much to pull.

The colon syntax is worth noting because it is how the roster is expressed throughout the tool. A creator is a site plus an id, and the WebUI roster, the CLI arguments and the naming templates all speak the same vocabulary.

For integrations there is a Python API guide, and the metadata describes the package as a typed Python client, with pydantic and pydantic-settings among the dependencies, so the data model is validated rather than loose dictionaries. The rest of the dependency list tells you what the tool is built from: httpx with socks support for the transport, tenacity for retries, aiofiles for async file writes, pathvalidate for sanitising names taken from the source, croniter and tzdata and tzlocal for the scheduling side, tomlkit for rewriting the project config, cyclopts for the command line, loguru for logging and rich for terminal output. urllib and urllib3 are absent, which is consistent with an httpx based client.

## Schedules, filters and naming templates are the real feature

The WebUI list mentions automatic synchronisation plans, filters and naming templates, and the dependencies show how the scheduling works. croniter and tzlocal are both present, with tzdata for the timezone database, which means a synchronisation plan is expressed as a cron expression evaluated in a local timezone, not as a fixed interval in UTC.

That matters for a tool that runs unattended on a schedule, because a creator's post times and your own working hours are both local times, and an off-by-one-hour schedule in the wrong timezone is the classic way to end up downloading at 3am.

The naming side is where pathvalidate earns its place. A download tool that names files after what it found at the source is writing arbitrary text into a filesystem, and the sanitising library is there to keep a hostile or merely awkward title from turning into a path traversal or an unopenable filename. The documentation also mentions a custom_templates/ directory at the repository root and a k_generator/ directory, which is consistent with a templating system for how a downloaded post becomes a set of files and folders.

The creator roster, the filters, the templates and the plans together are the reason to use this rather than a browser and a download manager. Each downloaded work goes to a predictable place, on a predictable schedule, named by a rule you chose.

## Migrating from v0 changes where files land

Version 1 is a breaking release, and the documentation treats the migration as something to plan rather than something to discover.

The warning at the top of the README is the key sentence: KToolBox v1 is a new major version and has not yet received enough real-world validation, so some features may still fail and you are asked to report anything unexpected. That is an unusually honest statement to find at the top of a project page, and it is the first thing to weigh.

The migration guidance is specific. Back up .env, prod.env and existing downloads before upgrading. The WebUI detects legacy naming settings and guides you through configuration and directory conversion, and there is a separate v1 migration guide plus a troubleshooting page for when a migration or a task fails.

The phrase to hold onto is directory conversion. In v0 the naming and directory layout were different, and v1 rewrites them. A tool whose value is that everything lands in a predictable place is exactly the tool where a silent layout change is most disruptive, which is why the instruction to back up the downloads directory and the env files comes before anything else.

The release history reflects the reset. The listed versions are v1.1.0-beta.1 on 2026-09-10, v1.0.0 on 2026-08-23 and v0.24.0 on 2025-12-28, and the project metadata gives the current version as v1.1.0-beta.1 with a Development Status of 4, Beta. The last push was on 2026-09-10 and the repository is not archived.

## The project ships more than the tool

The repository tree shows a project with several ambitions beyond the downloader itself.

There is a shortcuts/ directory, and the project topics list ios-shortcut and ios-shortcuts among fanbox, fantia, patreon, coomer, coomer-su and coomer-party, so the tool is meant to be triggered from a phone as well as from a desktop. There is a webui/ directory with its own npm project, alongside a ktoolbox/ Python package, tests/, docs/, scripts/, static/ and custom_templates/.

The MCP service is worth singling out. The WebUI list names a built-in MCP service for Codex, Claude, Cursor, VS Code and compatible clients, and there is a separate MCP guide for AI clients. The webui extra pulls in FastAPI, aiosqlite, argon2-cffi and cryptography, and docstring-parser and docutils, which is consistent with a service that exposes the tool's own commands to an agent by describing them.

There is also a ktoolbox.spec file, which is a PyInstaller specification, so the tool can be frozen into a single executable, and the optional dependencies include uvloop and winloop for the event loop on Unix and Windows respectively, and urwid for a terminal user interface on both platforms.

The licence is BSD 3-Clause, with a LICENSE file at the root, and the project publishes a Code of Conduct, a SECURITY.md, a CHANGELOG.md and RELEASE_NOTES.md. The development workflow is Poetry based, with poetry install --with test,docs,dev and a pytest run with coverage, and the web UI has its own npm test and build steps. The documentation states that the default tests are offline and must not contact Pawchive or any other remote service, which is the right constraint for a test suite that would otherwise hit a third party mirror on every run.

## Conclusion

KToolBox fits a user who wants a scheduled, templated download workflow rather than a one-off script, and who would rather drive it from a browser or from an AI coding agent than from a shell. It does not fit someone who wants a stable tool, because the project states plainly that version 1 is a new major version without enough real world validation and that some features may still fail, and it does not fit a server deployment without a TLS terminator, because the built-in web server speaks plain HTTP. Before adopting it, read the v1 migration guide if you have an existing v0 project, because the WebUI detects legacy naming settings and converts directories, and pin a password hash in the project .env rather than relying on the generated one, since the generated credentials are printed to the terminal and are meant for a first run.

## FAQ

### How do I install KToolBox with the web interface?

Run pipx install "ktoolbox[webui]", then create a project directory, change into it and run ktoolbox webui . The browser opens automatically and you sign in with the username and random password printed in the terminal.

### Why does KToolBox use Pawchive instead of Kemono?

The project documentation states that Kemono is no longer available, so KToolBox now uses the Pawchive mirror by default. Downloads are addressed with Pawchive URLs, such as a fanbox user and post path.

### How do I set a stable password for the KToolBox web interface?

Run ktoolbox webui hash-password and put the username and the resulting argon2 hash in the project .env file as KTOOLBOX_WEBUI__USERNAME and KTOOLBOX_WEBUI__PASSWORD_HASH. The built-in server uses HTTP, so for remote access use a trusted network or an HTTPS reverse proxy.

### What happens when I upgrade a v0 project to v1?

The documentation asks you to back up .env, prod.env and existing downloads first, because the WebUI detects legacy naming settings and guides you through configuration and directory conversion. There is a dedicated v1 migration guide and a troubleshooting page for failed migrations or tasks.

## Sources

- [License: BSD-3-Clause](https://github.com/Ljzd-PRO/KToolBox/blob/master/LICENSE)
- [Ljzd-PRO/KToolBox on GitHub](https://github.com/Ljzd-PRO/KToolBox)
- [Project website](https://ktoolbox.readthedocs.io)
- [README](https://github.com/Ljzd-PRO/KToolBox/blob/master/README.md)
- [Releases](https://github.com/Ljzd-PRO/KToolBox/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ljzd-pro-ktoolbox