vrk epoch

vrk epoch converts between Unix timestamps and ISO 8601, and handles relative offsets like +3d or -1h.

The problem

date -d @1740009600 works on Linux. On macOS, -d means something different and you need date -r 1740009600 instead. Relative times are worse: date -d '+3 days' is Linux-only. Every timestamp conversion in a cross-platform script becomes a compatibility puzzle.

The solution

vrk epoch converts between Unix timestamps and ISO 8601, and handles relative offsets like +3d or -1h. It works the same on macOS and Linux. Use --at to pin the reference time, so the pipeline output is the same on every run.

Before and after

Before

# Linux: date -d @1740009600
# macOS: date -r 1740009600
# Neither is portable. Scripts break on the other OS.

After

vrk epoch 1740009600 --iso

Example

vrk epoch '+3d' --iso

Exit codes

Flags

Input formats

vrk epoch converts between Unix timestamps and ISO 8601 dates, and calculates relative times such as +3d.

vrk epoch accepts four input forms:

epoch reads an integer as milliseconds (JavaScript Date.now()) if its absolute value is from 100000000000 up to, but not including, 100000000000000. So vrk epoch --iso 1792042275000 prints 2026-10-15T05:31:15Z. Ten-digit values stay seconds. With --json, millisecond input adds "unit":"ms".

Relative units: s (seconds), m (minutes), h (hours), d (days), w (weeks).

How it works

Unix to ISO

$ vrk epoch 1740009600 --iso
2025-02-20T00:00:00Z

ISO to Unix

$ vrk epoch '2025-02-20T00:00:00Z'
1740009600

Relative time

$ vrk epoch '+3d' --at 1740009600
1740268800

$ vrk epoch '+3d' --at 1740009600 --iso
2025-02-23T00:00:00Z

Current time

$ vrk epoch --now
1774892819

JSON output

$ vrk epoch '+3d' --at 1740009600 --json
{"input":"+3d","unix":1740268800,"iso":"2025-02-23T00:00:00Z","ref":"1740009600"}

Timezone conversion

$ vrk epoch 1740009600 --iso --tz America/New_York
2025-02-19T19:00:00-05:00

$ vrk epoch 1740009600 --iso --tz +09:00
2025-02-20T09:00:00+09:00

Fixed reference point (–at)

For reproducible scripts, pin the reference time instead of using “now”:

$ vrk epoch '+3d' --at 1740009600 --iso
2025-02-23T00:00:00Z

Pipeline integration

Store timestamps in kv

# Record when a pipeline ran
vrk kv set --ns pipeline last_run "$(vrk epoch --now)"

# Set a TTL relative to now
vrk kv set --ns cache result "$DATA" --ttl 24h

Check JWT expiry as a date

# Decode a JWT's expiry and convert to human-readable
EXP=$(echo "$TOKEN" | vrk jwt --claim exp)
echo "Token expires: $(vrk epoch "$EXP" --iso)"

Schedule-aware pipelines

# Only run if it's been more than 6 hours since last run
LAST=$(vrk kv get --ns pipeline last_run 2>/dev/null || echo "0")
SIX_HOURS_AGO=$(vrk epoch '-6h')
if [ "$LAST" -lt "$SIX_HOURS_AGO" ]; then
  run-pipeline
  vrk kv set --ns pipeline last_run "$(vrk epoch --now)"
fi

When it fails

Invalid input:

$ vrk epoch 'not-a-date'
error: epoch: unsupported format "not-a-date": natural language not supported; accepted forms: unix integer, +3d/-3d, YYYY-MM-DD, YYYY-MM-DDTHH:MM:SSZ
$ echo $?
1

A date that does not exist is also exit 1:

$ vrk epoch 2026-02-29
error: epoch: invalid date "2026-02-29"
$ echo $?
1

Missing input:

$ vrk epoch
usage error: epoch: no input: provide as argument or via stdin
$ echo $?
2