when 3.3.2

Calculate and convert times across time zones and cities of significant population

when 🌐🕐

Scenario: Your favorite sporting event, concert, performance, conference, or symposium is happening in Ulan Bator, Mongolia and all you have is the time of the event relative to the location -- Feb 8, 3pm.

• What time is it currently in Ulan Bator?

  $ when --source "Ulan Bator"
  2025-02-07 03:08:58+0800 (+08, Asia/Ulaanbaatar) 038d05w (Ulan Bator, Ulaanbaatar, MN, Asia/Ulaanbaatar)[🌓 First Quarter]
  

• What time is the event in your local time (PST for me, currently)?

  $ when --source "Ulan Bator" Feb 8 3pm
  2025-02-07 23:00:00-0800 (PST, America/Los_Angeles) 038d05w [🌓 First Quarter]
  

• What time did it or will it occur at some other time, past or present?

  $ when --source "Ulan Bator" --offset +15d6h
  2025-02-22 09:18:01+0800 (+08, Asia/Ulaanbaatar) 053d07w (Ulan Bator, Ulaanbaatar, MN, Asia/Ulaanbaatar)[🌗 Last Quarter]
  

• What about for your friends in other locations around the world?

  $ when --exact --target London,GB  --source "Ulan Bator" Feb 8 3pm
  2025-02-08 07:00:00+0000 (GMT, Europe/London) 039d05w (London, England, GB, Europe/London)[🌓 First Quarter]
  

Table of Contents

• Features
• Installation
  • Database Installation
• Examples
  • Basic Usage
  • Formats
  • Timezones
  • Cities
  • Database Search
  • Database Aliases
  • Source Input Times
  • Targets
  • JSON
  • Holidays
  • Full Moons
• Formatting
• Configuration
  • Default TOML
• Complete CLI Options
• Development

Features

when can refer to source and target locations via the --source and --target specifiers.

• 🏙️ when can download a GeoNames cities database for referencing locations by city name
• 🕘 All IANA time zone definitions are available, as well as the most common time zone aliases (i.e.: EST => US/Eastern). For further reading, see Time Zones Aren’t Offsets – Offsets Aren’t Time Zones
• 🌖 Display current lunar state
• 🎉 List common holidays for a given country and/or year (US or configurable)
• 🌝 Show dates for full moons
• ⚙️ Extensive configuration options for results
• 📄 JSON output
• 🗓️ Allow for past and future offsets
• 🔎 96% test code coverage

Installation

Requirements

Python 3.10+ or pipx

• Install from PyPI:

  $ pip install when
  

• Install using pipx:

  $ pipx install when
  

  or:

  $ pipx install git+https://github.com/dakrauth/when.git
  

• Install from GitHub source

  git clone [e-mail]:dakrauth/when.git
  python -m pip install --require-virtualenv when/
  

  See Development below for detailed instructions for working on when below.

Note

Once installed, if you wish to utilize when's full capabilities, you should install the GeoNames cities database as describe next.

Database installation

To access city names, you need to install the cities database after installing the when application:

$ when --db <SIZE> [options]

Use the <SIZE> option to specify a database download size. For detailed info, see the GeoNames ReadMe.

<SIZE> options must be one of the following:

• sm: ~2.9M download, ~2M DB
  • All country capitals
  • Cities with population > 15,000
• md: default ~4.8M download, ~3.1M DB; same as sm, plus:
  • Seat of first-order admin division, i.e. US state
  • Cities with population > 5,000
• lg: ~9.5M download, ~5.8M DB; same as md, plus:
  • seat of admin division down to third level (counties)
  • cities with population > 1,000
• xl ~12.1M download, ~7.2M DB; same as lg, plus:
  • seat of admin division down to fourth order
  • cities with population > 500

Additional options are:

• --db-pop: Filter non-admin division seats providing a minimum city population size
• --force: Force an existing database to be overwritten

Examples

Basic Usage

Note

In the following examples, please the xl database has been installed, and that the system TZ is configured for the West coast of the NW United States.

The most basic form of when will show the following output, based upon the system's date and timezone configuration:

