date-time-cli

name	date-time-cli
description	Date, time, timezone, and epoch timestamp manipulation from the command line. Use when user mentions "date command", "timestamp", "epoch", "unix timestamp", "timezone conversion", "date math", "date formatting", "ISO 8601", "convert timestamp", "time ago", or any date/time manipulation in shell.

Date & Time CLI

Current Date and Time

date                        # system default format
date +%s                    # epoch seconds (Unix timestamp)
date +%Y-%m-%d              # 2026-04-13
date +"%Y-%m-%d %H:%M:%S"  # 2026-04-13 14:30:00
date +%T                    # 14:30:00 (shorthand for %H:%M:%S)
date -u                     # UTC time

Format Strings

Token	Meaning	Example
%Y	4-digit year	2026
%m	Month (01-12)	04
%d	Day (01-31)	13
%H	Hour 24h (00-23)	14
%M	Minute (00-59)	30
%S	Second (00-59)	45
%s	Epoch seconds	1681400000
%N	Nanoseconds (GNU)	123456789
%Z	Timezone name	EDT
%z	Timezone offset	-0400
%A	Day of week name	Monday
%a	Day abbrev	Mon
%B	Month name	April
%j	Day of year	103
%u	Day of week (1=Mon)	1
%F	Shorthand %Y-%m-%d	2026-04-13

macOS vs GNU date -- Critical Differences

macOS ships BSD date. Linux ships GNU date. They are not compatible.

Parse a date string

# GNU (Linux)
date -d "2026-04-13 14:30:00" +%s

# macOS (BSD)
date -j -f "%Y-%m-%d %H:%M:%S" "2026-04-13 14:30:00" +%s

Date math

# GNU (Linux) -- use -d with relative strings
date -d "now + 3 days"
date -d "2026-04-13 + 2 hours"
date -d "yesterday"
date -d "last monday"

# macOS (BSD) -- use -v with adjustment flags
date -v+3d                  # 3 days from now
date -v-2H                  # 2 hours ago
date -v+1m                  # 1 month from now (lowercase m = month)
date -v+30M                 # 30 minutes from now (uppercase M = minute)
date -v-1y                  # 1 year ago
date -v+1w                  # 1 week from now

macOS -v flags: y year, m month, w week, d day, H hour, M minute, S second.

Epoch Conversions

Epoch seconds: 10 digits (e.g., 1681400000). Epoch milliseconds: 13 digits (e.g., 1681400000000). If 13 digits, divide by 1000 first.

# Seconds to human-readable
# GNU
date -d @1681400000
# macOS
date -r 1681400000

# Milliseconds to human-readable
# GNU
date -d @$((1681400000000 / 1000))
# macOS
date -r $((1681400000000 / 1000))

# Human-readable to epoch seconds
# GNU
date -d "2026-04-13T14:30:00" +%s
# macOS
date -j -f "%Y-%m-%dT%H:%M:%S" "2026-04-13T14:30:00" +%s

# Current epoch
date +%s

ISO 8601

# GNU
date --iso-8601=seconds          # 2026-04-13T14:30:00-04:00

# macOS (no --iso-8601 flag, construct manually)
date -u +"%Y-%m-%dT%H:%M:%SZ"   # 2026-04-13T18:30:00Z
date +"%Y-%m-%dT%H:%M:%S%z"     # 2026-04-13T14:30:00-0400

Note: ISO 8601 wants -04:00 not -0400. GNU handles this; on macOS insert the colon yourself.

Timezone Conversion

# Show time in a specific timezone (works on both GNU and macOS)
TZ="America/New_York" date
TZ="Europe/London" date
TZ="Asia/Tokyo" date
TZ="UTC" date

# Convert a specific timestamp to another timezone
# GNU
TZ="Asia/Tokyo" date -d "2026-04-13 14:30:00 EDT"
# macOS
epoch=$(date -j -f "%Y-%m-%d %H:%M:%S" "2026-04-13 14:30:00" +%s)
TZ="Asia/Tokyo" date -r "$epoch"

# List available timezones
ls /usr/share/zoneinfo/America/

