Biff is a command line datetime Swiss army knife

A command line tool for datetime arithmetic, parsing, formatting and more.

Dual-licensed under MIT or the UNLICENSE.

Please see the CHANGELOG for a release history.

The user guide should be your first stop for understanding the high level concepts that Biff deals with. Otherwise, consult biff --help or biff <sub-command> --help for more specific details.

Alternatively, there is a comparison between other similar tools that might give you a quick sense of what Biff is like.

Print the current time:

Print the current time in a format of your choosing:

Print multiple relative times in one command:

Print the current time in another time zone, and round it the nearest 15 minute increment:

Add a duration to the current time:

Find the duration since a date in the past and round it to the desired precision:

Find timestamps in a log file and reformat them into your local time in place:

Generate a sequence of the next 5 days that are Monday, Wednesday or Friday at a specific time, and then format them in your locale:

Print every day remaining in the current month:

Find the last weekday in each of the next 12 months and print them in a succinct format:

Or print the second Tuesday of each month until the end of the year:

Finally, this command will get the last commit date on each file in a git repository, sort them in ascending order, format the datetime to a fixed-width format and then print the data in a tabular format:

To see more examples, check out the user guide or the comparison between Biff and other datetime command line tools.

The binary name for Biff is biff. It is also on crates.io under the name biff-datetime-cli.

Archives of precompiled binaries for Biff are available for Windows, macOS and Linux. Linux and Windows binaries are static executables.

Alternatively, if you're a Rust programmer, Biff can be installed with cargo. Note that the binary may be bigger than expected because it contains debug symbols. This is intentional. To remove debug symbols and therefore reduce the file size, run strip on the binary.

Or, if you want locale support (which is enabled in the binaries distributed on GitHub), then install with the locale feature enabled:

There is relatively little datetime logic inside of Biff proper. (Except for its RFC 5545 implementation, which may eventually move out to a library.) Most of the datetime logic is instead provided by Jiff. Additionally, localization is provided by ICU4X and integrated with Jiff via jiff-icu.

I may ship arbitrary and capricious breaking changes at this point. You have been warned.

Also, no compatibility with date is intended. This is not a drop-in replacement. It is not intended to be. It never will be. And it doesn't give a hoot about POSIX (other than the TZ environment variable). If you need a date compatible program, then go use an implementation of POSIX date. With that said, Biff's biff time fmt command generally supports a strftime syntax that has a large amount of compatibility with GNU date.

If you have use cases serviced by date that aren't possible with Biff, I'd like to hear about them.

I built this tool primarily as a way to expose some of the library functionality offered by Jiff on the command line. I was after a succinct way to format datetimes or do arithmetic. So I built this tool.

date is one of those commands that I use infrequently enough, and its flags and behavior is weird enough, that I constantly have to re-read its manual in order to use it effectively. So perhaps there is room for improvement there.

As I progressed in constructing this tool, I quickly found it somewhat limited by the fact that the only data it could process was datetimes. To make Biff much more versatile, I added a biff tag command that looks for datetimes in arbitrary data and wraps them up into a JSON lines format. It's unclear to me how broadly useful folks will find this functionality, but other datetime utilities don't seem to have it.

I also wanted to use Jiff in "anger," and in particular, as part of confidently getting it to a 1.0 state. Is its performance acceptable? Are there APIs missing that are needed for real world programs? And so on. For example, because of my development on Biff, I added a way to hook ICU4X localization into Jiff's jiff::fmt::strtime APIs.

Biff is written in Rust, so you'll need to grab a Rust installation in order to compile it.

To build Biff:

Additionally, optional locale support can be built with Biff by enabling the locale feature:

Biff can be built with the musl target on Linux by first installing the musl library on your system (consult your friendly neighborhood package manager). Then you just need to add musl support to your Rust toolchain and rebuild Biff, which yields a fully static executable:

Applying the --features locale flag from above should also work.

To run both unit tests and integration tests, use:

from the repository root. If you're hacking on Biff and need to change or add tests, Biff makes heavy use of cargo insta for snapshot testing. For example, to run tests with Insta, use:

And if there are any snapshots to review, you can review them via: