| name | bttf |
| description | Use the bttf CLI for datetime arithmetic, formatting, timezone conversion, and duration calculation. Reach for this instead of doing date math mentally — LLMs are unreliable for datetime computation, especially across DST boundaries and leap years. |
| user-invocable | true |
| args | [{"name":"task","description":"What datetime operation to perform (e.g. \"how many days until 2026-01-01\", \"current time in Tokyo\")","required":false}] |
bttf — Command-line Datetime Tool
bttf (Back to the Future) is installed at /opt/homebrew/bin/bttf. Use it for all non-trivial datetime work — current time, arithmetic, timezone conversion, duration calculation, formatting. Do not do this math mentally.
When to reach for bttf: anytime the user asks about the current time, a date in the past or future, how long until/since something, timezone conversion, or date formatting.
Get the Current Time
bttf
bttf time fmt -f rfc3339 now
bttf time fmt -f rfc9557 now
bttf time fmt -f '%Y-%m-%d' now
bttf time fmt -f '%Y-%m-%d %H:%M:%S' now
bttf time fmt -f '%s' now
Datetime Inputs — What bttf Accepts
Most subcommands take a <datetime> argument. Accepted forms:
| Input | Meaning |
|---|
now | Current instant |
today | First instant of today |
yesterday / tomorrow | First instant of prev/next day |
2025-03-15 | ISO date (local midnight) |
08:30 | Time today |
2025-03-15T10:23:00-04:00 | RFC 3339 |
2025-03-15T10:23:00-04:00[America/New_York] | RFC 9557 |
-1d | 1 day ago |
1w | 1 week from now |
6mo | 6 months from now |
1y1s | Mixed units |
next saturday | Next Saturday |
last friday | Previous Friday |
this thurs | This Thursday (or today if it's Thursday) |
5pm tomorrow | 5pm tomorrow |
5pm next wed | 5pm next Wednesday |
1 week ago | Verbose relative form |
bttf time fmt — Format / Convert Datetimes
bttf time fmt now
bttf time fmt -f rfc3339 now
bttf time fmt -f rfc2822 now
bttf time fmt -f rfc9110 now
bttf time fmt -f '%B %d, %Y' now
bttf time fmt -f '%Y-%m-%d' 2025-03-15
bttf time fmt -f '%A' 2026-07-04
bttf time fmt -f '%V' now
bttf time fmt -f '%s' now
bttf time fmt -f '%c' now -1d 'next sat'
Named formats: rfc9557 (default), rfc3339, rfc2822, rfc9110
bttf time parse — Parse Datetimes from Non-Standard Formats
bttf time parse -f '%m/%d/%y' 03/15/25
bttf time parse -f flexible '5pm next wednesday'
bttf time parse -f '%s' 1736956800
bttf time parse -i -f '%Y-%m-%d' invalid 2026-01-01
Options: -f <format> (default: rfc9557), -i/--ignore-invalid, -r/--relative <datetime>
bttf time relative — Relative Descriptions Against a Reference
bttf time relative 'this monday' 2025-04-22
bttf time relative 'next friday' 2026-01-01
bttf time relative 'last day of month' now
Usage: bttf time relative <relative-description> <datetime>...
bttf time in — Timezone Conversion
bttf time in America/New_York now
bttf time in Asia/Tokyo now
bttf time in UTC now
bttf time in Pacific/Honolulu now
bttf time in now America/Chicago
Usage: bttf time in <time-zone> <datetime>... or bttf time in <datetime> <time-zone>...
bttf time add — Datetime Arithmetic
bttf time add 1w now
bttf time add -1d now
bttf time add 6mo now
bttf time add 1y6mo now
bttf time add 90d 2026-01-01
bttf time add '1 week, 12 hours ago' now
Usage: bttf time add <span> <datetime>... or bttf time add <datetime> <span>...
bttf time cmp — Filter Datetimes by Comparison
Prints only datetimes satisfying the inequality — useful for filtering lists.
bttf time cmp gt 2025-03-01 2025-02-28 2025-03-02
cat dates.txt | bttf time cmp le now
cat dates.txt | bttf time cmp ge 2026-01-01
Operators: eq, ne, lt, gt, le, ge
Usage: bttf time cmp <op> <datetime> <datetime>...
bttf time round — Round Datetimes
Rounding only works for units of days or lower.
bttf time round -s minute now
bttf time round -s hour now
bttf time round -s day now
bttf time round -i 15 -s minute now
bttf time round -m trunc -s hour now
Options: -s/--smallest <unit>, -i/--increment <number>, -m/--mode <rounding-mode> (e.g. trunc, half-expand)
bttf time start-of / bttf time end-of — Snap to Period Boundaries
bttf time start-of year now
bttf time start-of month now
bttf time start-of week now
bttf time start-of day now
bttf time start-of hour now
bttf time end-of year now
bttf time end-of month now
bttf time end-of week now
bttf time end-of day now
Usage: bttf time start-of <unit> <datetime>...
bttf time sort — Sort Datetimes
bttf time sort 2026-03-01 2025-11-15 2026-01-20
bttf time sort -r 2026-03-01 2025-11-15 2026-01-20
cat dates.txt | bttf time sort
cat dates.txt | bttf time sort -r
Also accepts tagged data from stdin (see tagging section).
bttf time seq — Generate Datetime Sequences (RFC 5545 Recurrence)
bttf time seq daily -c 7 now
bttf time seq weekly --until 2026-12-31 now
bttf time seq monthly -c 12 2026-01-01
bttf time seq daily -w mon,tue,wed,thu,fri -c 10 now
bttf time seq weekly -i 2 -c 5 now
bttf time seq monthly --until 3y -w fri -d 13
Frequencies: daily, weekly, monthly, yearly
Key options: -c/--count <n>, --until <datetime>, -i/--interval <n>,
-w/--week-day, -d/--day, -m/--month, -H/--hour, -M/--minute
bttf span since / bttf span until — Duration Calculation
Default largest unit is hours. Use -l to get calendar units.
bttf span since 2025-01-20T12:00
bttf span since 2025-01-20 -l year
bttf span until 2027-01-01 -l year
bttf span until 2026-12-25 -l day
bttf span since 2025-01-20 | bttf span round -l day -s day
bttf span until 2026-12-25 | bttf span round -l day -s day
bttf span since 2025-01-01 -r 2026-01-01
Options: -l/--largest <unit>, -r/--relative <datetime>
bttf span round — Round Spans
bttf span round 2h30m10s -s minute
bttf span round 2h30m10s -s minute -m expand
bttf span round 75y5mo22d -l year -s day
bttf span round 90m -s hour
bttf span since 2025-01-01 | bttf span round -l year -s day
Options: -s/--smallest <unit>, -l/--largest <unit>, -i/--increment <n>,
-m/--mode (trunc, half-expand, expand, etc.), -r/--relative <datetime>
bttf span balance — Change Largest Non-Zero Unit
Converts units without rounding (full subsumption into target unit):
bttf span balance 2h30m10s -l seconds
bttf span balance 75y5mo22d -l month
bttf span balance 90m -l hour
Options: -l/--largest <unit>, -r/--relative <datetime>
bttf span fmt — Format Spans (Verbose / Custom)
bttf span fmt '75y5mo22d' -s units-and-designators -d verbose --comma
bttf span fmt 2h30m -d verbose
bttf span fmt 2h30m --hms
Options: -d/--designator <kind> (verbose), -s/--spacing <kind>,
--comma, --hms, --precision <n>, --sign <kind>, -f/--fractional <unit>
bttf span iso8601 — Format Spans as ISO 8601 Durations
bttf span iso8601 75y5mo22d5h30m12s
bttf span iso8601 -l 2h30m
bttf span since 2025-01-01 | bttf span iso8601
bttf tag / bttf untag — Tagging Pipeline
bttf's tagging system associates datetimes with data items so they can be
sorted/filtered by time, then reconstructed with untag.
bttf tag exec — Tag file paths via a command
git ls-files | bttf tag exec git log -n1 --format='%cI'
find . -name '*.log' | bttf tag exec stat -f '%Sm' {}
Options: -j/--threads <n>
bttf tag lines — Extract datetimes from log lines
bttf tag lines < access.log \
| bttf time fmt -f '%B %-d, %Y at %H:%M:%S' \
| bttf untag --substitute
bttf tag lines -e '\d{4}-\d{2}-\d{2}' < logfile.txt
Options: --auto <kind>, -e/--regex <pattern>, --all
bttf tag files — Extract datetimes from file contents
bttf tag files *.pdf
bttf tag files -e 'YYYY-MM-DD pattern' report.txt
Options: --auto, -e/--regex, --all, -j/--threads, --mmap/--no-mmap
bttf tag stat — Tag files with filesystem metadata
find ./ | bttf tag stat modified
find ./ | bttf tag stat created
find ./ | bttf tag stat accessed
bttf untag — Reconstruct tagged output
cat tagged.txt | bttf untag
cat tagged.txt | bttf untag -f '{tag} {data}'
cat tagged.txt | bttf untag --substitute
Options: -f/--format <string>, -s/--substitute
bttf tz — Timezone Commands
bttf tz list
bttf tz list | grep -i tokyo
bttf tz compatible '2025-03-09T17:00+10:30'
bttf tz next America/New_York now
bttf tz next America/New_York now -c 3
bttf tz prev America/New_York now
bttf tz seq America/New_York -c 5
bttf tz seq Australia/Sydney -c 5
bttf tz seq America/New_York -p -c 5
Piping Pattern
bttf is pipe-friendly — output of one command feeds into another:
bttf time in Asia/Bangkok now | bttf time round -i 15 -s minute
bttf span since 2025-01-20 | bttf span round -l day -s day
bttf time add 6mo now | bttf time fmt -f '%B %d, %Y'
git ls-files \
| bttf tag exec git log -n1 --format='%cI' \
| bttf time sort \
| bttf untag -f '{tag} {data}'
Common Recipes
bttf time fmt -f '%A' 2026-07-04
bttf span until 2026-12-25 | bttf span round -l day -s day
bttf span since 2024-03-01 | bttf span round -l day -s day
for tz in America/New_York America/Chicago America/Los_Angeles; do
echo -n "$tz: "; bttf time in $tz now | bttf time fmt -f '%H:%M %Z'
done
bttf time fmt -f '%V' now
bttf time start-of month now
bttf time end-of month now
cat dates.txt | bttf time cmp gt now
bttf time seq weekly -w mon -c 5 now
bttf span since 2025-01-01 -l year | bttf span fmt -d verbose --comma
bttf time parse -f '%s' 1736956800 | bttf time fmt -f '%c'
Tips
bttf always has access to the real current time — use it instead of relying on the date in the system prompt.- Set
BTTF_NOW to override "now" for testing: BTTF_NOW="2025-01-01T00:00:00" bttf
- Set
BTTF_LOCALE in your shell to enable locale-aware formats (%c, %x, %X).
TZ env var overrides the system timezone: TZ=UTC bttf time fmt nowTZDIR overrides the timezone database location.bttf span since/until default to hours as largest unit; use -l year etc. for calendar output.- Exit code 0 = success; non-zero = parse/arithmetic error — check stderr on failure.
- Use
-h for short help, --help for full docs with examples.