$ when
2025-02-04 17:38:10-0800 (PST, America/Los_Angeles) 035d05w [🌒 Waxing Crescent]

Formats

The default format of the output is structured as:

<ISO 8601 timestamp> (<TZ abbreviation>, <TZ name>) <Day-if-year>d<Week-of-year>w [<Lunar information>]

The default format configuration is specified by the string '%F %T%z (%Z%!Z) %jd%Ww %!C[%!l]'.

Output formatting can be configured in multiple ways:

• Creating a .whenrc.toml configuration file (see Configuration below)

• Use the --format option and use formatting pattern (see Formatting below):

  $ when --format '%a %b %d %Y %T %!c' --source Seattle
  Tue Feb 04 2025 17:40:11 Seattle, Washington, US, America/Los_Angeles
  

• Use one of the pre-configured, named formats such as iso and rfc2822:

  $ when --format iso
  2025-02-05T16:31:22-0800
  
  $ when --format rfc2822
  Wed, 05 Feb 2025 16:31:30 -0800
  

• Set a WHENFORMAT env variable, which can specified in your with your shell config (such as .bash_prole or .zshrc), or prepended to the command line command, for instance:

  $ WHENFORMAT='%a %b %d %Y %T %!c' when --source Seattle
  Tue Feb 04 2025 17:40:09 Seattle, Washington, US, America/Los_Angeles
  

Timezones

Source (and target) locations can also be specified by IANA timezone names or aliases:

$ when --source CST
2025-02-04 20:01:43-0600 (CST, Central Standard Time) 035d05w [🌒 Waxing Crescent]
2025-02-05 06:01:43+0400 (+04, Caucasus Standard Time) 036d05w [🌓 First Quarter]
2025-02-05 10:01:43+0800 (CST, China Standard Time) 036d05w [🌓 First Quarter]
2025-02-04 21:01:43-0500 (CST, Cuba Standard Time) 035d05w [🌒 Waxing Crescent]

Cities

Searching by city can return numerous results, since by default the database is queried looking for matches containing the search string:

$ when --source Paris
2025-02-05 04:04:44+0200 (EET, Europe/Athens) 036d05w (Kyparissía (Kyparissia), Peloponnese, GR, Europe/Athens)[🌓 First Quarter]
2025-02-05 02:04:44+0000 (GMT, Europe/London) 036d05w (Whiteparish, England, GB, Europe/London)[🌓 First Quarter]
2025-02-05 03:04:44+0100 (CET, Europe/Paris) 036d05w (Villeparisis, Île-de-France, FR, Europe/Paris)[🌓 First Quarter]
2025-02-05 03:04:44+0100 (CET, Europe/Paris) 036d05w (Seyssinet-Pariset, Auvergne-Rhône-Alpes, FR, Europe/Paris)[🌓 First Quarter]
2025-02-05 03:04:44+0100 (CET, Europe/Paris) 036d05w (Paris, Île-de-France, FR, Europe/Paris)[🌓 First Quarter]
2025-02-05 03:04:44+0100 (CET, Europe/Paris) 036d05w (Cormeilles-en-Parisis, Île-de-France, FR, Europe/Paris)[🌓 First Quarter]
...
2025-02-04 20:04:44-0600 (CST, America/Chicago) 035d05w (Paris, Texas, US, America/Chicago)[🌒 Waxing Crescent]
2025-02-04 21:04:44-0500 (EST, America/New_York) 035d05w (Paris, Maine, US, America/New_York)[🌒 Waxing Crescent]
2025-02-04 19:04:44-0700 (MST, America/Boise) 035d05w (Paris, Idaho, US, America/Boise)[🌒 Waxing Crescent]
2025-02-04 21:04:44-0500 (EST, America/Toronto) 035d05w (Paris, Ontario, CA, America/Toronto)[🌒 Waxing Crescent]
2025-02-05 09:04:44+0700 (WIB, Asia/Jakarta) 036d05w (Danauparis, Aceh, ID, Asia/Jakarta)[🌓 First Quarter]

Use --exact to restrict the results to a full match on the respective columns within the database:

