worldclock-tty

A terminal-based world clock that displays multiple timezones in real-time.

This program is a heavy refactor of a timezone clock I made in 2016.

Installation

uv tool install worldclock-tty

Usage

Run the clock:

worldclock-tty

Press Ctrl+C to exit.

The display shows your local time at the top, followed by all configured timezones in two columns, updated once a second by default (configurable with --interval).

Options

worldclock-tty --no-sort          # keep the order from config
worldclock-tty --no-offset        # hide UTC offset labels
worldclock-tty -n 5               # refresh every 5s, aligned to :00, :05, :10
worldclock-tty --12h              # 12-hour clock with AM/PM
worldclock-tty --military         # Zulu/November letters instead of UTC±N
worldclock-tty --military --utc   # letters and the numeric offset (e.g. P UTC-3)
worldclock-tty --full-military    # DTG format: 041430Z JUL 26
worldclock-tty --theme matrix     # use a color theme for this run
worldclock-tty --color time=green --color city=45   # tweak individual colors
worldclock-tty --no-sort --no-offset

--interval (-n) sets the seconds between refreshes and snaps each redraw to the wall clock: -n 5 updates at :00, :05, :10, …; -n 2 at :00, :02, :04, …; and -n 60 at the top of each minute. Intervals that don't divide a minute evenly (e.g. -n 7) stay evenly spaced from midnight. It pairs well with --full-military (minute-precision) and with a clock left running all day.

Military zone letters map each whole-hour UTC offset to a letter: Z is UTC+0, A…M run east (skipping J, reserved for local time), and N…Y run west. Offsets with no official designator (half-hour zones like India at UTC+5:30, or anything beyond ±12h) fall back to the numeric UTC±N.

--full-military (--dtg) replaces each time with a Date-Time Group: DDHHMM + zone letter + MON YY, e.g. 041430Z JUL 26 (day 04, 14:30, Zulu, July 2026). It is minute-precision and always 24-hour, so it overrides the offset and --12h flags. Zones with no official letter use *.

The LOCAL header always ends in J (Juliet). In the military system Juliet is local time itself, not a fixed UTC offset, so the header stays J whatever your offset happens to be. This is expected even when your own zone also appears in the list with its offset letter: at UTC-3 the header reads ...J while the matching row reads ...P (Papa). The two are consistent: J labels "your local time", P labels "the -3 offset".

Colors and themes

Every element on screen is colorable: city, offset, time (the world-clock rows) and label, date, local-time (the LOCAL header). Colors are given as a name (e.g. green, cornflower_blue) or a 256-color code (0–255).

Pick a built-in theme for a run, or override individual elements with --color (repeatable). Precedence, lowest to highest: default, the saved theme, --theme, then --color.

worldclock-tty --theme ocean
worldclock-tty --theme matrix --color time=196     # theme, then tweak one element
worldclock-tty --color label=cyan --color city=45  # override on the default theme

Save a theme as your default. That is the only thing persisted in the config; per-run --color tweaks are never saved:

worldclock-tty theme set matrix    # persist as the default
worldclock-tty theme list          # list themes; the saved one is marked
worldclock-tty theme reset         # back to the built-in default

Built-in themes: default, mono, matrix, amber, ocean.

Managing timezones

Timezones are stored in $XDG_CONFIG_HOME/worldclock-tty/config.json (defaults to ~/.config/worldclock-tty/config.json). Use IANA timezone names (e.g. America/Chicago, Europe/Paris).

worldclock-tty add America/Chicago       # add a timezone
worldclock-tty remove America/Chicago    # remove a timezone
worldclock-tty list                      # show configured timezones
worldclock-tty reset                     # restore built-in defaults

Default timezones

America/Buenos_Aires, America/Caracas, America/La_Paz, America/Lima, America/Los_Angeles, America/Montevideo, America/New_York, America/Sao_Paulo, Asia/Bangkok, Asia/Dubai, Asia/Hong_Kong, Asia/Istanbul, Asia/Tokyo, Asia/Vladivostok, Atlantic/Bermuda, Atlantic/Canary, Australia/Sydney, Europe/London, Europe/Madrid, Europe/Moscow, Europe/Rome, Pacific/Honolulu.

Requirements

Python 3.10+

License

MIT