timezone-tool

A Python CLI for timezone conversion, meeting planning, and world clock display. Zero external dependencies.

Features

• Current time in any timezone
• Convert between any two timezones
• List all timezones with filtering by region or UTC offset
• Meeting planner showing a time across multiple timezones
• Countdown to a specific datetime
• World clock for 15 major cities
• UTC offset calculator with DST detection
• Business hours overlap finder across timezones
• Next occurrence of a specific time in a timezone

Requirements

Python 3.9+ (uses zoneinfo from stdlib)

Usage

# Show current time in a timezone
python timezone_tool.py now Asia/Kuala_Lumpur
python timezone_tool.py now US/Eastern

# Convert between timezones
python timezone_tool.py convert "14:30" US/Eastern Asia/Tokyo
python timezone_tool.py convert "2026-03-15 09:00" Europe/London America/New_York

# List timezones
python timezone_tool.py list
python timezone_tool.py list --region Asia
python timezone_tool.py list --offset "+08:00"

# Meeting planner
python timezone_tool.py meeting US/Eastern Europe/London Asia/Tokyo -t "10:00"
python timezone_tool.py meeting America/New_York Asia/Kuala_Lumpur Europe/Berlin

# Countdown to a datetime
python timezone_tool.py countdown "2026-12-31 23:59" US/Eastern

# World clock
python timezone_tool.py world

# UTC offset with DST info
python timezone_tool.py offset America/New_York

# Find business hours overlap
python timezone_tool.py overlap US/Eastern Asia/Tokyo Europe/London
python timezone_tool.py overlap US/Pacific Asia/Singapore --start 8 --end 18

# Next occurrence of a time
python timezone_tool.py next "09:00" Asia/Tokyo

Output Examples

World Clock

World Clock (2026-03-04 12:00 UTC):

  New York             07:00  Wed Mar 04  (UTC-05:00)
  London               12:00  Wed Mar 04  (UTC+00:00)
  Tokyo                21:00  Wed Mar 04  (UTC+09:00)
  Sydney               23:00  Wed Mar 04  (UTC+11:00)

Meeting Planner

Meeting at 2026-03-04 10:00 (US/Eastern):

  US/Eastern                     2026-03-04 10:00 EST [business hours]
  Europe/London                  2026-03-04 15:00 GMT [business hours]
  Asia/Tokyo                     2026-03-05 00:00 JST [night]

Business Hours Overlap

Business hours overlap (9:00 - 17:00 local):

  Overlapping UTC hours: 14:00 - 17:00 UTC

  UTC 14:00 -> US/Eastern: 09:00, Europe/London: 14:00
  UTC 15:00 -> US/Eastern: 10:00, Europe/London: 15:00
  UTC 16:00 -> US/Eastern: 11:00, Europe/London: 16:00

Supported Timezones

All IANA timezone names are supported (e.g., America/New_York, Europe/London, Asia/Tokyo). Run python timezone_tool.py list to see all available timezones.

License

MIT