https://github.com/borhansaflo/epoch-time
A CLI tool to print and manipulate Unix epoch timestamps
https://github.com/borhansaflo/epoch-time
cli epoch-time rust terminal tool
Last synced: 5 months ago
JSON representation
A CLI tool to print and manipulate Unix epoch timestamps
- Host: GitHub
- URL: https://github.com/borhansaflo/epoch-time
- Owner: BorhanSaflo
- License: mit
- Created: 2026-01-13T00:19:21.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-13T14:42:23.000Z (6 months ago)
- Last Synced: 2026-01-18T00:23:36.439Z (5 months ago)
- Topics: cli, epoch-time, rust, terminal, tool
- Language: Rust
- Homepage:
- Size: 24.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# epoch-time (et)
epoch-time is a CLI tool that prints and manipulates Unix epoch timestamps. All operations use UTC. Timestamps are integers representing seconds since 1970-01-01T00:00:00Z.
With no arguments, print the current epoch. With a duration argument,
apply the offset to the current epoch. With an epoch and duration,
apply the offset to the given epoch.
When standard input is not a terminal, read epoch timestamps from
stdin (one per line) and apply any duration offset to each.
## Installation
### Using Cargo
```bash
cargo install epoch-time
```
### Using Installers
Download pre-built binaries from the [GitHub Releases](https://github.com/BorhanSaflo/epoch-time/releases) page.
### Using brew
```bash
brew tap BorhanSaflo/epoch-time
brew install et
```
### Using Nix
Run directly without installing:
```bash
nix run github:BorhanSaflo/epoch-time
```
Install to your profile:
```bash
nix profile install github:BorhanSaflo/epoch-time
```
Or add to your Nix configuration:
```nix
{
inputs.epoch-time.url = "github:BorhanSaflo/epoch-time";
}
```
Then add `inputs.epoch-time.packages.${system}.default` to your packages.
### Build from source
Clone the repository and build with Cargo:
```bash
git clone https://github.com/BorhanSaflo/epoch-time.git
cd epoch-time
cargo build --release
# The binary will be available at target/release/et
```
## Motivation
I needed a simple tool to quickly generate epoch timestamps for URL queries. The date command can do this, but its syntax varies across implementations (GNU coreutils on Linux, BSD on macOS, and others), making it inconvenient for quick, portable use. This tool provides a fast and consistent way to generate epoch timestamps. Here's an example of how it can be used:
```
curl "https://api.example.com/data?start=$(et now)&end=$(et now +7d)"
```
## Usage
- `et now [OFFSET]` Print current epoch timestamp, optionally applying an offset
- `et [OFFSET]` Print an epoch timestamp with an optional offset
- `et parse ` Convert ISO-8601 timestamp (UTC required) to epoch
- `et format ` Convert epoch to ISO-8601 UTC
## Duration Units
| Unit | Value |
|------|------------------|
| s | 1 second |
| m | 60 seconds |
| h | 3600 seconds |
| d | 86400 seconds |
| w | 604800 seconds |
| M | 1 month |
| Y | 1 year |
Months and years use calendar arithmetic. Days are clamped to valid
range for the target month (e.g., Jan 31 + 1M = Feb 28).
## Examples
Print current epoch:
et
Subtract 7 days:
et -7d
Add 3 hours:
et +3h
Add 1 month:
et +1M
Subtract 1 year:
et -1Y
Add 1 hour to a specific epoch:
et 1704912345 +1h
Convert ISO-8601 to epoch:
et parse 2026-01-05T12:00:00Z
Convert epoch to ISO-8601:
et format 1704912345
Apply offset to timestamps from stdin:
cat timestamps.txt | et -1d
## License
MIT