articlepub 0.1.1

Turn article URLs into Kindle-friendly EPUBs and optionally upload them to Calibre-Web.

ArticlePub

Turn a long article or blog post into a clean, Kindle-friendly EPUB.

ArticlePub is for the moment when you find something worth reading, but you want it in your reading queue instead of another browser tab. Give it a URL, get an EPUB, and optionally send that EPUB straight to Calibre-Web.

Quick Start

If you have uv, you can run ArticlePub without installing it permanently:

uvx articlepub add "https://example.com/article" --provider none

That creates an EPUB in articlepub/.

Want AI cleanup and better article structure? Set your Anthropic key and leave the provider at its default:

export ANTHROPIC_API_KEY="..."
uvx articlepub add "https://example.com/article"

Send To Calibre-Web

If your Calibre-Web server allows anonymous uploads:

uvx articlepub add "https://example.com/article" \
  --provider none \
  --calibre-url "https://calibre.example.com/"

If login is required:

uvx articlepub add "https://example.com/article" \
  --calibre-url "https://calibre.example.com/" \
  --calibre-username "articlepub" \
  --calibre-password "your-password"

Add the uploaded book to a shelf:

uvx articlepub add "https://example.com/article" \
  --calibre-url "https://calibre.example.com/" \
  --calibre-shelf "Quick Read"

Shelf names can contain spaces. Repeat --calibre-shelf to add the book to more than one shelf.

Already have an EPUB? Upload it directly:

uvx articlepub upload \
  --calibre-url "https://calibre.example.com/" \
  --calibre-shelf "Quick Read" \
  articlepub/article.epub

What You Get

ArticlePub prints the EPUB path to stdout, so it is easy to script:

articlepub/example-article.epub

When Calibre-Web upload is enabled, it also prints the Calibre-Web book URL when available:

articlepub/example-article.epub
https://calibre.example.com/book/35

Status messages go to stderr and tell the story of the run:

OK    Saved articlepub/example-article.epub  :-)
OK    Book uploaded  :-)
INFO  Book: https://calibre.example.com/book/35
OK    Added to shelf: Quick Read  :-)
OK    Book uploaded successfully  :-)

Common Recipes

Save to a different folder:

uvx articlepub add "https://example.com/article" --provider none --out ~/Documents/epubs

Override the EPUB title:

uvx articlepub add "https://example.com/article" --provider none --title "Weekend Reading"

Use Claude to fetch the page directly when local extraction fails. This requires ANTHROPIC_API_KEY or --api-key:

uvx articlepub add "https://example.com/article" --fetch-mode llm

Check your setup before a long run:

uvx articlepub doctor "https://example.com/article" --provider none

See detailed timing and upload diagnostics:

uvx articlepub add "https://example.com/article" --provider none --log-level debug

Keep raw debug artifacts for one run:

uvx articlepub add "https://example.com/article" --provider none --store-metadata

Raw artifacts are written under OUT/.raw. Without --store-metadata, stale .raw data is removed.

Fetch Modes

ArticlePub starts with --fetch-mode auto.

• auto: try local extraction first, then fall back to LLM fetch when needed.
• local: fetch and extract locally, then optionally ask the provider to clean the HTML.
• llm: ask the LLM provider to fetch the URL directly.

If you do not want to use an LLM, add --provider none.

Useful Options

Option	What it does
--out articlepub	Choose where EPUB files are written.
--provider none	Build without an LLM or API key.
--api-key ...	Pass an Anthropic key directly instead of using ANTHROPIC_API_KEY.
--title "..."	Override the EPUB title.
--log-level debug	Show detailed timing and Calibre-Web steps.
--doctor	Validate an add command without building the EPUB.
--calibre-url ...	Upload the result to Calibre-Web.
--calibre-username ... and --calibre-password ...	Log in before uploading.
--calibre-shelf "Quick Read"	Add the uploaded book to a shelf.

Run uvx articlepub --help or uvx articlepub add --help for the full CLI reference.

Local Development

From a checkout of this repository:

PYTHONPATH=src python -m articlepub add "file://$PWD/tests/fixtures/blog.html" \
  --provider none \
  --fetch-mode local \
  --out /private/tmp/articlepub-check \
  --log-level debug

Run the test suite:

PYTHONPATH=src python -m unittest discover -s tests

Release

Releases are tag-driven. The release workflow runs when a vX.Y.Z tag is pushed.

Before tagging, update the version in both places:

• pyproject.toml
• src/articlepub/__init__.py

Then commit, tag, and push:

git tag v0.1.1
git push origin main
git push origin v0.1.1

The GitHub Action will run tests, build the wheel and source distribution, publish to PyPI using secrets.ARTICLEPUB_PYPI_UPLOAD_TOKEN, and create a GitHub Release with generated release notes.