$ when --exact --source paris
2025-02-05 03:09:24+0100 (CET, Europe/Paris) 036d05w (Paris, Île-de-France, FR, Europe/Paris)[🌓 First Quarter]
2025-02-04 21:09:24-0500 (EST, America/Panama) 035d05w (París (Paris), Herrera Province, PA, America/Panama)[🌒 Waxing Crescent]
2025-02-04 20:09:24-0600 (CST, America/Chicago) 035d05w (Paris, Illinois, US, America/Chicago)[🌒 Waxing Crescent]
2025-02-04 21:09:24-0500 (EST, America/New_York) 035d05w (Paris, Kentucky, US, America/New_York)[🌒 Waxing Crescent]
2025-02-04 20:09:24-0600 (CST, America/Chicago) 035d05w (Paris, Missouri, US, America/Chicago)[🌒 Waxing Crescent]
2025-02-04 20:09:24-0600 (CST, America/Chicago) 035d05w (Paris, Tennessee, US, America/Chicago)[🌒 Waxing Crescent]
2025-02-04 20:09:24-0600 (CST, America/Chicago) 035d05w (Paris, Texas, US, America/Chicago)[🌒 Waxing Crescent]
2025-02-04 21:09:24-0500 (EST, America/New_York) 035d05w (Paris, Maine, US, America/New_York)[🌒 Waxing Crescent]
2025-02-04 19:09:24-0700 (MST, America/Boise) 035d05w (Paris, Idaho, US, America/Boise)[🌒 Waxing Crescent]
2025-02-04 21:09:24-0500 (EST, America/Toronto) 035d05w (Paris, Ontario, CA, America/Toronto)[🌒 Waxing Crescent]

You can also filter by country:

$ when --exact --source paris,fr
2025-02-05 03:10:17+0100 (CET, Europe/Paris) 036d05w (Paris, Île-de-France, FR, Europe/Paris)[🌓 First Quarter]

Or by subnational region (e.g. a state in the US):

$ when --exact --source paris,maine,us
2025-02-04 21:11:13-0500 (EST, America/New_York) 035d05w (Paris, Maine, US, America/New_York)[🌒 Waxing Crescent]

Database Search

Use --search to search the GeoNames database, once installed:

$ when --search paris
 259782 Kyparissía (Kyparissia), Peloponnese, GR, Europe/Athens
2634065 Whiteparish, England, GB, Europe/London
2968496 Villeparisis, Île-de-France, FR, Europe/Paris
2974645 Seyssinet-Pariset, Auvergne-Rhône-Alpes, FR, Europe/Paris
2988507 Paris, Île-de-France, FR, Europe/Paris
3023645 Cormeilles-en-Parisis, Île-de-France, FR, Europe/Paris
3703358 París (Paris), Herrera Province, PA, America/Panama
3725276 Fond Parisien, Ouest, HT, America/Port-au-Prince
4246659 Paris, Illinois, US, America/Chicago
4303602 Paris, Kentucky, US, America/New_York
4402452 Paris, Missouri, US, America/Chicago
4647963 Paris, Tennessee, US, America/Chicago
4717560 Paris, Texas, US, America/Chicago
4974617 Paris, Maine, US, America/New_York
5603240 Paris, Idaho, US, America/Boise
6942553 Paris, Ontario, CA, America/Toronto
8571689 Danauparis, Aceh, ID, Asia/Jakarta

Results of a database search are formated as:

<GeoName ID> <Name> [(<ASCII Name>)], <Subregion>, <Country code>, <Timezone info>

The search feature checks for containment by default, but exact filtering can be useful, as discussed above:

$ when --search paris --exact
2988507 Paris, Île-de-France, FR, Europe/Paris
3703358 París (Paris), Herrera Province, PA, America/Panama
4246659 Paris, Illinois, US, America/Chicago
4303602 Paris, Kentucky, US, America/New_York
4402452 Paris, Missouri, US, America/Chicago
4647963 Paris, Tennessee, US, America/Chicago
4717560 Paris, Texas, US, America/Chicago
4974617 Paris, Maine, US, America/New_York
5603240 Paris, Idaho, US, America/Boise
6942553 Paris, Ontario, CA, America/Toronto

