datemath

Natural language date calculations and formatting.

A simple CLI for working with dates, times, and durations. Designed for humans and AI agents alike.

Installation

pip install datemath-cli

Usage

Current Time

datemath now                    # Show current time in multiple formats
datemath now --tz UTC           # In specific timezone
datemath now --json             # JSON output

Add Duration

datemath add "3 weeks"          # 3 weeks from now
datemath add "2 months"         # 2 months from now
datemath add "1 year 2 months"  # Combine units
datemath add "5 days" --from "2026-01-01"  # From specific date

Subtract Duration

datemath sub "1 week"           # 1 week ago
datemath sub "3 months"         # 3 months ago

Between Dates

datemath between "2026-01-01" "2026-12-31"  # Days/weeks/months between
datemath between "today" "2026-12-25"       # Until Christmas
datemath between "yesterday" "tomorrow"     # 2 days

Parse Natural Language

datemath parse "next tuesday"    # Parse to ISO date
datemath parse "tomorrow"        # Tomorrow's date
datemath parse "in 3 weeks"      # 3 weeks from now
datemath parse "2 days ago"      # 2 days ago
datemath parse "last friday"     # Previous Friday

Format Dates

datemath format "2026-02-03" --fmt "%B %d, %Y"     # February 03, 2026
datemath format "tomorrow" --fmt "%A"              # Weekday name
datemath format "now" --fmt "%Y%m%d_%H%M%S"        # Filename-safe

Timezone Conversion

datemath tz "2026-02-03T12:00" --from UTC --to America/Los_Angeles
datemath tz "now" --from America/New_York --to Europe/London
datemath zones  # List common timezones with current time

Duration Syntax

Supported units:

• y, year, years — Years
• mo, month, months — Months
• w, week, weeks — Weeks
• d, day, days — Days
• h, hour, hours — Hours
• m, min, minute, minutes — Minutes
• s, sec, second, seconds — Seconds

Combine freely: "1 year 2 months 3 days", "1y 2mo 3d", "90 days"

JSON Output

All commands support --json for machine-readable output:

datemath now --json

{
  "iso": "2026-02-03T12:00:00",
  "unix": 1770184800,
  "date": "2026-02-03",
  "time": "12:00:00",
  "human": "February 03, 2026 at 12:00 PM",
  "weekday": "Tuesday",
  "timezone": "local"
}

For AI Agents

See SKILL.md for agent-optimized documentation.

License

MIT