Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Timezones CLI

CLI toolkit for timezones⚡

What can you do with timezones-cli? ✨

  • Search for date and time based on city, country, or timezones.
  • Manage dashboard for timezones you frequently view.
  • Get UTC date and time based on your local timezone or any timezones.



  $ pip3 install timezones-cli

To run this CLI using Docker, check Run using Docker 🐳.

NOTE: List of country codes or timezone names 🌏

Use -t flag to toggle 24 hours format.


Search for timezones

Get time based on the entered timezone or country code

  • using country code (either 2 or 3 letters):

      $ tz search US
      $ tz search USA
  • using timezone:

      $ tz search Asia/Kathmandu
  • using fuzzy text: (example: Ireland)

      $ tz search Irela
  • using timezone shortcodes (--zone or -z flag):

      $ tz search pst -z
      $ tz search ist -z
      $ tz search jst -z
      $ tz search cest -z
      $ tz search +0543 -z
      $ tz search +05 -z
Demo demo of timezone cli search

Add/save timezones

Timezones added to the config file are treated as the default timezones which is triggered by the tz show command.

file is stored at ~/.tz-cli

$ tz add "Asia/Kathmandu"
Demo demo of timezone cli add

Remove timezones

There are two ways for removing timezones from the config file. Using the --interactive mode and passing the the --name flag.

$ tz remove -i

$ tz remove --name "Asia/Kathmandu"
Demo demo of timezone cli remove

Show saved timezones

$ tz show
Demo demo of timezone cli show

Select individual timezones from saved

$ tz select
Demo demo of timezone cli select

Get UTC time

Get UTC time based on current system time.

tz utc --help

$ tz utc

Get UTC time based on specified time and timezone.

$ tz utc <time> <timezone>

$ tz utc "11:45PM" "Asia/Kathmandu"
Demo demo of timezone cli select

Run using Docker 🐳

docker pull

Verify signature of the image: requires cosign.

COSIGN_EXPERIMENTAL=true cosign verify

Create a config file manually first.

$ touch ~/.tz-cli

$ docker run --rm -it -v ${HOME}/.tz-cli:/home/tz/.tz-cli search us

For convenience you can add alias of the command to your shell config:

$ echo "alias tz='docker run --rm -it -v ${HOME}/.tz-cli:/home/tz/.tz-cli'" >> ~/.bashrc
$ source ~/.bashrc

$ echo "alias tz='docker run --rm -it -v ${HOME}/.tz-cli:/home/tz/.tz-cli'" >> ~/.zshrc
$ source ~/.zshrc

# Use alias to invoke timezones-cli
$ tz search Nepal

For local debugging: Use the make run command followed by the command you want to run against the tz binary.

$ make run cmd="get ist"
Demo demo of timezone cli with Docker


For guidance on setting up a development environment and how to make a contribution to timezones-cli, see the contributing guidelines.