Current Date And Time Skill

To use the values in your script:

eval "$(./scripts/datetime.sh)"
echo "Today is $DATE_ISO"
echo "Timestamp: $TIMESTAMP_UNIX"

Available Formats

All timestamps reflect the system's local timezone unless explicitly noted as UTC.

Common Use Cases

1. Creating Timestamped Files and Backups

Create files with timestamps in their names for easy sorting and identification:

# Load all date/time variables
eval "$(./scripts/datetime.sh)"

# Create a timestamped backup
cp database.db "backups/database-${DATE_ISO}.db"

# Create a log file with full timestamp
touch "logs/app-${DATETIME_FILE}.log"

# Generate a report with human-readable date
echo "Sales Report for $DATE_HUMAN" > "reports/sales-${DATE_COMPACT}.txt"

2. API Queries with Date Parameters

Pass properly formatted dates to REST APIs:

# Get date variables
eval "$(./scripts/datetime.sh)"

# Query an API with ISO date
curl "https://api.example.com/events?date=${DATE_ISO}"

# Send JSON with ISO datetime and timezone
curl -X POST https://api.example.com/logs \
  -H "Content-Type: application/json" \
  -d "{\"timestamp\": \"${DATETIME_ISO}\", \"message\": \"System check\"}"

# Use Unix timestamp for time-based APIs
curl "https://api.example.com/data?since=${TIMESTAMP_UNIX}"

3. Structured Data with Timestamps

Embed timestamps in JSON, CSV, or other structured formats:

eval "$(./scripts/datetime.sh)"

# Create JSON with multiple timestamp formats
cat > event.json <<EOF
{
  "event_id": "evt_${TIMESTAMP_UNIX}",
  "created_at": "${DATETIME_ISO}",
  "created_at_utc": "${DATETIME_UTC}",
  "date": "${DATE_ISO}",
  "display_date": "${DATE_HUMAN}",
  "timezone": "${TIMEZONE}"
}
EOF

# Append to CSV log
echo "${DATE_ISO},${TIMESTAMP_UNIX},system_check,OK" >> system_log.csv

4. Automated Backup Scripts

Create daily or periodic backups with organized naming:

#!/usr/bin/env bash
# Daily backup script

eval "$(./scripts/datetime.sh)"

# Define backup directory with date
BACKUP_DIR="backups/${DATE_ISO}"
mkdir -p "$BACKUP_DIR"

# Backup files with timestamps
tar -czf "${BACKUP_DIR}/data-${DATETIME_FILE}.tar.gz" /path/to/data
tar -czf "${BACKUP_DIR}/config-${DATETIME_FILE}.tar.gz" /etc/myapp

# Log the backup
echo "[${DATETIME_ISO}] Backup completed successfully" >> backup.log

# Cleanup old backups (keep last 7 days)
find backups/ -type d -mtime +7 -exec rm -rf {} +

5. Log File Management

Create and append to timestamped log files:

eval "$(./scripts/datetime.sh)"

# Create daily log file
LOGFILE="logs/app-${DATE_COMPACT}.log"

# Append entries with ISO timestamps
echo "[${DATETIME_ISO}] Application started" >> "$LOGFILE"
echo "[${DATETIME_ISO}] Connected to database" >> "$LOGFILE"

# Create a log entry function
log_message() {
  eval "$(./scripts/datetime.sh)"
  echo "[${DATETIME_ISO}] $1" >> "$LOGFILE"
}

log_message "Processing batch job"
log_message "Batch job completed"

6. Scheduling and Time-Based Operations

Use timestamps for scheduling decisions and time-based logic:

eval "$(./scripts/datetime.sh)"

# Check if it's time for maintenance (compare Unix timestamps)
LAST_MAINTENANCE=$(cat last_maintenance.txt)
TIME_SINCE=$((TIMESTAMP_UNIX - LAST_MAINTENANCE))
TWENTY_FOUR_HOURS=86400

if [ $TIME_SINCE -ge $TWENTY_FOUR_HOURS ]; then
  echo "Running maintenance..."
  ./maintenance.sh
  echo "$TIMESTAMP_UNIX" > last_maintenance.txt
fi

# Create time-based directory structure
ARCHIVE_DIR="archives/${DATE_ISO:0:4}/${DATE_ISO:5:2}"  # YYYY/MM
mkdir -p "$ARCHIVE_DIR"
mv processed_*.dat "$ARCHIVE_DIR/"

Tips & Best Practices

Format Selection Guide

