clck 0.1.8

A responsive cross-platform countdown alarm for the terminal.
Documentation

clck

A responsive cross-platform countdown alarm for the terminal.

Read the full documentation at gkk-dev-ops.github.io/clck.

Officially supported on macOS and Linux. Windows support is best-effort.

Installation

Cargo/crates.io is the best option for Rust users:

cargo install clck --locked

GitHub Releases are best for users who want prebuilt binaries. Download the archive for your platform from the latest GitHub Release, verify it using SHA256SUMS, and place the extracted executable on PATH.

Release archives use these names:

  • clck-vX.Y.Z-macos-aarch64.tar.gz
  • clck-vX.Y.Z-macos-x86_64.tar.gz
  • clck-vX.Y.Z-linux-aarch64-musl.tar.gz
  • clck-vX.Y.Z-linux-x86_64-musl.tar.gz
  • clck-vX.Y.Z-windows-x86_64.zip

After either installation method, the command is clck.

Usage

Pass the countdown duration directly:

clck 45
clck 45s
clck 10m
clck 1h30m
clck 01:30:00
clck --help

Numbers without a unit are seconds. Compact durations such as 1H30 mean one hour and thirty minutes. Duration units are case-insensitive.

Running clck without a duration opens guided interactive setup. Interactive title, font, sound, and notification choices can be saved as defaults.

Options

clck 5m --title "Pizza"
clck 5m -t "Pizza"
clck 5m --sound ~/Music/alarm.mp3
clck 5m --sound ~/Movies/alarm.mp4
clck 5m --font banner
clck 5m --no-notification

MP3, WAV, FLAC, OGG, and AIFF play natively. Other formats, including MP4, require ffmpeg to be installed.

The default sound is resolved by logical name from installed OS sounds. macOS defaults to Glass; Linux discovers freedesktop sound themes. If no sound is available, the terminal bell is used.

Commands

clck fonts
clck sounds
clck config --show
clck config --reset
clck --help

Configuration is stored in the platform-standard application config directory. Command-line options override saved defaults.

Controls

  • During countdown: q, Esc, or Ctrl+C cancels.
  • While ringing: any key dismisses the alarm.

The timer selects the largest bundled ASCII font that fits and redraws when the terminal is resized. Terminal mode and cursor visibility are restored on normal exit, cancellation, dismissal, and errors.

Development

cargo test
cargo clippy --all-targets -- -D warnings
cargo build --release

See docs/manual-testing.md for platform smoke tests and docs/releases.md for GitHub Release operations.