dstimer 1.0.0

A dead-simple, cross-platform CLI countdown timer with color-changing progress bar and optional audio playback
dstimer-1.0.0 is not a library.

Dead Simple CLI Timer (dstimer)

Rust License Platform

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.

Demo with only seconds as argument

Features

  • Centered, full-width progress bar that shifts green → yellow → red as time runs out
  • Fullscreen (default) or inline mode
  • Interactive time entry (HH:MM:SS)
  • Optional audio file playback when the timer completes

Usage

Fullscreen mode

dstimer --seconds 300
dstimer -s 90 --audio /path/to/audio.wav
dstimer --time 1:30:00
dstimer -t 5:00 --inline
Flag Short Description
--time -t Duration in HH:MM:SS, MM:SS, or SS format
--seconds -s Duration in seconds
--audio -a Path to audio file to play on finish
--inline -i Inline mode (see below)
--silent Suppress desktop notifications

Demo with seconds and audio as arguments

Interactive mode (no arguments):

dstimer

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

demo_manual

Inline mode (--inline / -i):

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

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.

Demo inline with -i -t 00:00:07 args Demo inline with -i -t 00:00:07 -a "home/linuxg/Musik/Super Survivor.flac" args Demo inline interactive mode

Install

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/madLinux7/dead-simple-cli-timer/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/madLinux7/dead-simple-cli-timer/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/dead-simple-cli-timer
cd dead-simple-cli-timer
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 ♥️

Support Me

If you like using dstimer in your daily routine, consider buying me a coffee or sending a tip:

Ko-fi · Bitcoin · Monero · Ethereum · Solana · Litecoin · Cardano · XRP

Made with ♥️ by Linus Grolmes