kairos is a tool for converting between timezones. There are two primary use-cases.
-
Converting local system time into a different timezone:
$ kairos -d europe/paris Sat, 18 Jun 2022 03:19:58 CEST # -d sets the "destination" timezone # no "time string" means we read the local system time -
Converting a "time string" from one timezone to another:
$ kairos --date 2022-06-17 -s america/new_york 18:30 Sat, 18 Jun 2022 10:30:00 NZST # -s sets the "source" timezone # no dest means we convert to local time # i.e. 6:30 pm in New York on 2022-06-17 will be 10:30 am NZST (18 Jun 2022)We can also convert between two non-local timezones:
$ kairos -s america/new_york -d europe/paris 18:30 Mon, 17 Mar 2025 23:30:00 CET # no --date information means we use the current date, as determined by # the source i.e. 18:30 in nyc on the current date (2025-03-17).
The timezone names are based on the tz_database. See https://en.wikipedia.org/wiki/Tz_database for more information.
Arg: -c,--config PATH
Description: Path to toml config file. Can be used to define aliases for tz_database labels. See the examples directory for examples.
Examples:
$ kairos -c ./lib/exe/examples/config.toml -d la
Thu, 20 Apr 2023 22:25:37 PDT
Arg: --color (true | false)
Description: Determines if we color the --print-aliases output. Defaults to true.
Examples:
$ kairos -c ./lib/exe/examples/config.toml --print-aliases --color true
- la: america/los_angeles
- ny: america/new_york
- paris: europe/paris
- some_offset: +0700
- uk: europe/london
- zagreb: europe/zagreb
Arg: -f,--format-in FMT_STR
Description: Glibc-style format string for parsing the time string. Should not contain a timezone flag like %Z (see --src-tz) nor a date (see --date). Defaults to standard 12 and 24 hour formats e.g. 17:00, 0300, 4:30 pm, 2 am. See 'man date' for basic examples.
Examples:
# default formats
$ kairos 08:30
Tue, 18 Mar 2025 08:30:00 NZDT
$ kairos 0830
Tue, 18 Mar 2025 08:30:00 NZDT
$ kairos '8:30 am'
Tue, 18 Mar 2025 08:30:00 NZDT
$ kairos 8am
Tue, 18 Mar 2025 08:30:00 NZDT
# custom format
$ kairos -f "%I:%M %p" "08:00 pm"
Tue, 18 Mar 2025 20:00:00 NZDT
Arg: -o,--format-out (rfc822 | FMT_STR)
Description: Like --format-in except it applies to the output format only. If --format-out is not given we default to rfc822.
Examples:
# using implicit rfc822 format for output
$ kairos 08:30
Tue, 18 Mar 2025 08:30:00 NZDT
# overriding output format
$ kairos -o %H:%M:%S 08:30
08:30:00
Arg: --print-aliases
Description: Prints aliases from toml config.
Examples:
$ kairos -c ./lib/exe/examples/config.toml --print-aliases
- la: america/los_angeles
- ny: america/new_york
- paris: europe/paris
- some_offset: +0700
- uk: europe/london
- zagreb: europe/zagreb
Arg: --date YYYY-mm-dd
Description: Date in which to read the string. This option requires Time String. No date uses the current date, as determined by the source.
Examples:
$ kairos 08:30
Tue, 18 Mar 2025 08:30:00 NZDT
$ kairos --date 2022-04-10 -s america/new_york 08:30
Mon, 11 Apr 2022 00:30:00 NZST
Arg: TIME_STR
Description: This is the time string to parse. If none is given then we parse the local system time. To format the output, use --format-out.
Examples:
$ kairos
Tue, 18 Mar 2025 15:33:30 NZDT
$ kairos -s america/new_york 08:30
Tue, 18 Mar 2025 01:30:00 NZDT
Arg: -d,--dest-tz TZ
Description: This option allows one to convert the read timezone. Must be a tz database label or offset e.g. America/New_York, +1300. If none is given then we use the local system timezone.
Examples:
# use the local system timezone
$ kairos 08:30
Tue, 18 Mar 2025 08:30:00 NZDT
# using tz database name
$ kairos -d america/new_york 08:30
Mon, 17 Mar 2025 15:30:00 EDT
$ kairos -s america/new_york -d utc 08:30
Mon, 17 Mar 2025 12:30:00 UTC
$ kairos -d +0200 08:30
Mon, 17 Mar 2025 21:30:00 +0200
Arg: -s,--src-tz TZ
Description: Timezone in which to read the string. Must be a tz database label or offset e.g. America/New_York, +1300. If none is given then we use the local system timezone. This option requires Time String.
Examples:
# use the local system timezone
$ kairos 08:30
Tue, 18 Mar 2025 08:30:00 NZDT
# using tz database name
$ kairos -s america/new_york 08:30
Tue, 18 Mar 2025 01:30:00 NZDT
# use tz offset
$ kairos -s -13 08:30
Tue, 18 Mar 2025 10:30:00 NZDT
The releases page has binaries built for several platforms. If there are no binaries for your platform, it is possible to build kairos yourself.
If you have never built a haskell program before, Cabal is probably the best choice.
The easiest way to install these is generally ghcup.
The current "blessed" version is ghc-9.10.1.
Once you have cabal and ghc, kairos can be built with cabal build kairos or installed globally (i.e. ~/.local/bin/kairos) with cabal install kairos.
For further reproducibility, an optional freeze file can be used for the "blessed" compiler.
cabal build --project-file cabal.ghc<XYZ>.projectLike cabal and ghc, stack can be installed with ghcup.
Once you have stack, kairos can be built with stack build kairos or installed globally (i.e. ~/.local/bin/kairos) with stack install kairos.
Building with nix uses flakes. kairos can be built with nix build, which will compile and run the tests.
Because kairos is a flake, it can be built as part of a nix expression. For instance, if you want to add kairos to NixOS, your flake.nix should have:
# flake.nix
{
inputs.kairos.url = "github:tbidne/kairos/main";
}Then include this in the systemPackages:
# wherever your global packages are defined
{
environment.systemPackages = [
kairos.packages."${system}".default
];
}