gotz

gotz - a simple CLI timezone info tool.

Installation

Directly via Go

go install github.com/merschformann/gotz@latest

Binary

Simply download the binary of the latest release (look for gotz_*_OS_ARCH - darwin is macOS), unpack the gotz binary and put it in a folder in your $PATH.

Homebrew

brew tap merschformann/gotz # only once
brew install gotz

Usage

Show current time:

gotz

Show arbitrary time:

gotz 21

Show arbitrary time using different timezone (index based):

gotz 15@2

Time can be one of the following formats:

15
15:04
15:04:05
3:04pm
3:04:05pm
3pm
1504
150405
2006-01-02T15:04:05

Use live mode to continuously update the time (exit via q, esc or ctrl+c). Activate once via:

gotz --live true

(above also uses option --inline false; for styling see customization below)

Basic configuration

Set the timezones to be used by default:

gotz --timezones "Office:America/New_York,Home:Europe/Berlin"

(lookup timezones in the timezones wiki page - TZ identifier column)

Set 12-hour format:

gotz --hours12 true

Customization

The configuration is stored in $XDG_CONFIG_HOME/gotz/config.json (usually ~/.config/gotz/config.json on most systems). It can be configured directly or via the arguments of the gotz command (see gotz --help). The configuration attributes are described in the following example:

{
    // Tracks the version of the configuration file (automatically written on creation)
    "config_version": "1.0",
    // Configures the timezones to be shown
    "timezones": [
        // Timezones have a name (Name) and timezone code (TZ)
        { "Name": "Office", "TZ": "America/New_York" },
        { "Name": "Home", "TZ": "Europe/Berlin" },
    ],
    // Configures the style of the plot
    "style": {
        // Select symbols to use for the time blocks
        // (one of 'mono', 'rectangles', 'blocks', 'sun-moon' or 'custom')
        "symbols": "mono",
        // Define custom symbols (used if 'symbols' is 'custom')
        // Each symbol is used from its start time (hour in day as int) until the next symbol
        "custom_symbols": [
            { "Start": 6, "Symbol": "▓" },
            { "Start": 8, "Symbol": "█" },
            { "Start": 18, "Symbol": "▓" },
            { "Start": 22, "Symbol": "░" }
        ],
        // Indicates whether to use coloring at all
        "colorize": true,
        // Configures how the day is segmented
        "day_segments": {
            // Hour of the morning to start (0-23)
            "morning": 6,
            // Hour of the day (business hours / main time) to start (0-23)
            "day": 8,
            // Hour of the evening to start (0-23)
            "evening": 18,
            // Hour of the night to start (0-23)
            "night": 22
        },
        // Defines the colors for the segments
        // Static mode colors can be one of:
        //  - >simple< color names like `red`, `green`, `cyan`, etc.
        //  - terminal color codes like `\u001b[34m`, `\u001b[32m`, etc.
        //  - hex codes like #DC143C, #00ff00, etc. (if true color is supported)
        // Dynamic mode colors 
        //  - tcell color names like crimson, green, etc.
        //  - hex codes like #DC143C, #00ff00, etc.
        // Note that some symbols are not fully opaque and will show the background color, thus,
        //   making the color appear darker (or lighter for white/light terminal backgrounds)
        "coloring": {
            // Color of the morning segment for static mode
            "StaticColorMorning": "#EC3620",
            // Color of the morning segment for static mode
            "StaticColorDay": "#F9C748",
            // Color of the morning segment for static mode
            "StaticColorEvening": "#EC3620",
            // Color of the morning segment for static mode
            "StaticColorNight": "#030D4D",
            // Foreground color overriding default for static mode (optional)
            "StaticColorForeground": "",
            // Color of the morning segment for dynamic mode
            "DynamicColorMorning": "#419AA8",
            // Color of the day segment for dynamic mode
            "DynamicColorDay": "#FFFFFF",
            // Color of the evening segment for dynamic mode
            "DynamicColorEvening": "#419AA8",
            // Color of the night segment for dynamic mode
            "DynamicColorNight": "#09293F",
            // Foreground color overriding default for dynamic mode (optional)
            "DynamicColorForeground": "",
            // Background color overriding default for dynamic mode (optional)
            "DynamicColorBackground": ""
        }
    },
    // Indicates whether to plot tics for the local time
    "tics": false,
    // Indicates whether to stretch across the full terminal width (causes inhomogeneous segment lengths)
    "stretch": true,
    // Inline indicates whether location and time info will be plotted on one line with the bars.
    "inline": true,
    // Indicates whether to colorize the blocks
    "hours12": false,
    // Indicates whether to use 12-hour format
    "live": false,
    // Selects the sorting of the timezones
    // (one of 'name' - lexicographically, 'offset' - TZ offset, 'none' - user defined)
    "sorting": "name",
    // Indicates whether to keep the local timezone on top when using sorting
    "sort_local_top": true
}

Why?

Working in an international team is a lot of fun, but comes with the challenge of having to deal with timezones. Since I am not good at computing them quickly in my head, I decided to write a simple CLI tool to help me out. I hope it can be useful for other people as well. Thanks for the inspiration @sebas!