https://github.com/thiswillbeyourgithub/freshrss_to_karakeep
A Python tool to transfer saved/favorited items from FreshRSS to Karakeep with tagging and filtering capabilities.
https://github.com/thiswillbeyourgithub/freshrss_to_karakeep
Last synced: 8 months ago
JSON representation
A Python tool to transfer saved/favorited items from FreshRSS to Karakeep with tagging and filtering capabilities.
- Host: GitHub
- URL: https://github.com/thiswillbeyourgithub/freshrss_to_karakeep
- Owner: thiswillbeyourgithub
- Created: 2025-05-18T14:20:13.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-06-04T20:11:54.000Z (9 months ago)
- Last Synced: 2025-06-04T22:58:02.840Z (9 months ago)
- Language: Python
- Size: 10.7 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# FreshRSS to Karakeep
A tool to transfer saved/favorited items from [FreshRSS](https://github.com/FreshRSS/FreshRSS) to [Karakeep](https://github.com/karakeep-app/karakeep).
[](https://www.gnu.org/licenses/gpl-3.0)
## Overview
FreshRSS to Karakeep simplifies the curation workflow between self-hosted FreshRSS (RSS reader) and Karakeep (bookmarking/read-it-later app). The tool automatically transfers items you've marked as "favorites" (saved) in FreshRSS to your Karakeep instance, applying the "freshrss" tag for easy identification.
## Workflow
The intended workflow is simple:
1. Browse your RSS feeds in FreshRSS
2. Mark interesting items as "favourite" (which is called 'saved' in the Fever API)
3. Have a scheduled job (e.g., systemd timer) run this script daily
4. Find your saved items in Karakeep with the "freshrss" tag
## Dependencies
This tool relies on two custom API clients that I made:
- [karakeep_python_api](https://github.com/thiswillbeyourgithub/karakeep_python_api/)
- [freshrss_python_api](https://github.com/thiswillbeyourgithub/freshrss_python_api/)
## Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/freshrss-to-karakeep.git
cd freshrss-to-karakeep
# Install dependencies
pip install -r requirements.txt
```
## Configuration
You need to set the following environment variables:
### FreshRSS Configuration
```bash
export FRESHRSS_PYTHON_API_HOST="https://your-freshrss-instance.com"
export FRESHRSS_PYTHON_API_USERNAME="your_username"
export FRESHRSS_PYTHON_API_PASSWORD="your_password"
```
### Karakeep Configuration
```bash
export KARAKEEP_PYTHON_API_ENDPOINT="https://your-karakeep-instance.com/api/v1"
export KARAKEEP_PYTHON_API_KEY="your_api_key"
export KARAKEEP_PYTHON_API_VERBOSE="true" # Optional
export KARAKEEP_PYTHON_API_VERIFY_SSL="true" # Optional, defaults to true
```
### Logging Configuration
The application always logs at DEBUG level to a log file, but console output verbosity can be controlled with the `--verbose` flag.
## Usage
```bash
# Basic usage
python freshrss_to_karakeep.py
# Only include items with URLs matching a pattern
python freshrss_to_karakeep.py --needed-regex "github\.com"
# Exclude items with URLs matching a pattern
python freshrss_to_karakeep.py --ignore-regex "youtube\.com"
# Dry run (don't actually transfer, just show what would be transferred)
python freshrss_to_karakeep.py --dry-run
# Keep items saved in FreshRSS after transfer
python freshrss_to_karakeep.py --no-unsave-freshrss
```
### Command-line Arguments
| Argument | Description | Default |
|----------|-------------|---------|
| `--needed-regex` | Only include items with URLs matching this regex | `.*` (all URLs) |
| `--ignore-regex` | Exclude items with URLs matching this regex | `""` (none) |
| `--dry-run` | Don't actually transfer items, just show what would be transferred | `False` |
| `--unsave-freshrss/--no-unsave-freshrss` | Whether to unsave items from FreshRSS after transfer | `True` |
| `--verbose` | Show detailed log messages in console output | `False` |
## Automation with systemd
To run this script daily, you can set up a systemd service and timer:
1. Create a service file at `/etc/systemd/system/freshrss-to-karakeep.service`:
```ini
[Unit]
Description=Transfer saved items from FreshRSS to Karakeep
After=network.target
[Service]
Type=oneshot
ExecStart=/usr/bin/python3 /path/to/freshrss_to_karakeep.py
Environment="FRESHRSS_PYTHON_API_HOST=https://your-freshrss-instance.com"
Environment="FRESHRSS_PYTHON_API_USERNAME=your_username"
Environment="FRESHRSS_PYTHON_API_PASSWORD=your_password"
Environment="KARAKEEP_PYTHON_API_ENDPOINT=https://your-karakeep-instance.com/api/v1/"
Environment="KARAKEEP_PYTHON_API_KEY=your_api_key"
# No environment variable for logging needed anymore
WorkingDirectory=/path/to/directory
[Install]
WantedBy=multi-user.target
```
2. Create a timer file at `/etc/systemd/system/freshrss-to-karakeep.timer`:
```ini
[Unit]
Description=Run FreshRSS to Karakeep transfer daily
[Timer]
OnCalendar=daily
Persistent=true
[Install]
WantedBy=timers.target
```
3. Enable and start the timer:
```bash
sudo systemctl enable freshrss-to-karakeep.timer
sudo systemctl start freshrss-to-karakeep.timer
```
## License
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
---
*This README was created with assistance from [aider.chat](https://github.com/Aider-AI/aider/)*