Awesome

🌐 A time zone helper

tz helps you schedule things across time zones. It's an interactive TUI program that displays time across the time zones of your choosing.

Usage

Run tz with no arguments to show the local time, as well as the UTC time zone. It gets more useful when you pass some time zones to the program, to list those below the local time zone.

For now, you need to select the time zones from the tz_data list. Yes, there are plans to make this friendlier for humans too. You're welcome to file an issue about it. I enjoy reading those.

If you would rather not type the list everytime, you could set an alias for your shell, or use the TZ_LIST environment variable with a semi-colon separated list of tz data zone names, or use a configuration file (see Configuration below).

Check out tz -h for other flags.

The program will adjust to light and dark terminals themes.

Installing

I provide linux/amd64 builds for "official" releases, and you can build from source for your favorite architecture. Kind souls have also packaged the program for other OSes.

Packages

Brew

Brew has a tz package: brew install tz

Archlinux

If you're an Archlinux user, packages are also available:

tz follows releases and,
tz-git builds the main git branch.

Go

go install github.com/oz/tz@latest

Configuration

The tz program uses standard time zones as described here.

You can specify preferences through a configuration file, an environment variable, or as command arguments.

They are applied in this order, overriding at each subsequent step:

Configuration file ~/.config/tz/conf.toml
Environment variable TZ_LIST
Command line arguments tz UTC

The local time zone is always displayed first.

Configuration File

Configs are read from $HOME/.config/tz/conf.toml.

Time zone ids should reference items from the standard tz database names. Alias them by providing your own name with the name key.

Sample configuration: example-conf.toml

Environment Variable

This method only supports setting time zones. Keymaps must be configured through the configuration file.

Specify time zones to display by setting the TZ_LIST environment variable. For example, to display your local time, the time in California, and the time Paris, set TZ_LIST to US/Pacific;Europe/Paris.

The TZ_LIST environment variable recognizes items from the standard tz database names, but you can alias these, using a special value: use the standard name followed by , and your alias. For example:

TZ_LIST="Europe/Paris,EMEA office;US/Central,US office"

If adding this to a shell configuration, remember to export it:

export TZ_LIST="Europe/Paris,EMEA office;US/Central,US office"

Building

You need a recent-ish release of go with modules support:

git clone https://github.com/oz/tz
cd tz
go build

Testing

go test -cover

Debug

DEBUG=1 tz # Logs will write to debug.log

Contributing

Please do file bugs, and feature requests. I am accepting patches too, those are the best, but please, open an issue first to discuss your changes. 😄

License

The GPL3 license.