miniflux

# Miniflux Skill Browse, read, and manage Miniflux RSS/atom feed articles through a CLI. ## Quick Start ```bash # 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 ```bash # 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. ```bash # 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. ```bash # 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. ```bash # 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. ```bash uv run scripts/miniflux-cli.py mark-unread 123 ``` ### feeds - List Feeds List all configured feeds. ```bash # 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. ```bash uv run scripts/miniflux-cli.py categories ``` ### stats - Statistics Show unread counts or article statistics. ```bash # 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. ```bash # 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`. ```bash 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): 1. **Check statistics first:** ```bash uv run scripts/miniflux-cli.py stats --entry-id=123 ``` Shows word count, character count, reading time. 2. **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 ``` 3. **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 `list` to 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 ```bash # 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 ```bash # 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 ```bash # 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: ```bash uv run scripts/miniflux-cli.py <subcommand> --help ```