zotrm 0.1.0__tar.gz

zotrm-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,58 @@
+name: Bug report
+description: Something isn't working as expected
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: Thanks for taking the time to file a bug! Please remove any secrets (like your Zotero API key) from logs.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you do, and what went wrong?
+      placeholder: I ran `zotrm pull` and ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Run `zotrm ...`
+        2. ...
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Output / logs
+      description: Paste the command output. Run with `--dry-run` if helpful. Remove your API key.
+      render: shell
+  - type: input
+    id: version
+    attributes:
+      label: zotrm version
+      description: Output of `zotrm --help` header or the installed version.
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - macOS
+        - Linux
+    validations:
+      required: true
+  - type: input
+    id: rmapi
+    attributes:
+      label: rmapi version
+      description: Output of `rmapi version` (if relevant).

zotrm-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or usage help
+    url: https://github.com/dipta007/zotRm/discussions
+    about: Ask questions and share setups in Discussions instead of opening an issue.

zotrm-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature request
+description: Suggest an idea or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+      description: Describe the use case or pain point. "I'm always frustrated when ..."
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like zotrm to do?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any workarounds or other approaches you've thought about.

zotrm-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+<!-- Thanks for contributing to zotrm! -->
+
+## What does this change?
+
+<!-- A short summary of the change and why it's needed. Link any related issue. -->
+
+Closes #
+
+## Checklist
+
+- [ ] Tests added or updated for the change
+- [ ] `uv run pytest` passes (100% coverage gate)
+- [ ] `uv run ruff check .` and `uv run ruff format --check .` are clean
+- [ ] `uv run mypy src` passes
+- [ ] Docs updated if behavior changed (README / advanced-usage / CHANGELOG)

zotrm-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check .
+
+      - name: Type check (mypy)
+        run: uv run mypy src
+
+      - name: Tests + 100% coverage gate
+        run: uv run pytest

zotrm-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+# Publishes to PyPI when a version tag (e.g. v0.1.0) is pushed.
+#
+# Uses PyPI "trusted publishing" (OIDC) — no API token needed. One-time setup on PyPI:
+#   PyPI → your project → Settings → Publishing → Add a trusted publisher
+#     Owner: dipta007 | Repo: zotRm | Workflow: release.yml | Environment: pypi
+# Then create a `pypi` environment in the repo settings.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Verify the package before publishing
+        run: |
+          uv sync --locked
+          uv run ruff check .
+          uv run ruff format --check .
+          uv run mypy src
+          uv run pytest
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

zotrm-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Build artifacts
+dist/
+build/
+
+# uv / virtualenv
+.venv/
+
+# Caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Coverage
+.coverage
+htmlcov/
+coverage.xml

zotrm-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

zotrm-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-23
+
+### Added
+
+- `push`, `pull`, `status`, and `sync` commands to move PDFs between a Zotero collection
+  and a reMarkable Paper Pro, tracking state with Zotero tags (`rm:synced`,
+  `rm:annotated`).
+- Sub-collection mirroring: Zotero sub-collections become nested folders on the tablet.
+- `zotrm config` — interactive setup wizard with a live Zotero check and an `rmapi`
+  presence check; runs automatically on first use.
+- `zotrm cron` — schedule an automatic sync (with `--remove` / `--show`).
+- `--config` and `--dry-run` global flags.
+- Full type hints (`mypy --strict`), `ruff` lint/format, and a test suite at 100%
+  coverage.
+
+[Unreleased]: https://github.com/dipta007/zotRm/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/dipta007/zotRm/releases/tag/v0.1.0

zotrm-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,55 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a
+harassment-free experience for everyone, regardless of age, body size, visible or invisible
+disability, ethnicity, sex characteristics, gender identity and expression, level of
+experience, education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse,
+inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards and will take
+appropriate and fair corrective action in response to any behavior that they deem
+inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an
+individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the
+maintainer via <https://roydipta.com>. All complaints will be reviewed and investigated
+promptly and fairly. Community leaders are obligated to respect the privacy and security of
+the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1,
+available at <https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+[homepage]: https://www.contributor-covenant.org

