8 stable releases

1.2.5 Mar 26, 2024
1.2.4 Feb 24, 2024
1.2.3 Jan 20, 2024

#77 in Command line utilities

Download history 1/week @ 2024-01-09 6/week @ 2024-01-16 1/week @ 2024-02-13 210/week @ 2024-02-20 26/week @ 2024-02-27 8/week @ 2024-03-05 11/week @ 2024-03-12 3/week @ 2024-03-19 85/week @ 2024-03-26 21/week @ 2024-04-02 6/week @ 2024-04-09

116 downloads per month

MIT license

370KB
719 lines

 pomodoro-cli

Pomodoro Timer Command Line Interface

Pomodoro timer is a simple timer that helps you to stay focused on your tasks.

pomodoro-cli is a CLI application which implements the basic functionalities of a basic Pomodoro timer. This application was designed to be used with waybar.

Rust Crates.io License

Installation

Download binary

Cargo

$ cargo install pomodoro-cli

Features

  • Start/Stop/Pause the Timer
  • Query the Timer status
  • Add more time to a running timer.
  • Wait for the Timer to finish
  • Add custom message to the timer status
  • Triggers system notification when the Timer is finished
  • Play alarm sound when the Timer is finished
  • Easy Waybar integration
  • Customize notification icon and alarm sound
  • Allow lock screen when the timer ran out

Usage

Options for start:

  • --duration Set the duration for the timer (format: 1h 30m 15s or 10:30)
  • --add Add more time to a running timer instead of starting a new timer
  • --message Add a custom message to the timer status
  • --resume Resume a paused timer (default: disabled)
  • --notify Triggers system notification when the timer is finished (default: disabled)
  • --silent Do not play alarm sound when the timer is finished (default: enabled)
  • --wait Wait for the timer to finish (default: disabled)
  • --lock-screen Wait for the timer to finish and lock the screen once the timer is finished (default: disabled)

Start/Stop the timer

# Start the timer with default configuration (25 min with alarm sound)
$ pomodoro-cli start

# Start a 30 min timer wihout playing alarm sound, but triggering a system notification
$ pomodoro-cli start --duration "30m" --silent --notify

# Stop the timer
$ pomodoro-cli stop

Pause/Resume the timer

# Pause the Timer (calling this command again will resume the timer)
$ pomodoro-cli pause

# Resume a paused timer
$ pomodoro-cli start --resume

Add more time to a running timer

# Add 10 minutes to the timer (instead of starting a new timer)
$ pomodoro-cli start -add 10m

Query the timer status

## Get remaining time in human readable format
$ pomodoro-cli status --format human

# Get the timer status in JSON format (for Waybar integration)
$ pomodoro-cli status --format json

# Specify the timer format in digital format (10:30) -- default
$ pomodoro-cli status --format human --time-format digital

# Specify the time format in segmented format (1h 30m 15s)
$ pomodoro-cli status --format human --time-format segmented

# Specify the time format in seconds
$ pomodoro-cli status --format human --time-format seconds

Waybar integration

Waybar

Add the following module to your waybar configuration:

"custom/pomo": {
    "format": "   {}",
    "exec": "pomodoro-cli status --format json --time-format digital",
    "return-type": "json",
    "on-click": "pomodoro-cli start --add 5m --notify",
    "on-click-middle": "pomodoro-cli pause",
    "on-click-right": "pomodoro-cli stop",
    "interval": 1
},

CSS styling

The module supports three different states: running, paused and finished. You can customize the styling of each state by adding the following CSS rules to your Waybar configuration:

#custom-pomo.running {
  background: #304D30;
}

#custom-pomo.paused {
  background: #AB730A;
}

#custom-pomo.finished {
  background: #8F0808;
}

Update Waybar module immediately

If you want to signal Waybar to update the module immediately when you can add pkill -SIGRTMIN+10 waybar to the on-click commands. For example:

"custom/pomo": {
    "on-click": "pomodoro-cli start --add 5m; pkill -SIGRTMIN+10 waybar",
    "signal": 10,
}

Customization

Set custom alarm sound

If you want to use a custom alarm sound, just add a alarm.mp3 file in the ~/.config/pomodoro-cli directory.

$ mkdir -p ~/.config/pomodoro-cli
$ cp /path/to/alarm.mp3 ~/.config/pomodoro-cli/alarm.mp3

Set custom notification icon

Waybar

If you want to use a custom notification icon, just add a icon.png file in the ~/.config/pomodoro-cli directory.

$ mkdir -p ~/.config/pomodoro-cli
$ cp /path/to/icon.png ~/.config/pomodoro-cli/icon.png

Alternatives

Dependencies

~4–38MB
~553K SLoC