Dead Simple CLI Timer (dstimer)

A dead-simple, cross-platform CLI countdown timer with color-changing progress bar and optional audio playback on finish.

Written in Rust for maximum efficiency and portability.

Features

• Automatically parses HH:MM:SS, MM:SS or just seconds
• Fullscreen (default) or --inline mode
• Full-width progress bar: green → yellow → red as time runs out
• Interactive time entry (HH:MM:SS) when no arguments parsed
• ♪ Optional audio file playback when the timer completes ♪

Usage

Flag	Short	Description
--time	-t	Default argument parsing duration in HH:MM:SS, MM:SS, or SS format
--audio	-a	Path to audio file to play on finish
--inline	-i	Inline mode (see below)
--silent		Suppress desktop notifications

Interactive mode (no arguments):

dstimer

You'll be prompted to enter a duration and an optional audio file path.

Fullscreen mode

dstimer # starts interactive mode
dstimer 25:00 # 25 minutes
dstimer 7 # 7 seconds
dstimer --time 1:30:17 # 1 hour 30 minutes 17 seconds
dstimer 90 --audio /path/to/audio.wav # plays audio.wav after 90 seconds

Inline mode (--inline / -i):

dstimer --inline # interactive prompt stays inline too
dstimer 60 -i

Renders the timer on the current terminal line instead of taking over the full screen. Useful for scripts, split panes, or when you want the rest of your terminal history visible.

Install

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/madLinux7/dstimer/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/madLinux7/dstimer/main/install.ps1 | iex

Via Cargo (requires Rust):

cargo install dstimer

Supported Audio Formats

MP3, FLAC, WAV, OGG, and anything else supported by Symphonia.

Build from Source

git clone https://github.com/madLinux7/dstimer
cd dstimer
cargo build --release
./target/release/dstimer

Requires Rust 1.70+.

Contributing

Contributions are always welcome! If you want to help, here's the workflow:

1. Fork the repo and create a feature branch
2. cargo clippy and cargo fmt before opening a PR
3. Follow the existing commit style: feat:, fix:, chore:, refactor:

No formal issue template — just open one if you want to discuss an idea first.

✨ Acknowledgements ✨

dstimer couldn't be dead simple without the efforts of some great open-source projects:

• clap — CLI argument parsing
• crossterm — cross-platform terminal manipulation
• rodio — audio playback
• Symphonia — audio decoding (MP3, FLAC, WAV, OGG, ...)
• ctrlc — Ctrl+C signal handling
• notify-rust — desktop notifications on Linux & Windows
• winresource — embedding the app icon on Windows

And a special shoutout to VHS by Charm for making it dead simple to record bootyful terminal GIFs straight from a script ♥️

---

Made with ♥️ by Linus