Dead Simple CLI Timer (dstimer)

A dead-simple, cross-platform CLI countdown timer featuring:

• Color-changing progress bar
• Fullscreen / Inline mode
• Optional audio playback
• Optional HTTP webhook
• Optional notifications on finish
• YAML-based presets and defaults.

Written in Rust for maximum efficiency and portability.

_{Demo with 7 seconds as argument (Fullscreen)}

_{Demo with pomodoro preset (Inline)}

Table of Contents

• Features
• Usage
  • TUI / Interactive mode
  • Fullscreen mode
  • Inline mode
• Configuration
  • defaults.yaml
  • presets.yaml
• Install
• Supported Audio Formats
• Build from Source
• Contributing
• Acknowledgements

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 ♪
• Optional HTTP call (--url) — fires a GET request on finish and shows the response
• YAML presets — save named presets (e.g. dstimer pomodoro) in ~/.dstimer/presets.yaml
• Global defaults — set default audio, URL, inline/silent in ~/.dstimer/defaults.yaml

Usage

Flag	Short	Description
--time	-t	Duration in HH:MM:SS, MM:SS, or SS format
--audio	-a	Path to audio file to play on finish
--url	-u	URL to call (HTTP GET) when timer finishes
--inline	-i	Inline mode (see below)
--silent		Suppress desktop notifications

The positional argument can be a time value (dstimer 25:00) or a preset name (dstimer pomodoro). See Configuration below.

TUI / Interactive mode (no arguments):

dstimer

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

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
dstimer 5:00 --url https://example.com/hook # fires HTTP GET after 5 minutes
dstimer pomodoro # loads named preset
dstimer pomodoro -t 30:00 # preset with CLI time override

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.

Configuration

dstimer automatically creates ~/.dstimer/ with two YAML files on first run.

defaults.yaml — Global defaults

These values apply to every run unless overridden by a preset or CLI flags.

inline: false
silent: false
audio: ""
url: ""

When audio or url are set here, the interactive TUI skips those prompts automatically.

presets.yaml — Named presets

Define reusable timer presets and call them by name:

pomodoro:
  time: "25:00"
  inline: true
  silent: false
  audio: "/home/user/music/bell.flac"
  url: "https://example.com/pomodoro-done"

break:
  time: "5:00"
  silent: true

Then just run:

dstimer pomodoro           # uses all preset values, starts immediately
dstimer break              # 5-minute silent break timer
dstimer pomodoro -t 30:00  # override just the time

All fields in a preset entry are optional. Missing fields fall back to defaults.yaml.

Priority order: CLI flags > preset > defaults.yaml

Install

Linux / macOS Install Script

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

macOS

homebrew

brew install madLinux7/tap/dstimer 

Windows

Winget:

winget install madLinux.dstimer

PowerShell Install Script:

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, ...)
• ureq — lightweight HTTP client
• serde + serde_yaml — YAML configuration
• 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 sick custom terminal GIFs!