Database Aliases

Use --alias to add aliases for easier search. For instance, consider the following:

$ when --search "New York City"
5128581 New York City, New York, US, America/New_York

If you are checking New York City often, it can be a pain to type out; however, in the result above, we see that New York City has a GeoNames ID of 5128581. You can pass along with the --alias option along with another name that you would like to use instead:

$ when --alias 5128581 NYC
$ when --source NYC
2025-02-04 21:33:33-0500 (EST, America/New_York) 035d05w (New York City, New York, US, America/New_York)[🌒 Waxing Crescent]

A complete list of aliases can be shown:

$ when --aliases
NYC: New York City | New York | US | America/New_York

Source Input Times

If we know a given time in a specific city or timezone, we can have that converted to our current timezone:

$ when --source Honolulu 17:00
2025-02-04 19:00:00-0800 (PST, America/Los_Angeles) 035d05w [🌒 Waxing Crescent]
2025-02-04 19:00:00-0800 (PST, America/Los_Angeles) 035d05w [🌒 Waxing Crescent]

But, wait! Why are there two results?

Doing a DB search will reveal that there are two entries that could match Honolulu:

$ when --search Honolulu
5856195 Honolulu, Hawaii, US, Pacific/Honolulu
7315245 East Honolulu, Hawaii, US, Pacific/Honolulu

In this case, --exact will show only one result:

$ when --exact --source Honolulu 17:00
2025-02-04 19:00:00-0800 (PST, America/Los_Angeles) 035d05w [🌒 Waxing Crescent]

The timestamp string parsing is provided by python-dateutil and is very generous:

$ when --exact --source Honolulu March 7, 1945 5pm
1945-03-07 19:30:00-0700 (PWT, America/Los_Angeles) 066d10w [🌘 Waning Crescent]

Targets

By default, if the --target option is not specified, it will default to the local machine's date/time/timezone. However, you can specify another target. For instance, if you are traveling to New York City, and you wish to see when an event occurring in Olso, Norway will be, relatively speaking:

$ when --exact --target NYC --source Oslo June 2 6pm
2025-06-02 12:00:00-0400 (EDT, America/New_York) 153d22w (New York City, New York, US, America/New_York)[🌒 Waxing Crescent]

Notice that details regarding the source (Oslo) are absent. Adding the --group option will remedy that:

$ when --group --exact --target NYC --source Oslo June 2 6pm
2025-06-02 12:00:00-0400 (EDT, America/New_York) 153d22w (New York City, New York, US, America/New_York)[🌒 Waxing Crescent]
 ↳ @2025-06-02 18:00:00+0200 (CEST, Europe/Oslo) 153d22w (Oslo, NO, Europe/Oslo)[🌒 Waxing Crescent]

$ when --exact --source paris,fr --target paris,us --group 21:00
2025-02-04 14:00:00-0600 (CST, America/Chicago) 035d05w (Paris, Illinois, US, America/Chicago)[🌒 Waxing Crescent]
 ↳ @2025-02-04 21:00:00+0100 (CET, Europe/Paris) 035d05w (Paris, Île-de-France, FR, Europe/Paris)[🌒 Waxing Crescent]
...
 ↳ @2025-02-04 21:00:00+0100 (CET, Europe/Paris) 035d05w (Paris, Île-de-France, FR, Europe/Paris)[🌒 Waxing Crescent]
2025-02-04 13:00:00-0700 (MST, America/Boise) 035d05w (Paris, Idaho, US, America/Boise)[🌒 Waxing Crescent]
 ↳ @2025-02-04 21:00:00+0100 (CET, Europe/Paris) 035d05w (Paris, Île-de-France, FR, Europe/Paris)[🌒 Waxing Crescent]

JSON

Output can be formatted as JSON, e.g., for use in API's:

