paperserve

Saves articles from URLs as Markdown files. Syncs to a git repo so they're readable anywhere.

paperserve add https://example.com/some-article

That's it. The article is fetched, stripped to readable content, and saved as a .md file with frontmatter. If you have a git remote configured, it pushes automatically.

Install

Install via cargo :

cargo install paperserve

Build it from the source :

git clone https://github.com/simplysabir/paperserve
cd paperserve
cargo build --release
cp target/release/paperserve /usr/local/bin/

Requires Rust and git.

Setup

Run once:

paperserve setup

It will ask for:

• Where to store files (default: ~/Papers)
• Whether to auto-sync to git on every add
• If yes: your git remote URL (e.g. git@github.com:you/papers.git)

The repo must already exist on GitHub. paperserve setup runs git init and git remote add locally — you don't need to clone it first.

Config is saved to ~/.config/paperserve/config.toml OR inside Application Support for macOS.

Commands

paperserve add <url>          # fetch article, save as Markdown
paperserve upload <file>      # copy any file into the archive
paperserve upload <file> --name custom-name.pdf
paperserve list               # show saved articles
paperserve sync               # commit and push manually
paperserve setup              # reconfigure at any time

File layout

~/Papers/
  README.md              # auto-generated index, updated on every add
  articles/
    2026-03-01-article-title-a1b2c3d4.md
  uploads/
    cpumemory.pdf

Each article file:

---
title: "Article Title"
url: https://example.com/article
author: "Author Name"
site: "Example"
saved: 2026-03-01
words: 4200
---

# Article Title

...content...

Git sync

With auto-sync on, every add and upload commits and pushes immediately.

With auto-sync off, changes are saved locally and pushed when you run paperserve sync.

GitHub renders the README.md index as a table with links to each article. Private repos work fine.

Notes

• Authentication uses your system git config (SSH keys, credential manager). paperserve doesn't handle credentials.
• Files over 50MB get a warning — GitHub's hard limit is 100MB per file.
• If an article extracts poorly, the raw cleaned HTML is converted to Markdown as a best-effort. No article is silently dropped.