semvec/pypi-packages huggingface dataset:
datemath-cli 0.1.0
Natural language date calculations and formatting
License: MIT
Requires Python: >=3.9
Keywords: date, time, calculator, cli, natural-language, timezone

# 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

```bash
pip install datemath-cli
```

## Usage

### Current Time

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

### Add Duration

```bash
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

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

### Between Dates

```bash
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

```bash
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

```bash
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

```bash
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:

```bash
datemath now --json
```

```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](SKILL.md) for agent-optimized documentation.

## License

MIT