$ when --exact --json --source Seattle --target Honolulu
[
  {
    "iso": "2025-02-04T17:12:18-10:00",
    "lunar": {
      "emoji": "\ud83c\udf12",
      "phase": "Waxing Crescent",
      "age": 6.545
    },
    "zone": {
      "name": "Pacific/Honolulu",
      "city": {
        "name": "Honolulu",
        "ascii": "Honolulu",
        "country": "US",
        "tz": "Pacific/Honolulu",
        "subnational": "Hawaii"
      },
      "utcoffset": [-10, 0]
    },
    "source": {
      "iso": "2025-02-04T19:12:18-08:00",
      "lunar": {
        "emoji": "\ud83c\udf12",
        "phase": "Waxing Crescent",
        "age": 6.545
      },
      "zone": {
        "name": "America/Los_Angeles",
        "city": {
          "name": "Seattle",
          "ascii": "Seattle",
          "country": "US",
          "tz": "America/Los_Angeles",
          "subnational": "Washington"
        },
        "utcoffset": [-8, 0]
      },
      "source": null,
      "offset": null
    },
    "offset": null
  }
]

Holidays

when comes pre-configured with most US holidays:

$ when --holidays US
New Year's Day.....Wed, Jan 01 2025 ( -35 days) [🌑 New Moon]
MLK Day............Mon, Jan 20 2025 ( -16 days) [🌖 Waning Gibbous]
Valentine's Day....Fri, Feb 14 2025 (   9 days) [🌕 Full Moon]
Presidents' Day....Mon, Feb 17 2025 (  12 days) [🌖 Waning Gibbous]
Mardi Gras.........Tue, Mar 04 2025 (  27 days) [🌒 Waxing Crescent]
Ash Wednesday......Wed, Mar 05 2025 (  28 days) [🌒 Waxing Crescent]
St. Patrick's Day..Mon, Mar 17 2025 (  40 days) [🌕 Full Moon]
Palm Sunday........Sun, Apr 13 2025 (  67 days) [🌕 Full Moon]
Good Friday........Fri, Apr 18 2025 (  72 days) [🌖 Waning Gibbous]
Easter.............Sun, Apr 20 2025 (  74 days) [🌗 Last Quarter]
Mother's Day.......Sun, May 11 2025 (  95 days) [🌔 Waxing Gibbous]
Memorial Day.......Mon, May 26 2025 ( 110 days) [🌘 Waning Crescent]
Father's Day.......Sun, Jun 15 2025 ( 130 days) [🌖 Waning Gibbous]
Juneteenth.........Thu, Jun 19 2025 ( 134 days) [🌗 Last Quarter]
Independence Day...Fri, Jul 04 2025 ( 149 days) [🌓 First Quarter]
Labor..............Mon, Sep 01 2025 ( 208 days) [🌓 First Quarter]
Columbus Day.......Mon, Oct 13 2025 ( 250 days) [🌖 Waning Gibbous]
Halloween..........Fri, Oct 31 2025 ( 268 days) [🌓 First Quarter]
Veterans Day.......Tue, Nov 11 2025 ( 279 days) [🌖 Waning Gibbous]
Thanksgiving.......Thu, Nov 27 2025 ( 295 days) [🌒 Waxing Crescent]
Christmas..........Thu, Dec 25 2025 ( 323 days) [🌒 Waxing Crescent]

You can specify a year as well:

$ when --holidays US 2026
New Year's Day.....Thu, Jan 01 2026 ( 330 days) [🌔 Waxing Gibbous]
MLK Day............Mon, Jan 19 2026 ( 348 days) [🌑 New Moon]
Valentine's Day....Sat, Feb 14 2026 ( 374 days) [🌘 Waning Crescent]
...
Veterans Day.......Wed, Nov 11 2026 ( 644 days) [🌑 New Moon]
Thanksgiving.......Thu, Nov 26 2026 ( 659 days) [🌕 Full Moon]
Christmas..........Fri, Dec 25 2026 ( 688 days) [🌕 Full Moon]

Full Moons

$ when --fullmoon
2025-01-13
2025-02-12
2025-03-14
2025-04-12
2025-05-12
2025-06-10
2025-07-10
2025-08-08
2025-09-06
2025-10-06
2025-11-05
2025-12-04

You can specify next, prev, or use YYY[-MM]:

