dstimer madLinux
Use this command to install dstimer with WinGet:
winget install --id=madLinux.dstimer -e The Timer for CLI people
Loading...
README
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.
You can also install a non-audio features version with cargo no-audio-release
Demo with 7 seconds as argument (Fullscreen)
Demo with pomodoro preset (Inline)
Table of Contents
- Features
- Usage
- Configuration
- 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
Audio-free / headless Cargo install
For headless or minimal Linux systems, install without audio playback and its system audio build dependencies:
cargo install dstimer --no-default-features
> --no-default-features is a Cargo built-in flag (learned this recently, can't be renamed); in this
> project audio is the only default feature, so it is exactly equivalent to
> building without audio. For local builds you can use the shorter
> cargo no-audio / cargo no-audio-release aliases defined in
> .cargo/config.toml.
This build retains timers, presets, webhooks, and desktop notifications, but
does not provide the --audio flag or an audio prompt. Existing audio:
values in defaults.yaml and presets.yaml are ignored.
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+.
To build an audio-free binary, use cargo no-audio-release (alias for
cargo build --release --no-default-features).
Contributing
Contributions are always welcome! If you want to help, here's the workflow:
- Fork the repo and create a feature branch
cargo clippyandcargo fmtbefore opening a PR- 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!