Changedetection TUI

A terminal user interface (TUI) client for the opensource changedetection.io project.

📽️ Demo Video

🖼️ Screenshots

Main view

Non compact view

Jump mode

Non compact view

Settings (keybindings)

Diff selection modal

✨ 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

🚀 Installation

Using uv (recommended)

uvx --from changedetection-tui cdtui

Or install as a tool:

uv tool install changedetection-tui
# $PATH must contain `uv tool dir`
cdtui

Using pip

pip install changedetection-tui

Using docker

Images are pushed both on the official docker hub and on Github's container registry. The images are the same, use whatever you want.

mkdir ~/.config/cdtui/

docker run --rm -it -v ~/.config/cdtui/:/home/appuser/.config/cdtui/ -u $(id -u):$(id -g) grota/changedetection-tui
# or
docker run --rm -it -v ~/.config/cdtui/:/home/appuser/.config/cdtui/ -u $(id -u):$(id -g) 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

cdtui --url http://your-changedetection-url-here --api-key your-api-key-here

📖 Other ways to specify URL and API key

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.

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

• implement compact view mode
• improve docker documentation usage
• create video demo
• custom diff views?

👨‍💻 Development

Prerequisites

• Python 3.13+
• uv package manager

Setup

# 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

# 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 .

# optional: run a local installation of changedetection for development
docker compose -f compose-dev.yaml up -d

# Update changelog and create tag
uv run cz bump

📂 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 file for details.

🔗 Links and acknowledgements

• changedetection.io
• Textual Framework
• GitHub Repository
• Issue Tracker
• posting for showing me how to use textual