doro-cli

A minimal, keyboard-first, full-screen terminal Pomodoro timer with soft pastel themes and synthetic 8-bit audio cues.

Focus on your work, not your timer.

Features

• Distraction-Free UI: Full-screen, minimalist design keeps you focused.
• Keyboard-First: Navigate and control everything from your keyboard.
• Responsive Layout: Adapts to any terminal size, from tiny to wide.
• Color Themes: Switch between modern and calm themes with a keypress.
• Audio Cues: Lightweight, generated 8-bit sounds for timer events (no media files needed).
• Mouse Support: Optional mouse control for key actions.

Gallery

Small	Medium (Text Hints)	Medium (Icon Hints)	Wide

Installation

Requires Node.js >= 22.

npm install -g doro-cli

Once installed, just run doro in your terminal!

Quick Start (Build from source)

# Clone the repository
git clone https://github.com/dnim/doro-cli.git
cd doro-cli

# Install dependencies
npm install

# Build the project
npm run build

# Run it!
node dist/cli.js

Development

Run in development mode with hot-reloading:

npm run dev

Global Install (Optional)

To run doro from anywhere:

npm link
doro

Controls

Key	Action
q	Quit
p or Space	Pause / Resume
r	Reset Timer
c	Toggle Color Scheme
m	Mute / Unmute
w	Start Work Timer
s	Start Short Break
l	Start Long Break
L	Lock / Unlock Hotkeys
Shift+R	Reset All Settings
Shift+D	Debug: Fast-forward timer

Configuration

doro-cli automatically saves your settings (volume mode and color scheme) to a persistent configuration file.

• Settings Location:
  • macOS: ~/Library/Preferences/doro-cli-nodejs/settings.json
  • Linux: ~/.config/doro-cli-nodejs/settings.json
  • Windows: %LOCALAPPDATA%\doro-cli-nodejs\Config\settings.json

To reset all settings to their factory defaults, press Shift+R within the app.

Behavior

• A long break is offered every 3 completed work sessions.
• When a timer finishes, you have 60 seconds to confirm the next mode before it auto-starts.

🚀 Publishing a Release

This project uses release-it to automate versioning, Git tagging, GitHub Releases, and npm publishing.

To create a new release, ensure your working directory is clean, then run:

npm run release

The interactive wizard will guide you through:

• Selecting the next version (patch, minor, major).
• Committing the version bump in package.json.
• Creating a Git tag.
• Pushing the commit and tag to GitHub.
• Creating an official GitHub Release.
• Publishing the package to npm.

Contributing

Contributions are welcome! Please keep pull requests small and focused.

Before submitting, please run:

npm run lint:local
npm run typecheck
npm run test:unit

---

Made with love and TypeScript