$ when --fullmoon next
2025-02-12

$ when --fullmoon prev
2025-01-13

$ when --fullmoon 2026
2026-01-03
2026-02-01
...
2026-11-23
2026-12-23

$ when --fullmoon 2026-01
2026-01-03

Formatting

Complete listing of specifiers:

• %a: Abbreviated weekday name, Thu *
• %A: Full weekday name, Thursday *
• %b: Abbreviated month name, Aug *
• %B: Full month name, August *
• %c: Date and time representation, Thu Aug 23 14:55:02 2001 *
• %C: Year divided by 100 and truncated to integer (00-99), 20 †
• %d: Day of the month, zero-padded (01-31), 23
• %D: Short MM/DD/YY date, equivalent to %m/%d/%y, 08/23/01 †
• %e: Day of the month, space-padded ( 1-31), 23 †
• %F: Short YYYY-MM-DD date, equivalent to %Y-%m-%d, 2001-08-23 †
• %g: Week-based year, last two digits (00-99), 01 †
• %G: Week-based year, 2001 †
• %h: Abbreviated month name (same as %b), Aug †*
• %H: Hour in 24h format (00-23), 14
• %I: Hour in 12h format (01-12), 02
• %j: Day of the year (001-366), 235
• %m: Month as a decimal number (01-12), 08
• %M: Minute (00-59), 55
• %n: New-line character, \\n †
• %p: AM or PM designation, PM
• %r: 12-hour clock time, 02:55:02 pm †*
• %R: 24-hour HH:MM time, equivalent to %H:%M, 14:55 †
• %S: Second (00-61), 02
• %t: Horizontal-tab character, \\t †
• %T: ISO 8601 time format (HH:MM:SS), equivalent to %H:%M:%S, 14:55:02 †
• %u: ISO 8601 weekday as number with Monday as 1 (1-7), 4 †
• %U: Week number with the first Sunday as the first day of week one (00-53), 33
• %V: ISO 8601 week number (01-53), 34 †
• %w: Weekday as a decimal number with Sunday as 0 (0-6), 4
• %W: Week number with the first Monday as the first day of week one (00-53), 34
• %x: Date representation, 08/23/01 *
• %X: Time representation, 14:55:02 *
• %y: Year, last two digits (00-99), 01
• %Y: Year, 2001
• %z: ISO 8601 offset from UTC in timezone (1 minute=1, 1 hour=100), no characters if timezone cannot be determined +100
• %Z: Locale timezone name or abbreviation, no characters if timezone cannot be determined CDT *
• %%: A % sign, %
• %!z: When timezone name, US/New_York ‡
• %!Z: When timezone name, using conditional format in settings, US/New_York ‡
• %!c: City name, Honolulu, Hawaii, US ‡
• %!C: City name, using conditional format in settings, Honolulu, Hawaii, US ‡
• %!l: Lunar phase emoji, 🌖 ‡

† C99 extension | ‡ when extension | * Locale-dependent

Configuration

Configuration is done via TOML format and can be overridden (overlayed, actually) by creating a .whenrc.toml in either the local directory from which when is executed, or from ~/.whenrc.toml.

To show the current configuration status, you can do:

$ when --config

You can refer to Default TOML below for all configuration values.

To begin, create the file:

$ cat << EOF > .whenrc.toml
[formats.named]
foo = "%x %X"
bar = "%!l"

[formats.source]
grouped = " ➡️ From "
EOF

Now, verify the configuration by doing:

$ when --config

At the top of the output there should be a line similar to the following:

# Read from /path/to/pwd/.whenrc.toml

Let's see the result:

$ when --format foo --group --source seattle --target "New York City"
02/05/25 19:02:12
 ➡️ From 02/05/25 16:02:12

$ when --format bar --source seattle
🌓 First Quarter

Default TOML

