# ystyle/kaf-cli: turning plain text files into EPUB, AZW3 and MOBI books

> kaf-cli is a Go command line tool that converts Chinese and other text novels into EPUB, AZW3 and MOBI files, with automatic chapter and volume detection, custom CSS, embedded fonts and a drag and drop mode. It suits readers who keep their books as plain text.

**ystyle/kaf-cli** — 把txt文本转成epub和mobi电子书的命令行工具(原TmdTextEpub)

- Repository: https://github.com/ystyle/kaf-cli
- Website: https://ystyle.top/2019/12/31/txt-converto-epub-and-mobi/
- Stars: 1,040 · Forks: 74
- Language: Go
- License: NOASSERTION
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/ystyle-kaf-cli

## What kaf-cli converts and who the tool is written for

kaf-cli takes a plain text file and produces an ebook. The project describes it as a command line tool that converts txt text into EPUB, and the feature list ends with automatic conversion to mobi, so the real output set is EPUB, AZW3 and MOBI, chosen by the `-format` flag whose accepted values are all, epub, mobi and azw3.

The tool is written in Go, with the module path `github.com/ystyle/kaf-cli` and a Go 1.23.1 requirement. The dependency list explains the shape of the output: `github.com/go-shiori/go-epub` for EPUB writing, `github.com/766b/mobi` and `github.com/leotaku/mobi` for the MOBI path, `golang.org/x/text` for encoding handling, and `golang.org/x/net`. There is a `replace` directive pointing the go-epub dependency at a fork under the same author's namespace, so the EPUB writer is a modified version rather than the upstream library.

The audience is readers with text libraries. Much of the design points at Chinese web novels: the feature list includes automatic detection of garbled characters from wrong encodings, a rule that pulls the book name and author out of a filename like `《希灵帝国》（校对版全本）作者：远瞳.txt`, and a default volume pattern built on Chinese numeral characters. The default language for the output is `en`, and the accepted values include zh, ja, ru and others, which is a hint that the tool is used on more than Chinese source text.

The original name of the project was TmdTextEpub, which appears in the repository description, so the tool has been renamed at least once.

## Drag and drop mode, the three output formats and the kindlegen requirement

The default usage is a drag and drop operation. You extract the archive, drag the novel file onto `kaf-cli.exe`, and when the conversion finishes the same directory contains the epub, azw3 and mobi files. The project calls this the fool-proof mode, and it is the mode most people will use, since the tool exists to remove the need to type flags.

The cover is handled without configuration in that mode. If a file named `cover.png` sits in the same directory as the novel, it is picked up automatically, and both jpg and png are supported there. Specifying a different file, or using jpg through the command line, requires the command line mode instead.

The mobi output has a hard dependency. MOBI generation requires kindlegen, and the Windows and macOS builds already bundle it. When kindlegen is detected the conversion to mobi happens on its own; when it is missing, the mobi file simply is not produced. The project also documents doing the conversion by hand, by downloading kindlegen from a GitHub mirror because the official site no longer offers it, dropping the epub onto `kindlegen.exe`, or running it directly:

```shell
cd d:/
d:/kindlegen.exe d:/全职法师.epub
```

The result lands next to the epub and is copied into a Kindle's documents directory, which is how the tool reaches e-ink readers that still expect MOBI rather than EPUB.

## Automatic chapter, volume and encoding detection, and where it breaks

The most useful behaviour in the tool is that it tries to work out the structure of a text file on its own. The feature list claims automatic recognition of the book title and the chapters, and the documentation states that all of the example patterns in the guide are detected automatically, so the custom matching rules are a fallback rather than the normal path.

The rules are regular expressions. The default volume pattern matches a volume heading of the form `第` followed by Chinese numerals and then `卷` or `部`, and it can be turned off by setting the volume rule to false. Chapters are matched by a separate `-match` expression, and the documentation explains the shorthand: a dot is any single character, `{1,8}` is a count of one to eight characters, `\d+` is digits and `\w` is letters and digits. A chapter format of `第x节` is expressed as `-match "第.{1,8}节"`, and English formats work the same way:

```shell
d:/kaf-cli.exe -filename d:/ebbok.txt -match "Section \d+"
```

