Flux
Universal Hot-Reload Manager
Flux is a cross-platform, language-agnostic CLI tool that watches your code and automatically restarts any shell command when files change. It ships with zero-config defaults, optional TOML/YAML configuration, and a Rich-powered TUI for live logs and timing.
🚀 Features
- Universal watcher: wrap any command (servers, test runners, compilers, file sync, etc.)
- Zero-config: sensible defaults (watch
./, ignore.git/,venv/,node_modules/, all extensions, 200 ms debounce) - Config file support:
hotreload.tomlorhotreload.yamlfor persistent settings - Flexible CLI flags: override paths, ignore patterns, extensions, debounce interval, and command
- Debounced restarts: coalesce rapid file changes into a single restart
- Cross-platform: Linux (inotify), macOS (FSEvents), Windows (ReadDirectoryChangesW)
- Rich TUI: color-coded stdout vs stderr, process status indicator, and runtime timer
💾 Installation
From PyPI (soon):
pip install flux
From source (editable mode):
git clone https://github.com/yourusername/flux.git
cd flux
pip install -e .
⚡ Quick Start
Wrap your existing command:
flux -- python server.py --port 8080
Flux will watch the current directory (.), ignore common folders, and restart your process whenever any file changes, showing logs and restart timings in its built-in TUI.
📖 CLI Usage
Usage: flux [OPTIONS] -- <command>...
Options:
-w, --watch PATH Paths to watch (repeatable)
-i, --ignore PATH Paths to ignore (repeatable)
--exts TEXT Comma-separated extensions (e.g. py,html)
--debounce INT Debounce interval in milliseconds (default: 200)
-c, --config PATH Path to hotreload.toml or .yaml
--help Show this message and exit
Examples
# Watch src/ and templates/, ignore tests/
flux -w src -w templates -i tests -- python app.py
# Only trigger on .py and .html changes
flux --exts py,html -- python app.py
# Increase debounce to 500 ms
flux --debounce 500 -- python app.py
# Using a config file
flux -c hotreload.toml
⚙️ Configuration File
Drop a hotreload.toml or hotreload.yaml in your project root:
# hotreload.toml
watch = ["src/", "templates/"]
ignore = ["tests/", "venv/"]
exts = ["py", "html"]
debounce_ms = 300
cmd = ["python", "app.py", "--port", "8080"]
# hotreload.yaml
watch:
- src/
- templates/
ignore:
- tests/
- venv/
exts:
- py
- html
debounce_ms: 300
cmd:
- python
- app.py
- --port
- "8080"
Then simply:
flux -c hotreload.toml
Flux will pick up all your settings and run your command with automatic reloads.
🏗 Architecture Overview
Flux is built as an async event-driven pipeline:
- Watcher
Useswatchdogto observe filesystem changes and pushes events into anasyncio.Queue. - Debouncer
Coalesces rapid bursts of events into a singleReloadSignal. - Process Manager
Gracefully kills & restarts your wrapped command viaasyncio.create_subprocess_exec. - Renderer
Renders a Rich TUI: color-coded logs, ▶️/⏸ status icon, and restart timers.
Each stage is decoupled by queues, adheres to SOLID principles, and is easy to unit-test or extend.
🤝 Contributing
- Fork the repo
- Create a feature branch:
git checkout -b feat/my-feature
- Commit your changes & add tests
- Open a Pull Request
Please follow the existing code style, write tests for new features, and ensure the TUI remains responsive.
Metadata
Release files for flux-reload 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| flux_reload-0.1.0.tar.gz | 10.0 kB | Without provenance | Details for flux_reload-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| flux_reload-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for flux_reload-0.1.0-py3-none-any.whl |
Total release size: 18.0 kB
Release files / flux_reload-0.1.0.tar.gz
| Download URL | flux_reload-0.1.0.tar.gz |
|---|---|
| Size | 10.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
17dbea5197b977ed26182aae85f82065d54905f793db75339f6aa9460e636b48
|
|
BLAKE2b-256 checksum How to use checksums |
e8ea33cb8df245e3b94feed32601df713eeb4ecbdb3a1af5c5df448d0d183671
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.12
|
Release files / flux_reload-0.1.0-py3-none-any.whl
| Download URL | flux_reload-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fb83bf682fcaebe6340e58c71428ba4c91e70f86d8b74056925c2c8dbb7806ac
|
|
BLAKE2b-256 checksum How to use checksums |
7288a6f135979ba9da69f736d8d844f1a94753bf9e4236507a8fe7348496e591
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.12
|
Security for flux-reload 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.