[calendar]
months = [ "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
days = [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]

[holidays]
format = "%a, %b %d %Y"

[lunar]
phases = [ "New Moon", "Waxing Crescent", "First Quarter", "Waxing Gibbous", "Full Moon", "Waning Gibbous", "Last Quarter", "Waning Crescent"]
emojis = "🌑🌒🌓🌔🌕🌖🌗🌘"
format = "%a, %b %d %Y"

[holidays.US]
Easter = "Easter +0"
"Ash Wednesday" = "Easter -46"
"Mardi Gras" = "Easter -47"
"Palm Sunday" = "Easter -7"
"Good Friday" = "Easter -2"
"Memorial Day" = "Last Mon in May"
"MLK Day" = "3rd Mon in Jan"
"Presidents' Day" = "3rd Mon in Feb"
"Mother's Day" = "2nd Sun in May"
"Father's Day" = "3rd Sun in Jun"
Labor = "1st Mon in Sep"
"Columbus Day" = "2nd Mon in Oct"
Thanksgiving = "4th Thu in Nov"
"New Year's Day" = "Jan 1"
"Valentine's Day" = "Feb 14"
"St. Patrick's Day" = "Mar 17"
Juneteenth = "Jun 19"
"Independence Day" = "Jul 4"
Halloween = "Oct 31"
"Veterans Day" = "Nov 11"
Christmas = "Dec 25"

[formats.named]
default = "%F %T%z (%Z%!Z) %jd%Ww %!C[%!l]"
rfc2822 = "%a, %d %b %Y %H:%M:%S %z"
iso = "%Y-%m-%dT%H:%M:%S%z"

[formats.conditional]
Z = ", {}"
C = "({})"

[formats.source]
grouped = " ↳ @"

Complete CLI Options

usage: when [--delta {long,short}] [--offset [+-]?(\d+wdhm)+] [--prefix] [-s SOURCE] [-t TARGET] [-f FORMAT] [-g] [--all]
            [--holidays COUNTRY_CODE] [-v] [-V] [--json] [--config] [--force] [--search] [--exact] [--alias ALIAS]
            [--aliases] [--db DB] [--db-pop DB_POP] [--tz-alias] [--fullmoon] [-h]
            [timestr ...]

Convert times to and from time zones or cities

positional arguments:
  timestr               Timestamp to parse, defaults to local time

options:
  --delta {long,short}  Show the delta to the given timestamp
  --offset [+-]?(\d+wdhm)+
                        Show the difference from a given offset
  --prefix              Show when's directory
  -s SOURCE, --source SOURCE
                        Timezone / city to convert the timestr from, defaulting to local time
  -t TARGET, --target TARGET
                        Timezone / city to convert the timestr to (globbing patterns allowed, can be comma delimited),
                        defaulting to local time
  -f FORMAT, --format FORMAT
                        Output formatting. Additional formats can be shown using the -v option with -h
  -g, --group           Group sources together under same target results
  --all                 Show times in all common timezones
  --holidays COUNTRY_CODE
                        Show holidays for given country code.
  -v, --verbosity       Verbosity (-v, -vv, etc). Use -v to show `when` extension detailed help
  -V, --version         show program's version number and exit
  --json                Output results in nicely formatted JSON
  --config              Show current configuration settings
  --force               Force an existing database to be overwritten
  --search              Search database for the given city
  --exact               DB searches must be exact
  --alias ALIAS         Create a new alias from the city id
  --aliases             Show all DB aliases
  --db DB               Create cities database from Geonames file. Can be one of 'xl' ('xlarge'), 'lg' ('large'), 'md'
                        ('medium'), 'sm' ('small')
  --db-pop DB_POP       City population minimum.
  --tz-alias            Search for a time zone alias
  --fullmoon            Show full moon(s) for given year or month. Can be in the format of: 'next' | 'prev' | YYYY[-MM]
  -h, --help            Show helpful usage information

Use -v option for details

Development

Requires Python 3.10+ and just for convenience.

$ git clone [e-mail]:dakrauth/when.git
$ cd when
$ just

Note:

just is a shortcut for just --help

Set up dev env:

$ just init

Test, and code coverage:

$ just test
$ just cov

Only run a test matching matching a given substring:

$ just test -k test_sometest

Run the when command with any arguments:

$ just when --source poulsbo

Or, start an interactive session:

$ . ./dev/venv/bin/activate
$ when --help