There is also an exclusion pattern for invalid chapters and volumes, whose default value is a long Chinese pattern matching headings that begin with a number followed by words such as 部门, 部队 or 部属, which in practice are table-of-contents style lines rather than real chapters. A heading that produces no chapters is the symptom that the match expression needs work.

Encoding is handled separately and automatically, with the promise of solving garbled Chinese characters. Chapter headings can also be styled as bold and centered paragraphs, the volume name can be given a double line border, and the chapter number can be separated from the title onto its own line. All of these can also be overridden in a custom CSS file, so the double border is a default rather than a fixed rule.

## The command line flags that control layout and output

Everything the drag and drop mode does is reachable through flags, and the flag set is the real interface of the tool. The output file name is set with `-out` and does not need a format suffix. The book name defaults to the txt file name, and the author defaults to `YSTYLE`, so a converted book carries a placeholder author unless `-author` is given. The book language is set with `-lang`, and the accepted values are en, de, fr, it, es, zh, ja, pt, ru and nl.

Typography is where most of the flags sit. `-indent` sets the number of indent characters in a paragraph and defaults to 2, `-bottom` sets the paragraph spacing and defaults to `1em`, `-line-height` sets the line height, and `-align` sets the heading alignment, defaulting to center. The heading text itself is capped by `-max`, which limits the maximum number of characters in a heading and defaults to 35. Chapters that could not be identified get the fallback name from `-unknow-title`, which defaults to `章节正文`.

Two flags are about behaviour rather than looks. `-separate-chapter-number` splits the chapter number and title into separate lines, and `-tips` appends the tool's own tutorial to the output, which is on by default. That last flag has a platform quirk worth knowing: on darwin, mac and osx, the tutorial has to be turned off with:

```shell
kaf-cli -filename 小说.txt -tips=0
```

Several defaults can also be changed through environment variables, which is a better route than repeating flags: `KAF_CLI_ALIGN` for heading alignment, `KAF_CLI_FORMAT` for the output format and `KAF_CLI_LANG` for the language. A font can be embedded with `-font`, after which the body text of the EPUB uses that font, and the EPUB format supports embedded fonts.

## Custom CSS with five named classes

The styling system is a small, explicit CSS contract rather than a template system. A custom CSS file is passed with `--custom-css-file`, and it overrides the defaults. The file defines five class names, and they map directly onto the elements the generator emits: `h2.volume` for the volume name, `h3.title` for the chapter title, `h3.title span.chapter-number` for the chapter number, `.content` for body paragraphs, and `body` for the overall style.

The example in the documentation shows the three heading levels being restyled at once:

```css
/* 修改卷名样式 */
h2.volume {
    border-top: 5px solid red;
    border-bottom: 5px solid red;
    color: darkred;
}
```

The same file can then be applied with:

```shell
kaf-cli -filename 小说.txt --custom-css-file mystyle.css
```

The documented advanced tweaks are one-liners on the same selectors: `.content { line-height: 2; }` for line spacing, `h3.title { font-size: 1.5em; }` for heading size, `.content { text-indent: 4em; }` for indentation, and `body { margin: 2em; }` for page margins. Since the override file only needs the properties to change, a user can start from the class names alone without copying the example.

A useful detail is that the paragraph indentation is also available as a flag, `-indent`, with a default of 2, and the CSS route allows a value in `em` units instead. The two mechanisms overlap, so it is worth picking one.

## Where kaf-cli is distributed and how an assistant can drive it

The desktop builds are on the GitHub releases, with the latest release serving the computer version, a separate `android` tag for the phone version `kaf`, and a separate repository for `kaf-wifi`, the book transfer over Wi-Fi tool. Everything is also mirrored on a Baidu netdisk link, and there are two package manager routes: Arch Linux users can install `kaf-cli` and `kaf-wifi` from the AUR with `yay -S kaf-cli kaf-wifi`, including a loongarch64 build, and Windows users can use `winget install kaf-cli`.

The repository also carries an Agent Skill, so a coding assistant can perform the conversion for you. It is installed with a single command:

```shell
npx skills add ystyle/kaf-cli
```

