biff Plugin

Datetime arithmetic, parsing, formatting, timezone conversion, sequence generation, and log timestamp tagging for the command line. By BurntSushi (author of ripgrep, xsv, and jiff).

Commands

Time Formatting

• biff time fmt — Format one or more timestamps

Time Arithmetic

• biff time add — Add a duration to a timestamp

Duration Calculation

• biff span since — Calculate the duration since a given timestamp

Utility

• biff self version — Print biff version
• biff _ _ — Passthrough to biff CLI

Usage Examples

• "What time is it now?"
• "Format this date as RFC 3339"
• "What will the date be 6 months from now?"
• "How long has it been since January 20th?"
• "Convert UTC timestamps in a log to my local timezone"
• "Generate the next 5 Mondays at 9am"

Installation

cargo install biff

Examples

# Print the current time
biff _ _

# Format current time as RFC 3339
biff time fmt -f rfc3339 now

# Format current time as RFC 9557 (with timezone)
biff time fmt -f rfc9557 now

# Custom format
biff time fmt -f '%Y-%m-%d %H:%M:%S %Z' now

# Format multiple relative times
biff time fmt -f '%c' now -1d 'next sat' 'last monday' '9pm last mon'

# Add a duration to the current time
biff time add -1w now

# Add natural-language duration
biff time add '1 week, 12 hours ago' now

# Add 6 months
biff time add 6mo now

# Convert time to another timezone and round to nearest 15 minutes
biff time fmt now | biff _ _ time in Asia/Bangkok | biff _ _ time round -i 15 -s minute

# Calculate duration since a date
biff span since 2025-01-20T12:00

# Calculate duration with year-level precision
biff span since 2025-01-20T12:00 -l year

# Round a duration
biff span since 2025-01-20T12:00 | biff _ _ span round -l year -s day

# Generate a sequence of the next 5 weekdays at 9am
biff _ _ time seq day today -c5 -H 9 -w mon,wed,fri

# Generate all days remaining in the current month
biff _ _ time seq daily --until $(biff _ _ time end-of month now) today

# Generate the last weekday of each of the next 12 months
biff _ _ time seq -c12 monthly -w mon,tue,wed,thu,fri --set-position -1 | biff time fmt -f '%a, %Y-%m-%d'

# Reformat timestamps in a log file to local time
biff _ _ tag lines /tmp/access.log | biff _ _ time in system | biff time fmt -f '%c' | head -n3 | biff _ _ untag -s

Key Features

• Print current time in various formats
• Format timestamps with RFC 3339, RFC 9557, or custom strftime patterns
• Parse natural-language relative times (now, -1d, next sat, last monday, 9pm last mon)
• Add/subtract durations with natural language (1 week, 12 hours ago, 6mo)
• Convert between timezones
• Round times to arbitrary increments
• Calculate durations since a given timestamp
• Round durations to desired precision
• Generate date/time sequences with filtering (weekdays, specific days)
• Tag and untag timestamps in log files for batch reformatting

Notes

• biff uses the jiff datetime library (also by BurntSushi) for high-quality parsing and arithmetic
• For locale-aware output, set BIFF_LOCALE and use a release binary or build with the locale feature
• biff supports IANA timezone names (e.g. America/New_York, Asia/Bangkok)
• Duration parsing accepts shorthand (-1w) and verbose forms ("1 week, 12 hours ago")