Miniflux Skill
Browse, read, and manage Miniflux RSS/atom feed articles through a CLI.
Quick Start
# List unread articles (brief format)
uv run scripts/miniflux-cli.py list --status=unread --brief
# Get article details
uv run scripts/miniflux-cli.py get 123
# Mark articles as read
uv run scripts/miniflux-cli.py mark-read 123 456
# Show article statistics (word count, reading time)
uv run scripts/miniflux-cli.py stats --entry-id=123
Configuration
Configuration precedence (highest to lowest):
1. CLI flags: --url, --api-key
2. Environment variables: MINIFLUX_URL, MINIFLUX_API_KEY
3. Config file: ~/.local/share/miniflux/config.json (auto-created on first run)
Setup
# Option 1: Environment variables (recommended for agents)
export MINIFLUX_URL="https://miniflux.example.org"
export MINIFLUX_API_KEY="your-api-key"
# Option 2: CLI flags (one-time, saves to config)
uv run scripts/miniflux-cli.py --url="https://miniflux.example.org" --api-key="xxx" list
Subcommands
list - List Articles
List articles with optional filtering.
# Unread articles (brief)
uv run scripts/miniflux-cli.py list --status=unread --brief
# From specific feed with summary
uv run scripts/miniflux-cli.py list --feed=42 --summary
# Search with limit
uv run scripts/miniflux-cli.py list --search="python" --limit=10
# Starred articles
uv run scripts/miniflux-cli.py list --starred
Flags:
- --status={read,unread,removed} - Filter by status
- --feed=ID - Filter by feed ID
- --category=ID - Filter by category ID
- --starred - Show only starred
- --search=QUERY - Search articles
- --limit=N - Max number of entries
- --offset=N - Skip first N chars in content
- --content-limit=N - Max characters per article
- -b, --brief - Titles only
- -s, --summary - Title + excerpt
- -f, --full - Full content (default)
- --json - JSON output
- --plain - Single-line per entry
get - Get Article by ID
Fetch a single article with content control.
# Full article
uv run scripts/miniflux-cli.py get 123
# First 2000 characters
uv run scripts/miniflux-cli.py get 123 --limit=2000
# Read from character 1000 to 2000 (pagination)
uv run scripts/miniflux-cli.py get 123 --offset=1000 --limit=1000
When content is truncated, shows: [...truncated, total: N chars]
mark-read - Mark as Read
Mark one or more articles as read.
# Single article
uv run scripts/miniflux-cli.py mark-read 123
# Multiple articles
uv run scripts/miniflux-cli.py mark-read 123 456 789
mark-unread - Mark as Unread
Mark one or more articles as unread.
uv run scripts/miniflux-cli.py mark-unread 123
feeds - List Feeds
List all configured feeds.
# Human-readable
uv run scripts/miniflux-cli.py feeds
# JSON format
uv run scripts/miniflux-cli.py feeds --json
categories - List Categories
List all categories.
uv run scripts/miniflux-cli.py categories
stats - Statistics
Show unread counts or article statistics.
# Article statistics (word count, character count, reading time)
uv run scripts/miniflux-cli.py stats --entry-id=123
# Global unread counts per feed
uv run scripts/miniflux-cli.py stats
refresh - Refresh Feeds
Trigger feed refresh.
# Refresh all feeds
uv run scripts/miniflux-cli.py refresh --all
# Refresh specific feed
uv run scripts/miniflux-cli.py refresh --feed=42
search - Search Articles
Convenient alias for list --search.
uv run scripts/miniflux-cli.py search "rust"
uv run scripts/miniflux-cli.py search "ai" --status=unread --brief
Output Formats
--brief/-b- Quick overview (titles + feed + date)--summary/-s- Title + content preview (200 chars)--full/-f- Complete article content (default)--json- Raw JSON output for machine processing--plain- Single-line per entry (tab-separated)
Long Article Handling
For articles with large content (e.g., >5k words):
-
Check statistics first:
bash uv run scripts/miniflux-cli.py stats --entry-id=123
Shows word count, character count, reading time. -
Use pagination to read in chunks:
```bash
# First 5000 chars
uv run scripts/miniflux-cli.py get 123 --limit=5000
# Next 5000 chars (chars 5000-10000)
uv run scripts/miniflux-cli.py get 123 --offset=5000 --limit=5000
```
- For summarization: If article is >5000 words, use a subagent to read and summarize:
```bash
# Get stats to determine word count
uv run scripts/miniflux-cli.py stats --entry-id=123
# If >5000 words, delegate to subagent for summarization
```
Error Handling
The CLI provides helpful error messages:
- Invalid credentials → Check
MINIFLUX_API_KEY - Article not found → Suggests using
listto browse - Missing config → Shows config file location
- No results → Clear message
Standard Flags
-v, --version- Show version-q, --quiet- Suppress non-error output-d, --debug- Enable debug output--no-color- Disable colored output--url=URL- Miniflux server URL--api-key=KEY- Miniflux API key
Examples
Daily Workflow
# Check what's unread
uv run scripts/miniflux-cli.py list --status=unread --brief
# Read interesting articles
uv run scripts/miniflux-cli.py get 456
# Mark as read
uv run scripts/miniflux-cli.py mark-read 456
Research Mode
# Search for specific topics
uv run scripts/miniflux-cli.py search "machine learning" --summary
# Get full article content
uv run scripts/miniflux-cli.py get 789
Batch Processing
# Get all unread as JSON for processing
uv run scripts/miniflux-cli.py list --status=unread --json
# Mark multiple as read
uv run scripts/miniflux-cli.py mark-read 123 456 789
For complete help on any subcommand:
uv run scripts/miniflux-cli.py <subcommand> --help
