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):

1. Check statistics first:

   uv run scripts/miniflux-cli.py stats --entry-id=123
   

   Shows word count, character count, reading time.

2. Use pagination to read in chunks:

   # 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:

   # 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

# 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