Compare Two Dates

Convert both to epoch, then compare.

# GNU
d1=$(date -d "2026-04-13" +%s)
d2=$(date -d "2026-05-01" +%s)

# macOS
d1=$(date -j -f "%Y-%m-%d" "2026-04-13" +%s)
d2=$(date -j -f "%Y-%m-%d" "2026-05-01" +%s)

# Compare
if [ "$d1" -lt "$d2" ]; then
  echo "d1 is earlier"
fi

# Difference in days
diff_days=$(( (d2 - d1) / 86400 ))
echo "$diff_days days apart"

Parse Dates from Strings

# GNU date is very flexible
date -d "April 13, 2026" +%F
date -d "13 Apr 2026" +%F
date -d "next friday" +%F
date -d "2 weeks ago" +%F

# macOS requires exact format specification
date -j -f "%B %d, %Y" "April 13, 2026" +%F
date -j -f "%d %b %Y" "13 Apr 2026" +%F

Useful One-Liners

How long ago was this timestamp

# Given an epoch timestamp
ts=1681400000
now=$(date +%s)
diff=$((now - ts))
echo "$((diff / 86400)) days, $(( (diff % 86400) / 3600 )) hours ago"

What day of the week was a date

# GNU
date -d "2026-04-13" +%A        # Monday

# macOS
date -j -f "%Y-%m-%d" "2026-04-13" +%A

Seconds between two timestamps

# GNU
echo $(( $(date -d "2026-05-01" +%s) - $(date -d "2026-04-13" +%s) ))

# macOS
echo $(( $(date -j -f "%Y-%m-%d" "2026-05-01" +%s) - $(date -j -f "%Y-%m-%d" "2026-04-13" +%s) ))

Relative time description

relative_time() {
  local diff=$(( $(date +%s) - $1 ))
  if   [ $diff -lt 60 ];    then echo "${diff}s ago"
  elif [ $diff -lt 3600 ];  then echo "$((diff/60))m ago"
  elif [ $diff -lt 86400 ]; then echo "$((diff/3600))h ago"
  else echo "$((diff/86400))d ago"
  fi
}
relative_time 1681400000

Date in Scripts

Generate timestamped filenames

backup_file="db-backup-$(date +%Y%m%d-%H%M%S).sql.gz"
log_file="deploy-$(date +%F).log"

Log timestamps

log() { echo "[$(date +"%Y-%m-%d %H:%M:%S")] $*"; }
log "Deployment started"
# [2026-04-13 14:30:00] Deployment started

Measure elapsed time

start=$(date +%s)
# ... do work ...
echo "Took $(( $(date +%s) - start ))s"

When date Is Not Enough

Python

python3 -c "from dateutil.parser import parse; print(parse('April 13, 2026 2:30 PM').isoformat())"
python3 -c "from datetime import datetime; print(datetime.fromtimestamp(1681400000000/1000))"
python3 -c "from datetime import datetime,timezone; print((datetime.now(timezone.utc)-datetime(2026,4,13,tzinfo=timezone.utc)).total_seconds())"
python3 -c "from datetime import datetime; from zoneinfo import ZoneInfo; print(datetime.now(ZoneInfo('Asia/Tokyo')))"

Node

node -e "console.log(new Date(1681400000000).toISOString())"
node -e "console.log(new Date('April 13, 2026').toISOString())"
node -e "console.log(Date.now())"                              # current epoch ms
node -e "console.log((Date.now() - new Date('2026-04-13').getTime()) / 3600000, 'hours')"

Quick Reference

Task	GNU (Linux)	macOS (BSD)
Current epoch	date +%s	date +%s
Epoch to date	date -d @EPOCH	date -r EPOCH
Parse date string	date -d "STRING"	date -j -f "FMT" "STRING"
Add 3 days	date -d "now + 3 days"	date -v+3d
Subtract 2 hours	date -d "now - 2 hours"	date -v-2H
ISO 8601	date --iso-8601=seconds	date -u +"%Y-%m-%dT%H:%M:%SZ"
Specific TZ	TZ="Zone" date	TZ="Zone" date