Tools: timex, xturing, login
Reference for the timex time and weather engine, the xturing terminal settings UI and the static SDDM login theme.
Beyond the compositor and the shell, three repositories provide focused tools: timex (time and weather data plus the calendar UI), xturing (the whole settings panel in the terminal) and login (the static SDDM greeter).
timex
equisdots/timex is the time and weather
engine. It feeds the bar clock, the calendar popup (SUPER + S), the desktop
weather faces and the settings tab.
CLI
timex --json # cached JSON (throttled refresh)
timex --getdata # force a refresh
timex --invalidate # drop the cache after a config change
timex --current-icon # bar module reads
timex --current-temp
timex --current-hex
timex --icon | --temp | --hex # forecast[0] variants
timex providers list # name|label|needs_key|hint
timex geocode "Tokyo" # top 5 matches for the UI picker
timex test # ok|description or fail|error
timex snapshot # icon|temp|max|min|desc|updated_epoch
timex status # provider|city|unit|configured|key_set|last_update|last_error
timex keys set OPENWEATHER_KEY <value>
timex keys remove OPENWEATHER_KEY
timex keys list # NAME|label|where|0-1
The engine runs exactly the selected provider; there are no silent fallbacks.
If the provider is missing a city or key, the cache gets an explicit error
state (Select a provider, Set a city, Set the API key,
Unknown provider). timex is deployed as a plugin: the engine, calendar panel
(ui/TimexPopup.qml, bound to SUPER + S), bar island (bar/Weather.qml) and
settings page (settings/TimexPage.qml) live under
.../quickshell/ui/plugins/timex/. The bar island polls the engine directly,
and the panel is exported as provides.panels.calendar; see
Plugins and extensions.
Providers
| Name | Key | Input | Notes |
|---|---|---|---|
open-meteo |
none | city or lat,lon |
Geocoding cached; 5 days, hourly. |
wttr |
none | city | 3 days, hourly. |
openweather |
yes | city + key | Free tier; geocoding with the key. |
Adding a provider is one executable under api/providers/ that prints the
normalized JSON document, plus one catalog line in core/timex.sh.
Configuration
settings.json -> timex:{ provider, city, unit }plus the UI layout keys (forecastEnabled,forecastPositionbelow/above,forecastSize,forecastGap,forecastHours,forecastShowTime/Icon/Temp,forecastOrderandclockScale). No secrets; the plugin owns its defaults and exposes them in the Timex settings page.- API keys:
~/.local/state/quickshell/timex/keys.conf(mode 600), written withtimex keys set. - Cache:
~/.cache/quickshell/timex/weather.json, with the stablecurrent_temp/current_icon/current_hex/forecast[]contract.
xturing
equisdots/xturing is a Rust/ratatui
TUI that exposes every option of the settings panel (the one bound to
SUPER + SHIFT + D). It reads and writes the same settings.json and calls
the same scripts, so the QML panel and xturing can coexist.
Usage
xturing # installed at ~/.local/bin/xturing
xturing --page d_style # open a page directly
xturing --search palette # open the search palette pre-filled
xturing --dry-run # no external commands; logs to /tmp/xturing-actions.log
xturing --help
| Option | Effect |
|---|---|
--settings <path> |
Alternative settings.json. |
--palettes <dir> |
Alternative palettes directory. |
--page <id> |
Open a page (s_general, d_style, d_palette, ...). |
--search <query> |
Open search pre-filled. |
--dry-run |
Same as XTURING_DRY=1. |
Pages
24 pages across six rail groups:
- Shell: General, Keyboard, Monitors, Startup.
- Bar: General, Position, Style, Zones, Modules, Workspaces.
- Theme: Appearance, Palette, Animations, Shadows, Frame, Glass.
- Behavior: Launcher, Notifications.
- Widgets: Popups (the
Personalization.jssections). - System: Hyprland, Input, GPU, Idle, About.
Keys
Up/Down or j/k move selection (wraps across pages)
Left/Right or h/l adjust / cycle
Tab / Shift+Tab next / previous page
Enter/Space edit, toggle, run
/ or Ctrl+P search palette
r reload settings.json, and in forms record a shortcut
? help
q / Ctrl+C quit
Write contract and sandbox testing
settings.jsonis written atomically (tmp + rename) withserde_json, preserving key order and unknown keys.- Writes are immediate; the shell watchers pick them up live.
- Control characters in
bar.modulesglyphs are preserved as-is.
Test without touching anything:
XTURING_DRY=1 xturing
cp ~/.config/hypr/settings.json /tmp/settings-test.json
XTURING_DRY=1 XTURING_SETTINGS=/tmp/settings-test.json xturing
XTURING_DRY=1 XTURING_SETTINGS=/tmp/settings-test.json \
XTURING_PALETTES_DIR=/tmp/palettes-test xturing
Known differences vs. the QML panel
Interaction differs where drag and drop or swatches do not map to a TUI; the settings file and its format are identical:
- Zones: no drag and drop;
Shift + Left/Rightmove a module within and across zones, Enter enables or disables it. - Monitors: Position X/Y fields replace the drag canvas.
- Palette: colors are edited as
#rrggbb; New palette clones the 8 base colors of the active palette. - General: the xkb layout list is a free text field.
- The Hyprland Refresh button works here (
hypr-effects.sh read); in the current QML panel it calls a method that does not exist.
Structure
src/
settings.rs atomic read/write + tests
catalog.rs data-driven definition of the 24 pages and controls
app.rs state, navigation, editing, special pages, side effects
ui.rs ratatui rendering (rail, content, chooser, forms, help)
palette.rs index.json, palette editing with backup, create/delete
monitors.rs hyprctl monitors, apply/reset with lua + display-config
actions.rs spawn/capture (with dry mode), notify-send
login
equisdots/login is the SDDM greeter: a black screen with the remembered user, a white underline password field, a session picker and small power/reboot buttons, all monochrome and drawn with the Hack Nerd Font.
It is deliberately static. The previous palette-synced theme wrote under
/usr/share/sddm/themes at runtime, which required sudo from hooks and risked
PAM lockouts. This theme is installed once and never writes again:
./install.sh # one-time sudo: theme + sddm config
./install.sh --uninstall # remove theme and its sddm config
The installer copies the theme to /usr/share/sddm/themes/x, selects it in
/etc/sddm.conf.d/10-x-theme.conf and disables the on-screen keyboard. If
another display manager owns display-manager.service, the link is switched
to SDDM (the previous one is backed up as
display-manager.service.equisdots-backup). --uninstall restores it. The
theme lives under theme/x/ with metadata.desktop and honors
theme.conf.user; dots system runs the installer for you.
dots doctor verifies the config file, the static theme (no Colors.qml) and
that SDDM is the active display manager.
Separately, niri-login installs the
Wayland session entry so display managers (SDDM, GDM, any greeter reading
wayland-sessions) list "Niri" at login. It is a system install (sudo) and is
skipped when the distro already ships an entry. dotsniri login install|remove|status
runs it; see niri compositor.
Related pages
- Quickshell shell for the settings panel xturing mirrors.
- Theming and palettes for palette-driven targets.
- Architecture and repositories for install paths.