tmr-cli

A featureful command-line timer and stopwatch for your terminal. Count down, count up, wait until a specific clock time, get desktop notifications, query progress live while it runs, and pick up right where you left off after closing the tool — all from one small, fast binary.

Features

• Countdown (--wait) — wait for a duration, then send a desktop notification.
• Wait until a clock time (--wait-to) — wait until a specific HH:MM:SS today, then notify.
• Stopwatch (--count) — count elapsed time indefinitely, with no target duration.
• Resume (--load) — reload the last saved timer and pick up where it left off.
• Count time while closed (--count-inactive) — when resuming, add the wall-clock time that passed while the tool wasn't running.
• Silent mode (--silenced) — suppress the desktop notification when a timer finishes.
• Background input (--background-input) — while a timer runs, read commands from stdin to query progress without stopping it.
• Flexible duration parsing — chain units like 1h+30m for readable, composable durations.
• State persistence — the current timer is saved to disk after every tick, so it survives a restart.
• Cross-platform notifications — desktop alerts on Linux, macOS, and Windows via notify-rust.

Installation

From crates.io (recommended)

cargo install tmr-cli

This installs the timer-cli binary to your Cargo bin directory (usually ~/.cargo/bin), which should already be on your PATH.

From source

git clone https://github.com/honerop/timer-cli.git
cd timer-cli
cargo build --release

The resulting binary will be in target/release/.

Usage

timer-cli [OPTIONS]

Flags and options

Exactly one of --wait, --wait-to, --count, or --load should be provided; the tool checks them in that priority order.

Duration format (--wait)

Durations are written as a number immediately followed by a unit, and multiple durations can be chained with +:

Examples:

timer-cli --wait 30s
timer-cli --wait 1h+30m
timer-cli --wait 90m+15s

Wait-to format (--wait-to)

Takes a 24-hour clock time as HH:MM:SS and waits until that time is reached:

timer-cli --wait-to 18:30:00

Examples

Count down 25 minutes (a Pomodoro), notify when done:

timer-cli --wait 25m

Count down, but suppress the notification:

timer-cli --wait 10m --silenced

Wait until 09:00:00, accounting for lost time if the tool was closed and reopened:

timer-cli --wait-to 09:00:00
timer-cli --load --count-inactive

Run a stopwatch with a background query interface:

timer-cli --count --background-input

While --background-input is active, you can type commands on stdin:

elapsed --format seconds
left --format minutes

--format accepts: nanoseconds, microseconds, milliseconds, seconds (default), minutes, hours, days.

Persistence

While a timer runs, its state (elapsed time, target duration, task type, and a timestamp) is written to:

<platform data dir>/.tasks/tasks.json

Notifications

Desktop notifications are sent via notify-rust when a --wait or --wait-to timer completes. Pass -s/--silenced to disable this.

Project Structure

timer-cli
├── src
│   ├── main.rs               # CLI argument parsing and dispatch
│   ├── handlers.rs           # Core logic for wait, wait-to, count, and load commands
│   ├── task.rs               # TaskState — tracks elapsed/target duration and task type
│   ├── magazine.rs           # Save/load of task state to/from tasks.json
│   ├── time.rs               # Duration and HH:MM:SS string parsing
│   └── background_input.rs   # Stdin-driven interface for querying a running timer
└── Cargo.toml                 # Project configuration

License

MIT