zotrm-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to zotrm
+
+Thanks for your interest in improving zotrm! This project uses
+[uv](https://docs.astral.sh/uv/) for everything.
+
+## Set up for development
+
+```sh
+git clone https://github.com/dipta007/zotRm
+cd zotrm
+uv sync              # creates .venv and installs deps + dev tools
+uv pip install -e .  # editable install, so `zotrm` reflects your edits
+```
+
+## Project layout
+
+```
+src/zotrm/
+  cli.py          # argparse, main(), command dispatch
+  config.py       # config loading/validation + shared helpers
+  zotero.py       # pyzotero wrapper: collection walk, tag helpers
+  remarkable.py   # rmapi subprocess wrapper
+  wizard.py       # interactive `zotrm config` setup wizard
+  cron.py         # `zotrm cron` schedule builder + crontab management
+  __main__.py     # enables `python -m zotrm`
+tests/            # pytest suite (pyzotero + rmapi + questionary are mocked)
+```
+
+## Run the checks
+
+All four must pass before a change is ready:
+
+```sh
+uv run pytest          # tests + 100% coverage gate
+uv run ruff check .    # lint
+uv run ruff format .   # format (use --check in CI)
+uv run mypy src        # type-check (strict)
+```
+
+GitHub Actions runs these same four gates on every push and pull request, across
+Python 3.11–3.13 (see [`.github/workflows/ci.yml`](.github/workflows/ci.yml)). The test
+step enforces 100% coverage, so a change that drops coverage fails CI.
+
+## Code style
+
+- **Formatting & linting:** `ruff`, line length 100. Run `ruff format` before committing.
+- **Types:** full type hints; `mypy --strict` must pass on `src`. The live `pyzotero`
+  client is typed as `Any` (it ships no stubs); helpers pin down the slices we use.
+- **Tests:** external systems are never hit. `pyzotero.Zotero`, the `rmapi`/`crontab`
+  subprocesses, and `questionary` prompts are all replaced with fakes (see
+  `tests/conftest.py`). Favor meaningful coverage over a coverage number.
+- **Keep changes surgical.** Match the surrounding style; don't refactor unrelated code.
+
+## Making a change
+
+1. Branch off `main`.
+2. Add or update tests alongside your change.
+3. Make sure all four checks above are green.
+4. Open a pull request describing what changed and why.
+
+## Releasing
+
+See [docs/advanced-usage.md](docs/advanced-usage.md#publishing-to-pypi-for-maintainers)
+for how to publish a new version to PyPI.

zotrm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shubhashis Roy Dipta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zotrm-0.1.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: zotrm
+Version: 0.1.0
+Summary: Bridge a Zotero collection to a reMarkable Paper Pro: push PDFs, pull annotations.
+Project-URL: Homepage, https://roydipta.com
+Project-URL: Repository, https://github.com/dipta007/zotRm
+Author: Shubhashis Roy Dipta
+License-Expression: MIT
+License-File: LICENSE
+Keywords: annotations,pdf,remarkable,rmapi,zotero
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: pyzotero>=1.5
+Requires-Dist: questionary>=2.0
+Description-Content-Type: text/markdown
+
+# zotrm
+
+[![CI](https://github.com/dipta007/zotRm/actions/workflows/ci.yml/badge.svg)](https://github.com/dipta007/zotRm/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/zotrm.svg)](https://pypi.org/project/zotrm/)
+[![Python](https://img.shields.io/pypi/pyversions/zotrm.svg)](https://pypi.org/project/zotrm/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/dipta007/zotRm/blob/main/LICENSE)
+
+Read your Zotero papers on a **reMarkable Paper Pro**, then get your handwritten
+notes back into Zotero — with one command.
+
+## Demo
+
+![zotrm in action: push papers, annotate on the tablet, pull them back](https://raw.githubusercontent.com/dipta007/zotRm/main/docs/demo.gif)
+
+> _Recording the GIF: see [how to record the demo](https://github.com/dipta007/zotRm/blob/main/docs/advanced-usage.md#recording-the-demo-gif)._
+
+**What it does, in plain words:**
+
+- **push** — sends the PDFs from one Zotero collection to your reMarkable tablet.
+- **pull** — brings the marked-up PDFs back and attaches them to the same Zotero papers.
+- **status** — shows which papers are waiting, on the tablet, or already done.
+- **sync** — does a pull and then a push, together.
+
+You never push or pull the same paper twice by mistake — the tool remembers what it has
+done. It is safe to run again and again.
+
+> **One honest limit (this is reMarkable's behavior, not a bug here):**
+> Your highlights and handwriting come back as part of the PDF image — "painted onto"
+> the page. They do **not** come back as clickable Zotero highlights.
+
+## Why zotrm?
+
+If you read research papers on a reMarkable, getting them on and off the tablet is fiddly:
+export each PDF, drag it into the reMarkable app, and later dig the annotated copy back
+out and re-file it in Zotero. zotrm makes that **one command in each direction**, driven by
+the collection you already curate in Zotero:
+
+- **No manual file shuffling** — it reads your Zotero collection and uploads the PDFs for you.
+- **Folders match your library** — Zotero sub-collections become nested folders on the tablet.
+- **Nothing pushed or pulled twice** — progress is tracked with Zotero tags, so it's safe to
+  re-run or schedule with `zotrm cron`.
+- **No extra database or account** — just your Zotero API key and the `rmapi` tool.
+
+It's a small, focused CLI — not a sync daemon or a cloud service.
+
+---
+
+## Before you start (what you need)
+
+1. A **Zotero** account with some PDFs in it.
+2. A **reMarkable** tablet, turned on and connected to WiFi.
+3. A **reMarkable Connect** subscription — this is what lets files move to and from the
+   tablet over the internet. Without it, push and pull may not work.
+4. A computer (Mac or Linux) where you can open a **Terminal** (a window where you type
+   commands). On a Mac, open the app called **Terminal**.
+
+You will copy and paste a few commands. That is all.
+
+---
+
+## Setup (about 10 minutes)
+
+### Step 1 — Install `uv`
+
+`uv` installs this tool for you. Paste this into the Terminal and press Enter:
+
+```sh
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Close the Terminal and open it again so the change takes effect.
+
+### Step 2 — Install `rmapi` and connect it to your tablet
+
+`rmapi` is a separate program that talks to your reMarkable:
+
+```sh
+brew install rmapi
+```
+
+(No Homebrew? See <https://github.com/ddvk/rmapi> for other ways. Use the **ddvk**
+version — the original does not work with new tablets.)
+
+Now connect it to your tablet **one time**:
+
+```sh
+rmapi
+```
+
+It shows a web address and asks for a code. Open
+<https://my.remarkable.com/device/desktop>, copy the code shown there, and paste it into
+the Terminal. Done — you won't do this again.
+
+### Step 3 — Install `zotrm`
+
+```sh
+uv tool install zotrm
+```
+
+### Step 4 — Set up your account (answer a few questions)
+
+Just run:
+
+```sh
+zotrm config
+```
+
+It asks you a few simple questions (use the arrow keys and Enter), then checks that your
+details work. To answer the two Zotero questions:
+
+- Open <https://www.zotero.org/settings/keys>.
+- Your **library ID** is the number shown as "Your userID".
+- Click **Create new private key**, allow read **and write**, and copy the key it gives
+  you.
+
+> **Tip:** In Zotero, make a collection (for example named `reMarkable`) and drag the
+> papers you want to read into it. Give that same name when the wizard asks for the
+> collection.
+
+That's it — your settings are saved automatically. (The very first time you run any
+command, this wizard starts on its own if you haven't set up yet.)
+
+### Step 5 — Use it
+
+Send your papers to the tablet:
+
+```sh
+zotrm push
+```
+
+Read and annotate them on the reMarkable. When you're done, bring them back:
+
+```sh
+zotrm pull
+```
+
+That's the whole loop. 🎉
+
+### Step 6 (optional) — Make it automatic
+
+Want it to sync by itself on a schedule? Run:
+
+```sh
+zotrm cron
+```
+
+Pick how often (every hour, daily, etc.) and it sets everything up for you. Remove it
+later with `zotrm cron --remove`.
+
+---
+
+## Everyday commands
+
+```sh
+zotrm push      # send waiting papers to the tablet
+zotrm pull      # bring marked-up papers back into Zotero
+zotrm status    # see what is waiting / on the tablet / done
+zotrm sync      # pull, then push, in one step
+
+zotrm config    # change your settings any time
+zotrm cron      # set up (or change) automatic syncing
+```
+
+Not sure what a command will do? Add `--dry-run` to see without changing anything:
+
+```sh
+zotrm --dry-run push
+```
+
+---
+
+## If something goes wrong
+
+- **"rmapi not found"** → Step 2 was missed, or reopen the Terminal.
+- **"config not found"** → Run `zotrm config` to set up your account.
+- **"no Zotero collection named ..."** → The collection name in your settings doesn't
+  exactly match a collection in Zotero. Check spelling and capital letters
+  (`zotrm config --show` prints your current settings).
+- **Pull finds nothing** → Make sure the tablet is online and finished syncing, and that
+  you have a reMarkable Connect subscription.
+
+Run any command with `--dry-run` first if you're unsure — it changes nothing.
+
+---
+
+## FAQ
+
+**Do I need a reMarkable Connect subscription?**
+Yes, in practice. `zotrm` talks to the reMarkable **cloud** through `rmapi`, and two-way
+document sync (uploading PDFs and downloading annotated ones) needs Connect.
+
+**Why don't my highlights come back as real Zotero highlights?**
+The reMarkable returns a flattened PDF — your marks are baked into the page image. That's a
+reMarkable limitation, not something `zotrm` can change. You get a faithful annotated PDF
+re-attached to the item, just not editable highlight objects.
+
+**Does it duplicate files if I run it again?**
+No. It tags items `rm:synced` once pushed and `rm:annotated` once pulled back, and skips
+anything already done. Re-run it (or schedule it) freely.
+
+**Can I use it with more than one Zotero library?**
+Yes — keep separate config files and pass `--config`. See
+[advanced usage](https://github.com/dipta007/zotRm/blob/main/docs/advanced-usage.md#global-flags).
+
+**Does it work on Windows?**
+Not currently. `zotrm` targets macOS and Linux (the `cron` scheduler is Unix-only).
+
+**Is my Zotero API key safe?**
+It's stored only in your local config file (`~/.config/zotrm/config.ini`) and never sent
+anywhere except Zotero's own API. `zotrm config --show` masks it.
+
+---
+
+## More
+
+- **[Advanced usage](https://github.com/dipta007/zotRm/blob/main/docs/advanced-usage.md)** —
+  editing the config file by hand, the full settings reference, how the scheduled sync
+  works, multiple configs, and deeper troubleshooting.
+- **[Contributing](https://github.com/dipta007/zotRm/blob/main/CONTRIBUTING.md)** — set up
+  the project for development and run the tests.
+
+## License
+
+MIT — see [LICENSE](https://github.com/dipta007/zotRm/blob/main/LICENSE).