Agent Skills
› NeverSight/learn-skills.dev
› date-time-cli
date-time-cli
GitHub提供命令行日期、时间、时区及时间戳操作指南。涵盖格式转换、epoch处理、日期计算及ISO 8601标准，并重点区分Linux GNU与macOS BSD date命令的差异及兼容用法。
Trigger Scenarios
date command
timestamp
epoch
unix timestamp
timezone conversion
date math
date formatting
ISO 8601
convert timestamp
time ago
Install
npx skills add NeverSight/learn-skills.dev --skill date-time-cli -g -y
SKILL.md
Frontmatter
{
"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 |
Version History
- e0220ca Current 2026-07-05 20:42
