<div align="center">
<h1>Changedetection TUI</h1>
</div>
<div align="center">
[](https://pypi.org/project/changedetection-tui/)
[](hub.docker.com/r/grota/changedetection-tui)
[](https://github.com/grota/changedetection-tui/releases)
[](https://pypi.org/project/changedetection-tui)
</div>
<div align="center">
[](https://github.com/grota/changedetection-tui/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](https://github.com/pre-commit/pre-commit)
</div>
A terminal user interface (TUI) client for the opensource [changedetection.io](https://github.com/dgtlmoon/changedetection.io) project.
## 🖼️ Screenshots
### Main view
<img width="1718" height="1020" alt="Real-time dashboard view of your monitored URLs" src="https://github.com/user-attachments/assets/9f78eb27-a6bb-454c-9733-26a0bbd98c97" />
### Jump mode
<img width="1526" height="1014" alt="cdtui_jump_mode" src="https://github.com/user-attachments/assets/1ecdbee0-1f99-440f-ba5d-2ee8f3bd357a" />
### Settings (keybindings)
<img width="1104" height="1291" alt="cdtui_keybindings" src="https://github.com/user-attachments/assets/e6c29806-8fd1-473c-8e32-cc308449a850" />
### Diff selection modal
<img width="1389" height="651" alt="Diff selection modal" src="https://github.com/user-attachments/assets/b307e1bb-721b-4a7a-8924-5d60fe325432" />
## ✨ Features
- Real-time dashboard view of your monitored URLs
- Diff viewer (in terminal)
- Fast and lightweight
- Configurable keybindings, url and api key
- based on python's [Textual](https://textual.textualize.io/)
## 🚀 Installation
### Using uv (recommended)
```bash
uvx --from changedetection-tui cdtui
```
Or install as a tool:
```bash
uv tool install changedetection-tui
# $PATH must contain `uv tool dir`
cdtui
```
### Using pip
```bash
pip install changedetection-tui
```
### Using docker
Images are pushed both on the official [docker hub](https://hub.docker.com/r/grota/changedetection-tui)
and on Github's [container registry](https://github.com/grota/changedetection-tui/pkgs/container/changedetection-tui).
The images are the same, use whatever you want.
```bash
docker run --rm -it grota/changedetection-tui
# or
docker run --rm -it ghcr.io/grota/changedetection-tui
```
### Pushed tags
These are the docker image tags we push to both registries:
- The major-only semver tag (e.g. `grota/changedetection-tui:1`)
- The full semver tags (e.g. `grota/changedetection-tui:1.2.3`)
- The _latest_ tag: which corresponds to the last commit on the default branch (_main_)
## ⚡️ Usage
### 🚀 Quick Start
```bash
cdtui --url http://your-changedetection-url-here --api-key your-api-key-here
```
### 📖 Other ways to specify URL and API key
<img width="754" height="448" alt="cdtui_help" src="https://github.com/user-attachments/assets/ae485b6b-c472-496a-99a8-cc700f7f2f81" />
The URL and the API key values found can also be persisted to the configuration file after launch via settings, here's a screenshot of the main section.
<img width="1110" height="469" alt="Main settings" src="https://github.com/user-attachments/assets/30ebf7fe-3633-451a-9794-af73b2dc4a95" />
Where you can see that you can avoid storing the API key secret to the configuration file by using the environment variable syntax.
### Keybindings
Current keybindings can be seen in the footer, they can be remapped in settings.
- Open Jump Mode: ctrl+j
- Quit: ctrl+c
- Open settings; ctrl+o
- Focus next: tab
- Focus previous: shift+tab
- Open palette: ctrl+p
- Move left/down/up/right: hjkl
- Dismiss jump mode: esc/ctrl+c
## Roadmap
- [x] implement compact view mode
- [ ] improve docker documentation usage
- [ ] custom diff views
## 👨💻 Development
### Prerequisites
- Python 3.13+
- [uv](https://github.com/astral-sh/uv) package manager
### Setup
```bash
# Clone the repository
git clone https://github.com/grota/changedetection-tui.git
cd changedetection-tui
# Install dependencies
uv sync --dev
# Run from venv
uv run cdtui
# Run in development mode
uv run textual console -x SYSTEM -x WORKER -x DEBUG -x EVENT
# Run connecting to textual's console
uv run textual run --dev .venv/bin/cdtui
```
### Development Tools
```bash
# Install precommits (ruff linting and formatting)
uv run pre-commit install
# Run tests
uv run pytest
# Format code
uv run ruff format .
# Lint code
uv run ruff check .
```
### 📂 Project Structure
```
src/changedetection_tui/
├── __main__.py # CLI entry point
├── app.py # Main application
├── main_screen.py # Main screen layout
├── dashboard/ # Dashboard components
├── settings/ # Settings management
├── utils.py # Utility functions
└── tui.scss # Textual CSS styling
```
## 📙 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔗 Links
- [changedetection.io](https://github.com/dgtlmoon/changedetection.io)
- [Textual Framework](https://textual.textualize.io/)
- [GitHub Repository](https://github.com/grota/changedetection-tui)
- [Issue Tracker](https://github.com/grota/changedetection-tui/issues)
Raw data
{
"_id": null,
"home_page": null,
"name": "changedetection-tui",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "console, tui, textual, changedetection, change, detection",
"author": "Giuseppe Rota",
"author_email": "Giuseppe Rota <403432+grota@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/12/32/a2d53b7eb48b9daf78af5a8e0a381121db7bc7511b4b059f6788f37396b3/changedetection_tui-0.3.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <h1>Changedetection TUI</h1>\n</div>\n\n<div align=\"center\">\n\n[](https://pypi.org/project/changedetection-tui/)\n[](hub.docker.com/r/grota/changedetection-tui)\n[](https://github.com/grota/changedetection-tui/releases)\n[](https://pypi.org/project/changedetection-tui)\n\n</div>\n\n<div align=\"center\">\n\n[](https://github.com/grota/changedetection-tui/actions/workflows/ci.yml)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/pre-commit/pre-commit)\n\n</div>\n\nA terminal user interface (TUI) client for the opensource [changedetection.io](https://github.com/dgtlmoon/changedetection.io) project.\n\n\n## \ud83d\uddbc\ufe0f Screenshots\n\n### Main view\n\n<img width=\"1718\" height=\"1020\" alt=\"Real-time dashboard view of your monitored URLs\" src=\"https://github.com/user-attachments/assets/9f78eb27-a6bb-454c-9733-26a0bbd98c97\" />\n\n### Jump mode\n\n<img width=\"1526\" height=\"1014\" alt=\"cdtui_jump_mode\" src=\"https://github.com/user-attachments/assets/1ecdbee0-1f99-440f-ba5d-2ee8f3bd357a\" />\n\n\n### Settings (keybindings)\n\n<img width=\"1104\" height=\"1291\" alt=\"cdtui_keybindings\" src=\"https://github.com/user-attachments/assets/e6c29806-8fd1-473c-8e32-cc308449a850\" />\n\n\n### Diff selection modal\n\n<img width=\"1389\" height=\"651\" alt=\"Diff selection modal\" src=\"https://github.com/user-attachments/assets/b307e1bb-721b-4a7a-8924-5d60fe325432\" />\n\n\n## \u2728 Features\n\n- Real-time dashboard view of your monitored URLs\n- Diff viewer (in terminal)\n- Fast and lightweight\n- Configurable keybindings, url and api key\n- based on python's [Textual](https://textual.textualize.io/)\n\n\n## \ud83d\ude80 Installation\n\n### Using uv (recommended)\n\n```bash\nuvx --from changedetection-tui cdtui\n```\n\nOr install as a tool:\n\n```bash\nuv tool install changedetection-tui\n# $PATH must contain `uv tool dir`\ncdtui\n```\n\n### Using pip\n\n```bash\npip install changedetection-tui\n```\n\n### Using docker\n\nImages are pushed both on the official [docker hub](https://hub.docker.com/r/grota/changedetection-tui)\nand on Github's [container registry](https://github.com/grota/changedetection-tui/pkgs/container/changedetection-tui).\nThe images are the same, use whatever you want.\n\n```bash\ndocker run --rm -it grota/changedetection-tui\n# or\ndocker run --rm -it ghcr.io/grota/changedetection-tui\n```\n\n### Pushed tags\n\nThese are the docker image tags we push to both registries:\n\n- The major-only semver tag (e.g. `grota/changedetection-tui:1`)\n- The full semver tags (e.g. `grota/changedetection-tui:1.2.3`)\n- The _latest_ tag: which corresponds to the last commit on the default branch (_main_)\n\n## \u26a1\ufe0f Usage\n\n### \ud83d\ude80 Quick Start\n\n```bash\ncdtui --url http://your-changedetection-url-here --api-key your-api-key-here\n```\n\n### \ud83d\udcd6 Other ways to specify URL and API key\n\n<img width=\"754\" height=\"448\" alt=\"cdtui_help\" src=\"https://github.com/user-attachments/assets/ae485b6b-c472-496a-99a8-cc700f7f2f81\" />\n\nThe URL and the API key values found can also be persisted to the configuration file after launch via settings, here's a screenshot of the main section.\n\n<img width=\"1110\" height=\"469\" alt=\"Main settings\" src=\"https://github.com/user-attachments/assets/30ebf7fe-3633-451a-9794-af73b2dc4a95\" />\n\nWhere you can see that you can avoid storing the API key secret to the configuration file by using the environment variable syntax.\n\n### Keybindings\n\nCurrent keybindings can be seen in the footer, they can be remapped in settings.\n\n- Open Jump Mode: ctrl+j\n- Quit: ctrl+c\n- Open settings; ctrl+o\n- Focus next: tab\n- Focus previous: shift+tab\n- Open palette: ctrl+p\n- Move left/down/up/right: hjkl\n- Dismiss jump mode: esc/ctrl+c\n\n## Roadmap\n\n- [x] implement compact view mode\n- [ ] improve docker documentation usage\n- [ ] custom diff views\n\n## \ud83d\udc68\u200d\ud83d\udcbb Development\n\n### Prerequisites\n\n- Python 3.13+\n- [uv](https://github.com/astral-sh/uv) package manager\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/grota/changedetection-tui.git\ncd changedetection-tui\n\n# Install dependencies\nuv sync --dev\n\n# Run from venv\nuv run cdtui\n\n# Run in development mode\nuv run textual console -x SYSTEM -x WORKER -x DEBUG -x EVENT\n# Run connecting to textual's console\nuv run textual run --dev .venv/bin/cdtui\n```\n\n### Development Tools\n\n```bash\n# Install precommits (ruff linting and formatting)\nuv run pre-commit install\n\n# Run tests\nuv run pytest\n\n# Format code\nuv run ruff format .\n\n# Lint code\nuv run ruff check .\n```\n\n### \ud83d\udcc2 Project Structure\n\n```\nsrc/changedetection_tui/\n\u251c\u2500\u2500 __main__.py # CLI entry point\n\u251c\u2500\u2500 app.py # Main application\n\u251c\u2500\u2500 main_screen.py # Main screen layout\n\u251c\u2500\u2500 dashboard/ # Dashboard components\n\u251c\u2500\u2500 settings/ # Settings management\n\u251c\u2500\u2500 utils.py # Utility functions\n\u2514\u2500\u2500 tui.scss # Textual CSS styling\n```\n\n## \ud83d\udcd9 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udd17 Links\n\n- [changedetection.io](https://github.com/dgtlmoon/changedetection.io)\n- [Textual Framework](https://textual.textualize.io/)\n- [GitHub Repository](https://github.com/grota/changedetection-tui)\n- [Issue Tracker](https://github.com/grota/changedetection-tui/issues)\n",
"bugtrack_url": null,
"license": null,
"summary": "TUI client for changedetection.io",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://github.com/grota/changedetection-tui",
"Homepage": "https://github.com/grota/changedetection-tui",
"Issues": "https://github.com/grota/changedetection-tui/issues",
"Repository": "https://github.com/grota/changedetection-tui"
},
"split_keywords": [
"console",
" tui",
" textual",
" changedetection",
" change",
" detection"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "717b58126d0e188d9bb349815cfbf13880d1f2560125c0e09f4b2750f98dc71c",
"md5": "5263e5aaa34ddab4e8b5355b0cb8bd78",
"sha256": "a65a18cf42e625f6c1998aa9f85e6caf249cf8db44952474475471aa8b7a8675"
},
"downloads": -1,
"filename": "changedetection_tui-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5263e5aaa34ddab4e8b5355b0cb8bd78",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 39362,
"upload_time": "2025-10-24T16:36:54",
"upload_time_iso_8601": "2025-10-24T16:36:54.726161Z",
"url": "https://files.pythonhosted.org/packages/71/7b/58126d0e188d9bb349815cfbf13880d1f2560125c0e09f4b2750f98dc71c/changedetection_tui-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1232a2d53b7eb48b9daf78af5a8e0a381121db7bc7511b4b059f6788f37396b3",
"md5": "1ebe3199ee6f3043145d4b258f0ae955",
"sha256": "5276f90b8bc0d9165dab1144699233da0327af21ca989f94e3e4ced66c312122"
},
"downloads": -1,
"filename": "changedetection_tui-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "1ebe3199ee6f3043145d4b258f0ae955",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 29011,
"upload_time": "2025-10-24T16:36:56",
"upload_time_iso_8601": "2025-10-24T16:36:56.137891Z",
"url": "https://files.pythonhosted.org/packages/12/32/a2d53b7eb48b9daf78af5a8e0a381121db7bc7511b4b059f6788f37396b3/changedetection_tui-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-24 16:36:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "grota",
"github_project": "changedetection-tui",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "changedetection-tui"
}
JSON
