Introduction
# 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 ```