gtime 0.8.4

Global Time Utility (gtime) - A modern, colorful Python CLI utility for global time zone lookup, comparison, and management. It supports fuzzy search, favorites, city comparison, meeting time conversion, and a live/watch mode

Global Time Utility (gtime)

Stop Googling time zones.

Recorded in Ghostty. Some output may look off in the GIF but works perfectly in a real terminal. Best with Ghostty or Kitty.

If this saves you from one more "what time is it in Tokyo?" search, give it a star.

A modern, colorful Python CLI for global time zone lookup, comparison, and management. Fuzzy search, favorites, live updates, meeting time conversion, and beautiful terminal output.

Installation

# With uv (recommended)
uv tool install gtime

# Or with pip
pip install gtime

# From source
git clone https://github.com/savitojs/gtime.git
cd gtime && uv sync
uv run gtime --help

Quick Start

gtime London                              # Look up any city (fuzzy search)
gtime add Tokyo Singapore "New York"      # Add favorites
gtime                                     # Show all favorites
gtime compare London Tokyo Sydney         # Compare times side by side
gtime meeting at "2:00 PM"                # Convert across favorites
gtime meeting at "3 PM UTC"               # With timezone support
gtime watch                               # Live monitoring (refreshes every 60s)

Features

Smart search - Fuzzy matching, case-insensitive, works with typos (gtime toky finds Tokyo), and country names (gtime india finds Delhi).

Favorites - Save your most-used cities. Sorted by UTC offset for a natural reading order.

gtime add London Tokyo Mumbai Berlin      # Add multiple cities
gtime remove Berlin                       # Remove a city
gtime                                     # View all favorites

Meeting planner - Convert a meeting time across all your favorite cities. Supports 12/24-hour format and timezone abbreviations.

gtime meeting at "10:00 AM"               # Your local time across favorites
gtime meeting at "15:30"                   # 24-hour format
gtime meeting at "9:00 AM EST"            # Eastern Standard Time
gtime meeting at "3 PM UTC"               # Coordinated Universal Time

Live watch mode - Real-time updates for favorites or specific cities.

gtime watch                               # Monitor all favorites
gtime compare London Tokyo --watch        # Watch specific cities

GNOME Desktop Widget

Display your favorite cities on your GNOME desktop using the Desktop Widgets (azclock) extension.

Three styles available:

gtime widget        # Style A (default) - flags, color-coded time, status
gtime widget b      # Grouped by status (Working, Sleeping, etc.)
gtime widget c      # Compact cards with hour diff from local

Style A - Flags + color-coded time + status:

🇺🇸 New York   23:05       ● Sleeping  UTC-4
🇨🇿 Brno       04:05  +1d  ● Sleeping  UTC+1
🇮🇳 Delhi      09:35  +1d  ● Working   UTC+5:30
🇦🇺 Melbourne  14:05  +1d  ● Working   UTC+11

Style B - Grouped by status:

💻 Working
  🇮🇳 Delhi      09:35  +1d
  🇦🇺 Melbourne  14:05  +1d
💤 Sleeping
  🇺🇸 New York   23:05
  🇨🇿 Brno       04:05  +1d

Style C - Compact cards:

🇺🇸 New York  🌙
   23:05  ● Sleeping  local
🇮🇳 Delhi  🌅
   09:35  +1d  ● Working  +9.5h

Setup

1. Install the Desktop Widgets GNOME extension
2. Add a widget with a Command Label element
3. Set the command to gtime widget a (or b / c)
4. Enable Polling with interval 60000 (1 minute)

A reference dconf config is included at gtime/widget-azclock-sidebar.dconf:

# Back up first
dconf dump /org/gnome/shell/extensions/azclock/ > backup.dconf

# Import the sidebar layout
dconf load /org/gnome/shell/extensions/azclock/ < gtime/widget-azclock-sidebar.dconf

Development

uv venv .venv && source .venv/bin/activate
uv sync
pytest tests/

Contributions welcome! Fork, branch, make changes, add tests, and open a PR.

License

MIT - see LICENSE.

---

Report bugs or request features.

Made with ❤️ for developers working across time zones