twidgets 1.1.1

A tool to design and run dynamic, customizable dashboards directly inside your terminal.

🖥 Terminal Widgets

This tool lets you design and run dynamic, customizable dashboards directly inside your terminal. It combines modular widgets, real-time data updates, and flexible layout management for a highly interactive CLI experience.

Getting started • Configuration • Adding new widgets • License

---

🚀 1. Getting started

Installation from PyPI

1. Install: pip install twidgets
2. Initialize: twidgets init
3. Run: twidgets

⚠️ Requires Python Version 3.13+

Installation from Source

1. Clone this repository
2. Install dependencies: pip install -r requirements.txt
3. Initialize configuration: python -m twidgets init
4. Run: python -m twidgets

⚠️ Requires Python Version 3.13+

For full documentation see Setup Guide

---

✨ 2. Configuration

2.1 Changing standard colors and configuration in twidgets/config/base.yaml

If you remove anything or let anything blank, it will just fall back to the standard configuration.
However, you will get warned.

Example:

use_standard_terminal_background: False

background_color:
  r: 31  # Red value
  g: 29  # Green value
  b: 67  # Blue value
  
...

2.2 Configure your secrets in: twidgets/config/secrets.env

Example (Full example provided in twidgets/config/secrets.env.example):

WEATHER_API_KEY='your_api_key'
WEATHER_CITY='Berlin,DE'
WEATHER_UNITS='metric'
NEWS_FEED_URL='https://feeds.bbci.co.uk/news/rss.xml?edition=uk'
NEWS_FEED_NAME='BCC'

2.3 Adjust widgets and layouts in: twidgets/config/widgets/*.yaml

Example:

name: 'clock'
title: ' ⏲ Clock'
enabled: True
interval: 1
height: 5
width: 30
y: 4
x: 87

weekday_format: '%A'  # day of the week
date_format: '%d.%m.%Y'  # us: '%m.%d.%Y', international: '%Y-%m-%d'
time_format: '%H:%M:%S'  # time

For full documentation see Configuration Guide

---

⭐ 3. Adding new widgets

See Widget Guide

---

📜 4. License

See License