miniflux-tui-py 0.4.6

A Python TUI client for Miniflux RSS reader with feed sorting capabilities

miniflux-tui-py

A Python TUI (Terminal User Interface) client for the Miniflux self-hosted RSS reader built with textual.

Installation

From PyPI (Recommended with uv)

# Install uv (see: https://docs.astral.sh/uv/getting-started/installation/)
# On macOS/Linux: brew install uv
# On Windows: winget install astral-sh.uv
# Or visit https://docs.astral.sh/uv/getting-started/installation/

# Install miniflux-tui-py
uv tool install miniflux-tui-py

# Create configuration
miniflux-tui --init

# Run the application
miniflux-tui

Alternative: Using pip

pip install miniflux-tui-py
miniflux-tui --init
miniflux-tui

From Source (For Developers)

# Install uv (see: https://docs.astral.sh/uv/getting-started/installation/)
# On macOS/Linux: brew install uv
# On Windows: winget install astral-sh.uv
# Or visit https://docs.astral.sh/uv/getting-started/installation/

# Clone the repository
git clone https://github.com/reuteras/miniflux-tui-py.git
cd miniflux-tui-py

# Install all dependencies (including dev and docs)
uv sync --all-groups

# Create default configuration
uv run miniflux-tui --init

# Run the application
uv run miniflux-tui

Documentation

Full documentation is available at reuteras.github.io/miniflux-tui-py

• Installation Guide
• Configuration
• Usage Guide
• Contributing

Configuration

Create a configuration file at:

• Linux: ~/.config/miniflux-tui/config.toml
• macOS: ~/.config/miniflux-tui/config.toml
• Windows: %APPDATA%\miniflux-tui\config.toml

Example configuration:

server_url = "https://miniflux.example.com"
api_key = "your-api-key-here"
allow_invalid_certs = false

[theme]
unread_color = "cyan"
read_color = "gray"

[sorting]
default_sort = "feed"  # Options: "feed", "date", "status"
default_group_by_feed = false

To generate an API key for your Miniflux account:

1. Log into your Miniflux server
2. Go to Settings -> API Keys -> Create a new API key

Keyboard Shortcuts

Entry List View

Key	Action
↑/↓ or k/j	Navigate entries
Enter	Open entry
m	Toggle read/unread
*	Toggle star
e	Save entry to third-party service
s	Cycle sort mode (date/feed/status)
g	Toggle grouping by feed
Shift+G	Expand all feeds (when grouped)
Shift+Z	Collapse all feeds (when grouped)
o	Toggle fold/unfold on feed header (when grouped)
h or ←	Collapse individual feed (when grouped)
l or →	Expand individual feed (when grouped)
r or ,	Refresh entries
u	Show unread entries
t	Show starred entries
?	Show keyboard help
q	Quit application

Entry Reader View

Key	Action
↑/↓ or k/j	Scroll up/down
PageUp/PageDown	Fast scroll
J	Next entry
K	Previous entry
m	Toggle read/unread
*	Toggle star
e	Save entry to third-party service
o	Open in browser
f	Fetch original content
b or Esc	Back to list
?	Show keyboard help

Contributing

Contributions are welcome! See CONTRIBUTING.md for details on:

• Setting up your development environment
• Running tests and checks
• Submitting pull requests

For release information and troubleshooting, see:

• RELEASE.md - How to create releases
• docs/RELEASE_TROUBLESHOOTING.md - Handling release failures

Development

# Install all development dependencies
uv sync --all-groups

# Lint code
uv run ruff check .

# Type check
uv run pyright miniflux_tui tests

# Run tests
uv run pytest tests --cov=miniflux_tui

# Preview documentation locally
uv run mkdocs serve

Why Python?

This project is a Python implementation of cliflux (Rust), created since I don't now Rust and wanted to do some changes to that code.

License

MIT License - see LICENSE file for details.

Related Projects

• cliflux - Original Rust TUI client for Miniflux that inspired this tool.
• Miniflux is a minimalist and opinionated feed reader.
• textual