Timestamp Converter by langbot-team

# Timestamp Converter

Unix <-> human dates, timezones, and date math — zero dependencies.

```
python scripts/run.py to 1718700000 --tz America/New_York
python scripts/run.py to now --tz +05:30
python scripts/run.py diff 1718700000 2024-06-18T12:00:00Z
python scripts/run.py add now --hours 36 --tz Asia/Tokyo
echo 1718700000 | python scripts/run.py to - --tz UTC
```

Pure Python stdlib (`datetime`, optional `zoneinfo` with UTC fallback).


---
name: timestamp-converter
display_name: Timestamp Converter
description: "Convert between Unix timestamps and human dates across timezones and do date math (diff, add/subtract). Triggers: unix timestamp, epoch, convert date, timezone, time difference, date math."
---

# Timestamp Converter

Convert Unix timestamps to human dates across timezones and do date arithmetic.

## When to use
The user has a Unix epoch (seconds or milliseconds) or an ISO date and wants it in a readable form, in another timezone, the difference between two times, or a time +/- some duration.

## How to use
Run `scripts/run.py` with a subcommand:
- `python scripts/run.py to 1718700000 --tz America/New_York` — show the timestamp in a timezone (plus UTC, ms, ISO, weekday).
- `python scripts/run.py to now --tz +05:30` — current time in a fixed offset.
- `python scripts/run.py diff 1718700000 2024-06-18T12:00:00Z` — duration between two moments.
- `python scripts/run.py add now --hours 36 --tz Asia/Tokyo` — add/subtract a duration.

Inputs accept unix seconds, unix millis (auto-detected), ISO 8601 (with `Z`), `now`, or `-` for stdin.

## Pitfalls
- Timezones use `zoneinfo`; if a zone name is unknown (or zoneinfo is unavailable) it degrades to UTC and prints a warning. Fixed offsets like `+05:30` always work.
- Values above ~1e11 are treated as **milliseconds**; below that as **seconds**.
- Naive ISO inputs (no offset) are assumed to be UTC.