miniflux-tui-py 0.4.18

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

Prebuilt Binaries (GitHub Releases)

If you do not want to manage a Python environment, each tagged release now attaches standalone binaries for Linux (x86_64), macOS (arm64), and Windows (x86_64):

1. Download the archive for your platform from the GitHub Releases page.
2. Extract the archive:
   • Linux/macOS: tar -xzf miniflux-tui-<os>-<arch>.tar.gz
   • Windows: right-click the .zip file and choose Extract All…
3. (Linux/macOS only) Make the binary executable: chmod +x miniflux-tui
4. Run the TUI: ./miniflux-tui --init

Note: macOS may quarantine binaries downloaded from the internet. If macOS blocks execution, run xattr -d com.apple.quarantine miniflux-tui once after extraction.

Container Image (Docker/Podman)

# Pull the signed image from GitHub Container Registry
# `latest` tracks the default branch. Replace with a release tag (e.g. v0.4.0) to pin.
docker pull ghcr.io/reuteras/miniflux-tui:latest

# Create a configuration directory on the host if it does not exist
mkdir -p ~/.config/miniflux-tui

# Generate a config file (writes to the mounted directory)
docker run --rm -it \
  -v ~/.config/miniflux-tui:/home/miniflux/.config/miniflux-tui \
  ghcr.io/reuteras/miniflux-tui:latest \
  --init

# Launch the TUI (shares configuration and uses your terminal)
docker run --rm -it \
  -v ~/.config/miniflux-tui:/home/miniflux/.config/miniflux-tui \
  ghcr.io/reuteras/miniflux-tui:latest

The image is built in CI, published to GHCR, and signed with Sigstore Cosign using GitHub OIDC so you can verify it with:

cosign verify ghcr.io/reuteras/miniflux-tui:latest

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

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