A tiny macOS alarm/timer CLI — set a relative or absolute time, get a notification and a sound when it fires

Features • Quick Start • CLI Reference • Development

Originally built to remember when Claude's usage quota resets — ding 5h "quota is back" and forget about it.

---

🌟 Features

• ⏱ Relative and absolute times — 5h, 90m, 1h30m, 30s, 14:30, 2:30pm, 9am; absolute times already past today roll to tomorrow
• 🔔 Desktop notifications — zero-dependency setup; ships with node-notifier which vendors its own terminal-notifier, no brew install required
• 🔊 Built-in alarm presets — six synthesised sounds (beep, digital, radar, bell, siren, chime), macOS Clock ringtones (e.g. Radial, Daybreak, Arpeggio), macOS system sounds, or any audio file via afplay
• 🧙 Interactive wizard — ding with no arguments launches a tabbed TUI (When · Message · Sound · Notify · Mode · Review); press Space on the Sound step to preview before choosing
• 🔗 Click-to-open notifications — --open https://claude.ai makes the notification banner a shortcut to any URL
• 🖥 Foreground and detached modes — live countdown with progress bar by default; --detach backgrounds the process and returns the prompt immediately

---

🚀 Quick Start

Install globally:

npm install -g @kud/ding-cli

Or run without installing:

npx @kud/ding-cli 5h "quota is back"

Set a timer and watch the countdown:

$ ding 90m "tea is ready"
ding → 16:37:22 · tea is ready
01:29:58 ▸ tea is ready

When it fires, the terminal rings (loops the alarm) until you press any key to dismiss, and a desktop notification pops up.

---

📖 CLI Reference

ding <time> [message] [options]

Time formats

Format	Example	Meaning
Relative — hours	5h	5 hours from now
Relative — minutes	90m	90 minutes from now
Relative — seconds	30s	30 seconds from now
Relative — compound	1h30m	1 hour 30 minutes from now
Bare number	45	45 minutes from now
24-hour clock	14:30	fires at 14:30 today (or tomorrow if past)
12-hour clock	2:30pm	fires at 14:30
Hour only	9am	fires at 09:00

Options

Flag	Alias	Description
--detach	-d	Background the process; prints fire time then returns the prompt
--sound <value>	-s	Alarm preset (beep digital radar bell siren chime), macOS Clock ringtone name (e.g. Daybreak; quote names with spaces like "Milky Way"), macOS system sound name (e.g. Glass), or path to an audio file. Default: bell
--no-sound		Disable alarm sound entirely
--no-notify		Disable desktop notification
--title <text>		Notification title (default: ding)
--subtitle <text>		Notification subtitle
--icon <path>		Absolute path to a custom notification icon image
--open <url>		URL to open when the notification banner is clicked
--notify-sound <name>		Notification banner sound (e.g. Glass, Ping) — distinct from --sound, which plays via afplay
--icons <mode>		Icon set: nerd (default, requires Nerd Font), emoji, or ascii. Also set via DING_ICONS env var
-i / --interactive		Force-launch the interactive wizard
--help	-h	Show help
--version	-V	Show version

Examples

# Relative timer with a message
ding 90m "tea is ready"

# Absolute time
ding 14:30 "stand-up"

# Fires at 9 am — rolls to tomorrow if 9 am has already passed
ding 9am

# Open claude.ai when the notification is clicked
ding 5h "quota is back" --open https://claude.ai --subtitle "Anthropic"

# Background the process, return the prompt immediately
ding 5h "quota is back" --detach

# Silent notification (no alarm sound)
ding 30m "check the oven" --no-sound

# macOS Clock alarm ringtone (played locally via afplay; quote names with spaces)
ding 5h "wake" --sound Daybreak
ding 5h "wake" --sound "Milky Way"

# Notification banner's own macOS sound (separate from the afplay alarm)
ding 30m "stand-up" --notify-sound Glass

# Custom audio file
ding 20m "deploy done" --sound ~/Downloads/alert.aiff

# Use emoji icons (no Nerd Font required)
ding 5m "test" --icons emoji

# Or set permanently in your shell profile
export DING_ICONS=emoji

Recipe: ring when Claude's usage quota resets

ding was born to time Claude's 5-hour usage window — but instead of guessing 5h, read the exact reset time from ccusage, which parses Claude Code's local logs. Pipe its active-block remainingMinutes straight into ding:

mins=$(ccusage blocks --active --json --offline | node -e 'const {blocks=[]}=JSON.parse(require("node:fs").readFileSync(0));const a=blocks.find(b=>b.isActive);process.stdout.write(String(a?.projection?.remainingMinutes??""))')
[ -n "$mins" ] && ding "${mins}m" "Claude quota is back 🎉"

--offline keeps it fast (no network), and remainingMinutes is already relative, so there is no timezone maths to get wrong.

Interactive wizard

Running ding with no time argument (or with -i) launches a tabbed wizard:

ding  When · Message · Sound · Notify · Mode · Review

Navigate between tabs with ← / →. On the Sound step, use ↑ / ↓ to browse presets, macOS Clock ringtones, and system sounds, and press Space to preview a sound before confirming with ↵.

Icon sets

The countdown display and fired state use glyphs from the active icon set:

Mode	Activate	Requires
nerd	default	a Nerd Font-patched terminal font
emoji	--icons emoji or DING_ICONS=emoji	any modern terminal
ascii	--icons ascii or DING_ICONS=ascii	nothing

--icons takes precedence over DING_ICONS. If your font is not Nerd Font-patched, add export DING_ICONS=emoji to your shell profile.

Foreground mode (default)

Without --detach, the terminal renders a live countdown. When the timer fires it rings continuously until you press any key:

$ ding 5m "quota is back"
ding → 16:42:00 · quota is back
04:59:58 ▸ quota is back

Detach mode

$ ding 5h "quota is back" --detach
ding → 21:00:00 (detached)
$

The process runs silently in the background and fires the notification and alarm at the target time — no terminal required.

---

🔧 Development

ding-cli/
├── src/
│   ├── index.ts          # CLI entry point and argument definitions
│   ├── countdown.ts      # Foreground countdown rendering loop
│   ├── detach.ts         # Background process spawning
│   ├── icons.ts          # Icon sets (nerd / emoji / ascii)
│   ├── notify.ts         # Desktop notification wrapper
│   ├── parse-time.ts     # Relative and absolute time parsing
│   ├── preview-sound.ts  # Sound preview during wizard
│   ├── sounds.ts         # Alarm presets (WAV synthesis) + system sound resolution
│   ├── ui/               # TUI primitives (tabs, footer hints)
│   └── wizard/           # Interactive wizard (Ink/React)
└── dist/                 # Compiled output (tsup → ESM)

Scripts

Command	Description
npm run dev	Run from TypeScript source via tsx
npm run build	Compile to dist/ with tsup
npm run build:watch	Watch mode compilation
npm run typecheck	TypeScript type-check without emitting
npm run lint	ESLint
npm run format	Prettier

Setup

git clone https://github.com/kud/ding-cli.git
cd ding-cli
npm install
npm run dev -- 5s "test alarm"

After npm link, the ding binary resolves to the compiled dist/index.js (run npm run build first).

---

🏗 Tech Stack

Package	Role
ink	React renderer for the terminal
@inkjs/ui	Text input and select components
citty	CLI argument parsing
node-notifier	macOS desktop notifications (vendors terminal-notifier)
chalk	Terminal colour output
tsup	ESM build
tsx	TypeScript execution for development

---

MIT © kud — Made with ❤️