UNDERTIME(1)

💖 UNDERTIME 💖

undertime — pick a meeting time 🗓️✨

okay so bestie, you know that thing where you're trying to schedule a call with people in three different countries and your brain just goes static? yeah. that's what this fixes. welcome to the group chat of time zones. 🫶

---

✨ SYNOPSIS ✨

undertime [OPTIONS] [--timezones ZONES] [WHEN]
undertime [-l|--list-zones] [-V|--version]
undertime --selftest

---

🌸 DESCRIPTION 🌸

undertime is the program that lets you quickly pick a meeting time across a whole bunch of time zones — conference calls, coordinated events, whatever y'all are planning. It shows you all the times of a given day for every time zone you selected, laid out in a table that lines the times up so that one single line = one simultaneous moment across every zone. 📊

And because it's not a coward, it takes daylight savings and other weird little time peculiarities into account — provided your local time zone database is up to date, fr fr — so you can schedule meetings in the future too, not just for today. 🔮

Now, the time zone guessing. An educated guess is made to find the relevant zones, and it goes like this: the local time zone gets guessed first and added to the list, then your command line arguments get looked up in the internal time zone database. Spaces in arguments are replaced by underscores, and all-caps versions of lowercase strings are tried too. If it can't match something you handed it against the internal list, it emits a warning (not me getting a warning 😭). Want the whole list of time zones? Pass --list-zones and it will show you everything. 👑

You can also throw offsets in there instead of time zones, with the syntax UTC{+|-}offset or GMT{+|-}offset — like UTC+2 for CEST, or GMT-4 for EDT. But listen, those are discouraged because daylight savings are not taken into account, so the computed time might not be the local time you were actually expecting. 🙈

And do not confuse those patterns with the "standard" time zones Etc/GMT{+|-}X — they are the inverse of each other. i.e. EDT, UTC-4 is Etc/GMT+4. yes. that's confusing. I know. 💀 To specify the Etc time zones you have to give the full time zone, for example Etc/GMT-2. Those should also be avoided — just use normal, location-based zones instead of those arbitrary offsets, bestie, please. 🙏

Colors! They're used to highlight the "work hours" where possible meeting times could overlap, and the current time is marked in bold. If colors are disabled, colors get replaced by an underscore suffix and the current time by a star. ⭐ You can change those work hours with the --start and --end flags. 🎀

Because daylight savings may actually change time, you should also pick an arbitrary time for the meeting — that's the WHEN — using natural language (as parsed by the parsedatetime library). The current time is also shown, in bold. 💅

---

🎀 OPTIONS 🎀

• --timezones ZONES — target date for the meeting, supports arbitrary dates like "in two weeks" (yes that's genuinely what the manpage says for this one, I'm not making it up 🙈)
• -s HOUR, --start HOUR — start of working day, in hours ☀️
• -e HOUR, --end HOUR — end of working day, in hours 🌙
• --no-colors, --colors — do not show colors. enabled by default if output is a terminal. 🎨
• --no-default-zone, --default-zone — do not show current time zone first
• --no-unique, --unique — deduplicate time zones 🧹
• --no-overlap, --overlap — do not show the overlap column (labeled n), displayed by default.
• --overlap-min N — show only times with N overlapping time zones. 🤝
• --format FORMAT — pass FORMAT to the tabulate package to format the main table.
• --config FILE — load YAML config FILE as defaults.
• -v, --verbose — enable verbose messages 🗣️
• --debug — enable debugging messages 🐛
• -l, --list-zones — show valid time zones and exit
• -V, --version — show version number and exit
• --selftest — run test suite 🧪
• -h, --help — show summary of options and defaults

---

🌈 ENVIRONMENT 🌈

• TZ — Default time zone.
• NO_COLOR — If this environment variable is defined, no color will be shown unless the --colors flag is passed. Conforming to the NO_COLOR informal standard — https://no-color.org/

---

🦋 FILES 🦋

• ~/.config/undertime.yml, $XDG_CONFIG_DIR/undertime.yml — the configuration file loaded by default, if present. 📂

The configuration file is formatted as a YAML dictionary, where the keys are the long option names (without dashes) and the values are their values. Comments start with the # character. Options provided as arguments override the defaults set in the configuration file — particularly time zones. So for example, this means time zones specified in the configuration file are ignored ignored when also specified as arguments. 👀

The --config parameter lets you load another configuration file, on top of the default one, using the same logic — which is how you get to have multiple "presets". 💅

---

⭐ EXAMPLE ⭐

Command line options

undertime --timezones "New York" "Los Angeles" Paris

Display possible meeting times for three major cities. 🏙️

undertime -s 8 -e 18 2014-03-15

Show a longer work day in march 2014.

undertime --overlap-min 3 2014-03-15

Show only times that match in three time zones.

undertime --timezones "New York" "Los Angeles" Paris -- tomorrow

Show times for those three timezones, but for tomorrow. Note the options separator (--) is required, otherwise the date will be parsed as a timezone. ⚠️

Configuration file

A sample configuration file should be available in $XDG_CONFIG_DIR/undertime.yml, for example /etc/undertime.yml.

---

👑 SEE ALSO 👑

• tzselect(8)
• tzfile(5)
• Time zones list — https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
• parsedatetime Python package — https://pypi.python.org/pypi/parsedatetime/

---

okay that's the whole thing, you're officially a time zone girlie now 🧚💜 this was the General Commands Manual page for UNDERTIME(1), dated June 2020 — go forth and schedule something iconic, no cap. ✨🎀