• Use DATE_ISO for simple dates, database date fields, and when you don't need time information
• Use DATETIME_ISO when you need precise timestamps with timezone awareness (most common for logging)
• Use DATETIME_UTC for distributed systems, international applications, or when coordinating across timezones
• Use TIMESTAMP_UNIX for time calculations, sorting by time, or APIs that expect Unix timestamps
• Use DATE_HUMAN only for user-facing output, never for file names or database storage
• Use DATETIME_FILE for file and directory names (no colons or spaces, safe on all platforms)
• Use DATE_COMPACT when you need short date identifiers or daily grouping

Timezone Considerations

• All timestamps except DATETIME_UTC reflect your system's local timezone
• The TIMEZONE variable shows your current offset from UTC
• Always use DATETIME_UTC when storing timestamps that will be accessed from multiple timezones
• For local operations (backups, logs), local time formats are usually more intuitive

Performance Notes

• The script runs in under 10ms on most systems
• Call once and reuse variables rather than calling multiple times in loops
• For high-frequency logging, consider calling once per batch rather than per log entry

Integration Patterns

# Pattern 1: Load once, use multiple times
eval "$(./scripts/datetime.sh)"
process_data "$DATE_ISO"
create_backup "$DATETIME_FILE"
log_event "$DATETIME_ISO"

# Pattern 2: Inline for simple cases
BACKUP_FILE="backup-$(./scripts/datetime.sh | grep DATE_ISO | cut -d= -f2).tar.gz"

# Pattern 3: Source in functions
get_timestamp() {
  eval "$(./scripts/datetime.sh)"
  echo "$DATETIME_ISO"
}

Troubleshooting

Permission Denied

If you get a "Permission denied" error:

chmod +x ./scripts/datetime.sh

Script Not Found

If running from a different directory:

# Use absolute path
eval "$(/absolute/path/to/scripts/datetime.sh)"

# Or change to skill directory first
cd /path/to/current-date-and-time-skill
eval "$(./scripts/datetime.sh)"

Date Command Differences

This script is compatible with both BSD date (macOS) and GNU date (Linux). If you experience issues:

• macOS/BSD date: Already compatible, no changes needed
• Linux/GNU date: Already compatible, no changes needed
• Other systems: May need to install GNU coreutils

Timezone Formatting Issues

If timezone appears without colon (e.g., +0800 instead of +08:00):

This shouldn't happen with the current script, but if you see it, ensure the sed command is working:

date '+%z' | sed -E 's/([+-][0-9]{2})([0-9]{2})$/\1:\2/'

Empty or Missing Variables

If variables are empty after eval:

# Check script output directly
./scripts/datetime.sh

# Verify eval syntax (note the double quotes and dollar-parentheses)
eval "$(./scripts/datetime.sh)"

# Check if variables are set
echo "DATE_ISO is: ${DATE_ISO:-NOT SET}"

Time Appears Incorrect

The script uses your system time. To verify:

# Check system time
date

# Check timezone setting
date +%Z

# For UTC time specifically
date -u

Examples in Practice

Complete Backup Script

#!/usr/bin/env bash
set -euo pipefail

# Load datetime variables
eval "$(./scripts/datetime.sh)"

# Configuration
SOURCE_DIR="/var/www/html"
BACKUP_ROOT="/backups"
BACKUP_DIR="${BACKUP_ROOT}/${DATE_ISO}"
LOGFILE="${BACKUP_ROOT}/backup.log"

# Create backup directory
mkdir -p "$BACKUP_DIR"

# Create backup with timestamp
BACKUP_FILE="${BACKUP_DIR}/website-${DATETIME_FILE}.tar.gz"
tar -czf "$BACKUP_FILE" "$SOURCE_DIR"

# Log success
echo "[${DATETIME_ISO}] Backup created: ${BACKUP_FILE}" >> "$LOGFILE"

# Cleanup old backups (keep 30 days)
find "$BACKUP_ROOT" -type f -name "*.tar.gz" -mtime +30 -delete

echo "Backup completed: $BACKUP_FILE"

API Integration Script

#!/usr/bin/env bash

# Load datetime variables
eval "$(./scripts/datetime.sh)"

# API configuration
API_URL="https://api.example.com/metrics"
API_KEY="your-api-key"

# Send metrics with timestamp
curl -X POST "$API_URL" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"timestamp\": \"${DATETIME_ISO}\",
    \"timestamp_unix\": ${TIMESTAMP_UNIX},
    \"metric\": \"cpu_usage\",
    \"value\": 45.2,
    \"timezone\": \"${TIMEZONE}\"
  }"

License

MIT License - See LICENSE.txt for details.

Version

1.0.0 - Initial release with 8 essential date/time formats