The listed assistants are Claude Code, Cursor and OpenCode. A related project, `kaf-mcp`, ships in the same release as kaf-cli and exposes the conversion over the Model Context Protocol, with the setup described using Cherry Studio: download and unpack kaf-mcp, put its path in the command field, and add `KAF_DIR` as an environment variable pointing at the directory that holds the text novels, where the converted books are written as well.

The repository itself is a Go project with `cmd/`, `internal/`, `lib/`, `pkg/` and a `skills/` directory, plus `kaf.go` at the top level, a `kaf-cli.exe.manifest` for Windows, and a PowerShell script named `注册右键菜单.ps1` that adds a right-click context menu entry. The same document explains the manual PATH setup on Linux and mac, adding `export PATH=$HOME/application:$PATH` to `~/.bashrc` or `~/.zshrc`.

## The constraints a user has to work around

Several limits are structural rather than bugs. The mobi path needs kindlegen, and the official kindlegen download no longer exists, so the project points to a GitHub mirror of a proprietary tool that the author does not control. The Orly style cover is generated on request, with an animal index from 0 to 41 and a theme colour that accepts a number from 1 to 16 or a hex code, and the flag help states that generating it requires a network connection, so an offline user must supply a local image instead.

The chapter detection is a heuristic expressed as a regular expression, and it only works on texts that follow a predictable heading convention. A file with mixed heading styles, or one where the same marker appears inside a paragraph, will produce wrong chapter boundaries, and the only fix is the manual `-match` expression. The default exclusion pattern is likewise written for one specific language, so a text in another script may need its own.

The `-tips` default that appends a tutorial to the generated book is on by default, and it needs a platform-specific flag on darwin to be disabled, which is the kind of detail that ends up inside a user's book if it is missed.

On the project side, the last push was on 2026-07-03 and the recent releases include v1.3.16 on 2026-05-29 and v1.3.15 on 2026-04-02, plus an `mcp-v1.3.13` build. The licence is one GitHub cannot classify, with the terms in the LICENSE file, so anyone redistributing a build or folding the code into another project needs to read that file rather than assume a permissive default.

## Conclusion

Adopt kaf-cli when your source material is plain text and you want EPUB output with sensible chapter, volume and paragraph handling, and when a drag and drop workflow on Windows fits how you read. Do not adopt it for MOBI output unless you accept the kindlegen dependency, since that format is only produced when kindlegen is present, and check the custom LICENSE file before redistributing a build, because the licence is not one GitHub can classify. Before your first run, confirm the chapter and volume patterns match your file, decide whether the Orly cover is acceptable since it needs a network connection, and set the book language explicitly.

## FAQ

### What output formats does kaf-cli produce?

The `-format` flag accepts all, epub, mobi and azw3. MOBI is only produced when kindlegen is available, and the Windows and macOS builds already include it.

### How do I convert a text file with kaf-cli on the command line?

Pass the file with `-filename` and set the metadata you want, for example `kaf-cli -author 乱 -filename ~/全职法师.txt`. A bare `kaf-cli ~/全职法师.txt` runs the same simple mode as the drag and drop one.

### How do I set custom chapter detection rules in kaf-cli?

Use the `-match` flag with a regular expression, such as `-match "第.{1,8}节"` for chapters of the form 第x节 or `-match "Section \d+"` for English headings. The default patterns already detect common Chinese novel formats automatically.

### Can I restyle the generated EPUB with CSS?

Yes. Pass a CSS file with `--custom-css-file` and override the generated classes: `h2.volume`, `h3.title`, `h3.title span.chapter-number`, `.content` and `body`.

### How do I install kaf-cli?

The computer build is downloaded from the GitHub releases. Arch Linux users can install `kaf-cli` and `kaf-wifi` from the AUR with `yay -S kaf-cli kaf-wifi`, and Windows users can run `winget install kaf-cli`.

### What licence does kaf-cli use?

The project uses a custom licence that GitHub cannot classify, with the terms written in the LICENSE file in the repository.

## Sources

- [Issues](https://github.com/ystyle/kaf-cli/issues)
- [Project website](https://ystyle.top/2019/12/31/txt-converto-epub-and-mobi/)
- [README](https://github.com/ystyle/kaf-cli/blob/master/README.md)
- [Releases](https://github.com/ystyle/kaf-cli/releases)
- [ystyle/kaf-cli on GitHub](https://github.com/ystyle/kaf-cli)

---

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