miniflux-tui-py

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

Status

Production/Stable

This project has reached production stability with:

• ✅ Comprehensive feature set (categories, feeds, settings, history, runtime theme switching)
• ✅ Non-blocking background operations (sync while using the UI)
• ✅ Robust CI/CD with automated security and quality workflows
• ✅ High test coverage (>60%) across Python 3.11-3.15
• ✅ OpenSSF Best Practices badge
• ✅ PyPI packages with SLSA attestation
• ✅ Professional documentation and API reference

Features

Core Functionality

• 📖 Browse and read feed entries with keyboard navigation
• ✓ Mark entries as read/unread, starred/unstarred
• 💾 Save entries to third-party services (Pocket, Instapaper, etc.)
• 🌐 Open in browser or fetch original content for truncated entries
• 📝 HTML to Markdown conversion for readable display

Organization & Filtering

• 🗂️ Multiple sort modes - date (newest first), feed (alphabetical), or status (unread first)
• 📁 Group by feed or category with expand/collapse
• 🔍 Filter by status - unread only or starred only
• 🔎 Search through entries by title or content
• 🏷️ Category management - organize feeds into categories

Feed Management

• 🔄 Auto-discover feeds from URLs
• ⚙️ Configure feeds - scraping rules, rewrite rules, fetch settings, blocklist/allowlist
• 🔁 Refresh feeds - individual feeds or all feeds
• 📊 Feed status - view problematic feeds and errors
• 🛠️ Feed settings editor - comprehensive feed configuration

User Experience

• ⌨️ Keyboard-driven - extensive Vim-style shortcuts
• 🎨 Runtime theme switching - toggle dark/light mode instantly with 'T' key
• 🔄 Non-blocking sync - navigate and read entries while syncing in background
• 📚 Reading history - browse your 200 most recently read entries
• 🔐 Password manager integration for secure credential storage
• 📦 Multi-platform - Linux, macOS, Windows support

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

Note: After installation with uv tool install or pip install, you can run the application directly with miniflux-tui (no uv run needed). You can also run it as a Python module: python -m 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 (use 'uv run' when running from source without installing)
uv run miniflux-tui

Note: uv run is only needed when running from source without installing the package. After installing with uv tool install or pip install, use miniflux-tui directly.

Documentation

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

• Installation Guide
• Configuration
• Usage Guide
• Contributing

GitHub Codespaces

GitHub Codespaces provides a preconfigured, browser-accessible development environment that works well with the terminal-based interface of miniflux-tui-py. This repository includes a .devcontainer/devcontainer.json so every Codespace starts from a Python 3.13+ image, installs uv, and runs uv sync --locked --all-groups automatically. After the first boot you can launch the TUI with the same commands documented in the From Source section:

uv run miniflux-tui --init
uv run miniflux-tui

To verify the setup before running the application, use:

uv run miniflux-tui --check-config

Keeping your Miniflux credentials secret

Use Codespaces secrets to store your credentials so only the Codespaces that you start can read them:

1. In the repository, go to Settings → Codespaces secrets and add two secrets:
   • MINIFLUX_SERVER_URL: Your Miniflux server URL (e.g. https://miniflux.example.com)
   • MINIFLUX_API_KEY: Your Miniflux API token
2. Launch a Codespace for this repository. GitHub injects the secrets into the environment each time the Codespace starts. If both secrets are present and no config file exists, miniflux-tui will create a Codespaces-optimized config automatically on first run.
3. To create the config manually instead, run miniflux-tui --init-codespace.

Each collaborator must define their own secrets—your personal Codespaces secrets are never shared with other users, and theirs are not shared with you. Avoid writing raw tokens to tracked files inside the Codespace so they are not accidentally committed.

The Codespace is set up so the Visual Studio Code Testing view is ready to run the project's pytest suite without extra configuration. Visual Studio Code also auto-formats Python files with Ruff on save and wires up the default interpreter to the repo's .venv, so the editor, formatter, and tests all work straight away.

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"
password = ["op", "read", "op://Personal/Miniflux/API Token"]
allow_invalid_certs = false

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

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

Retrieving your API token securely

Miniflux authenticates using API tokens. Instead of storing the token directly in config.toml, configure the password field with a command that prints the token to stdout. This keeps the secret in your password manager (for example 1Password, Bitwarden, or pass).

To create a token:

1. Log into your Miniflux server.

2. Go to Settings → API Keys → Create a new API key.

3. Store the generated token in your password manager.

4. Update the password command so it outputs the token, e.g.:

   # 1Password example
   password = ["op", "read", "op://Personal/Miniflux/API Token"]
   
   # Environment variable example
   password = ["/bin/sh", "-c", "printf %s \"$MINIFLUX_TOKEN\""]
   

Keyboard Shortcuts

Entry List View

Entry Reader View

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

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 zensical 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