kpub

kpub

• kpub
  • Features
  • Install
  • Quick Start
    • 1. Setup
    • 2. Run
    • 3. Update
    • 4. Manage Chats
    • 5. Stop and Reload
  • CLI Reference
    • Flags
  • How It Works
  • Requirements
  • License

A Telegram chat monitor and ebook pipeline — watches your Telegram chats for ebook files, converts them to Kobo-compatible KEPUB format, and uploads them to Dropbox.

Disclaimer: This tool is intended for use with legally obtained ebooks only. Please respect copyright laws and the rights of authors and publishers. The maintainers of this project are not responsible for how it is used.

Contributing: This repository is not open for contributions. You are welcome to fork it and do whatever you want with it under the terms of the MIT License.

If you find this useful:

Install

Homebrew (macOS / Linux)

brew install spacesedan/tap/kpub

Debian / Ubuntu

Download the .deb from the releases page, then:

sudo dpkg -i kpub_*.deb

Fedora / RHEL

Download the .rpm from the releases page, then:

sudo rpm -i kpub_*.rpm

Windows

Download the .zip from the releases page, extract it, and add kpub.exe to your PATH. Requires Docker Desktop.

Download binary

Download the latest archive for your platform from the releases page.

Build from source

go install github.com/spacesedan/kpub/cmd/kpub@latest

Features

• Chat monitoring — monitor any Telegram bot, group, or channel by handle (e.g. @ebook-bot)
• Single user session — authenticates once as your Telegram account, no bot tokens needed
• Automatic conversion — converts .epub, .mobi, .azw3 to .kepub.epub using Calibre
• Dropbox integration — uploads converted files directly to your Kobo's sync folder
• Hot reload — add or remove monitored chats by editing the config file, no restart needed
• Per-chat format filtering — restrict accepted file types per chat
• Per-chat upload paths — route files from different chats to different folders
• Graceful shutdown — in-flight file processing completes before exit
• Interactive TUI — setup wizard, run, and update commands with Bubbletea-powered terminal UI

Quick Start

1. Setup

The interactive setup wizard handles everything — Telegram credentials, Dropbox OAuth, and chat configuration — in a single command:

kpub setup

This walks you through 5 steps:

1. Telegram credentials — enter your app_id and app_hash from my.telegram.org/apps
2. Dropbox app credentials — enter your app_key and app_secret from the Dropbox App Console
3. Dropbox authorization — the wizard opens your browser to authorize the app, then you paste the code back
4. Chat configuration — add one or more chat handles to monitor (e.g. @ebook-bot)
5. Review and save — confirm and write ~/.config/kpub/config.yaml + ~/.config/kpub/dropbox.json

You can type back or press Esc at any step to return to the previous step. Press Ctrl+C to cancel.

To write files to a custom directory:

kpub setup --data-dir /path/to/dir

See docs/telegram-setup.md and docs/dropbox-setup.md for more details on obtaining credentials. See docs/config-reference.md for all config options.

2. Run

Pull the image and start the container in one step:

kpub run

This will:

1. Remove any existing kpub container
2. Pull the latest kpub image from GHCR
3. Start the container with logs streaming to your terminal

On first run, you'll be prompted for your Telegram phone number and a verification code. After that, the session is saved and subsequent runs skip authentication.

To run in the background:

kpub run --detach

To use a custom data directory:

kpub run --data-dir /path/to/dir

3. Update

Pull the latest kpub image:

kpub update

To also restart the container after pulling:

kpub update --restart

4. Manage Chats

Add, list, or remove monitored chats without re-running the full setup wizard:

kpub chat list                  # show all monitored chats
kpub chat add                   # interactive prompt for a chat handle
kpub chat remove @ebook-bot     # remove a chat by handle (with confirmation)

These commands read and update the existing config.yaml — Telegram credentials, Dropbox settings, and other chats are left untouched.

The server automatically picks up config changes, so there's no need to restart after adding or removing chats.

5. Stop and Reload

Stop the running container gracefully:

kpub stop

Restart the container to pick up other config changes:

kpub reload
kpub reload --data-dir /path/to/dir

CLI Reference

kpub                # Start the server (default behavior)
kpub setup          # Interactive setup wizard
kpub run            # Pull image + start container
kpub stop           # Gracefully stop the running container
kpub reload         # Restart container to pick up config changes
kpub update         # Pull latest kpub image
kpub chat list      # List monitored chats
kpub chat add       # Add a new chat (interactive)
kpub chat remove    # Remove a chat by handle

Flags

How It Works

kpub is a single Go binary that runs inside a lightweight Docker image (ghcr.io/spacesedan/kpub). The image is based on Ubuntu 24.04 with only Calibre's CLI tools installed — no desktop environment, no GUI. This gives access to ebook-convert for format conversion in a ~500MB image.

kpub run pulls the pre-built image and starts the container with your ~/.config/kpub directory bind-mounted as /data.

1. The server connects to Telegram as your user account (single MTProto session)
2. It monitors configured chats for ebook files — including files you send yourself
3. When a document appears, the server downloads it via MTProto
4. The file is converted to .kepub.epub using Calibre's ebook-convert
5. The converted file is uploaded to Dropbox (syncs to your Kobo via the Dropbox app)
6. Status notifications are sent to your Saved Messages

Requirements

• Docker
• Telegram API credentials (app_id + app_hash) from my.telegram.org/apps
• Dropbox app credentials + OAuth tokens

License

This project is licensed under the MIT License.