aux4/time

A time and date utility for the command line. It answers everyday questions — what is today, tomorrow, yesterday — does calendar-aware arithmetic, converts between timezones and formats, understands UTC and Unix epoch, and parses natural-language expressions like "in two hours" or "next friday". Every command can emit a rich JSON object, making it a reliable time source for scripts, AI agents, and other aux4 packages such as calendars.

Installation

aux4 aux4 pkger install aux4/time

Quick Start

# The current instant, ISO 8601 in your local zone
aux4 time now

# Today, tomorrow, yesterday
aux4 time today
aux4 time tomorrow
aux4 time yesterday

# Arithmetic — a week from now, 30 minutes ago, in two hours
aux4 time add --weeks 1
aux4 time subtract --minutes 30
aux4 time add --hours 2

# Convert a UTC instant to another zone
aux4 time convert 2026-08-10T12:00:00Z --toZone Asia/Tokyo

# Parse a human expression
aux4 time parse "next friday at 3pm"

Output Formats

Commands that produce an instant share the same output options:

--format selects a scalar representation: iso (default), rfc3339, datetime, date, time, epoch, epochMillis, kitchen, rfc1123.
--json true emits the full structured moment object instead of a scalar.
--timezone <zone> renders the result in an IANA timezone; --utc true forces UTC and overrides --timezone.

The structured moment object is stable across the package and intended for programmatic consumers:

{
  "iso": "2026-08-10T21:15:42+09:00",
  "utc": "2026-08-10T12:15:42Z",
  "epoch": 1786360542,
  "epochMillis": 1786360542000,
  "date": "2026-08-10",
  "time": "21:15:42",
  "timezone": "Asia/Tokyo",
  "offset": "+09:00",
  "weekday": "Monday",
  "dayOfYear": 222,
  "week": 33
}

Current Date

now, today, tomorrow, and yesterday report the current instant or calendar date. today/tomorrow/yesterday truncate to the start of the day and default to date output; now defaults to a full ISO timestamp.

aux4 time now --timezone America/New_York
aux4 time today --utc true
aux4 time now --format epoch

Because a calendar date depends on the zone, use --timezone/--utc to control which zone "today" is evaluated in — near midnight the date can differ between zones.

Arithmetic

add and subtract shift a date by any combination of years, months, weeks, days, hours, minutes, and seconds. The base date is the positional argument and defaults to now, so you can compute relative to today or to any given date.

# Relative to now
aux4 time add --days 3 --hours 6
aux4 time subtract --weeks 2

# Relative to a specific date
aux4 time add 2026-01-01 --months 6 --format date

Arithmetic is calendar-aware. Months and years use end-of-month clamping: adding one month to January 31 yields the last day of February (February 28, or February 29 in a leap year) rather than overflowing into March. Hours, minutes, and seconds are clock durations that correctly cross daylight-saving transitions when a real timezone is used.

aux4 time add 2026-01-31 --months 1 --utc true --format date
# 2026-02-28

Duration

diff measures the gap between two dates. Both --from and --to default to now, so supplying one measures the distance to the present. The default output is a humanized phrase; --json returns totals in every unit plus a component breakdown.

aux4 time diff --from 2026-08-10 --to 2026-08-13
# in 3 days

aux4 time diff --to 2026-12-25 --json true

Timezone and Format Conversion

convert changes a moment between zones and formats. The input is a date/time (positional) or a Unix epoch (--epoch); the output is rendered in --toZone.

# UTC instant to Tokyo wall-clock
aux4 time convert 2026-08-10T12:00:00Z --toZone Asia/Tokyo

# Epoch to a New York timestamp
aux4 time convert --epoch 1786349029 --toZone America/New_York

# A naive New York time to UTC
aux4 time convert "2026-08-10 08:00:00" --fromZone America/New_York --toZone UTC

--toZone accepts any IANA name, local, or UTC. --fromZone controls how a naive input (without an offset) is interpreted; inputs that already carry an offset keep it. Epoch values with 13 or more digits are treated as milliseconds.

Natural-Language Parsing

parse turns human phrasing into a structured date, resolved against a reference time (--from, defaulting to now). This is the most convenient entry point for AI agents.

aux4 time parse "in two hours"
aux4 time parse "30 minutes ago"
aux4 time parse "next friday at 3pm"
aux4 time parse "2026-12-25"          # absolute dates work too

If the phrase is not a recognized relative expression, parse falls back to absolute date parsing; if neither succeeds it fails rather than silently returning the reference time.

Note: Natural-language expressions are interpreted in English only. Weekday and month names in output (e.g. Monday) are also English.

Reformatting

format renders a date/time into another representation, including a custom Go layout.

aux4 time format 2026-08-10T14:30:00Z --format date
aux4 time format now --format kitchen
aux4 time format 2026-08-10T14:30:00Z --format custom --layout "Mon Jan 2 2006"

The Go reference layout uses the canonical date Mon Jan 2 15:04:05 MST 2006.

Timezones

The zone commands enumerate and inspect IANA timezones.

# List zones, optionally filtered
aux4 time zone list
aux4 time zone list Sao

# Current offset, abbreviation, and DST state
aux4 time zone info America/New_York

# Current time somewhere else
aux4 time zone now Asia/Tokyo

zone info reports the offset, abbreviation, and whether daylight saving is currently in effect (detected by comparing the current offset against the zone's standard offset for the year). The zone names printed by zone list are exactly the values accepted anywhere a timezone is expected.