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