A command-line Pomodoro tracker which uses the Open Pomodoro Format
- Download the latest package for your platform from the Releases page.
- Untar the package with
tar -zxvf openpomodoro-cli*.tar.gz
. - Move the extracted
openpomodoro-cli
file to a directory in your$PATH
(for most systems, this will be/usr/local/bin/
).
Or, if you have a Go development environment:
go get -u github.com/open-pomodoro/openpomodoro-cli/cmd/pomodoro
If you already have another command named
pomodoro
, usego get github.com/open-pomodoro/openpomodoro-cli
to install theopenpomodoro-cli
command.
$ pomodoro start
25:00 🍅
# Start a Pomodoro in the past
$ pomodoro start --ago 10m
15:00 🍅
# Set the Pomodoro duration in minutes
$ pomodoro start --duration 30
30:00 🍅
# Set the Pomodoro duration in seconds
$ pomodoro start --duration 22m30s
22:30 🍅
# Provide a description and tags
$ pomodoro start "Blog post" -t writing,personal
25:00 🍅
Blog post
writing,personal
# Block until the Pomodoro finishes
$ pomodoro start --wait
25:00 🍅
24:99
$ pomodoro start "Blog postt" --tags writing,personal
25:00 🍅
Blog postt
writing,personal
# Pass any options accepted by start. Only passed options will be changed.
$ pomodoro amend "Blog post"
24:30 🍅
Blog post
writing,personal
$ pomodoro status
12:34 🍅
# When the Pomodoro has finished
$ pomodoro status
❗🍅
# Customize the status format
$ pomodoro status -f "%mr %c/%g 🍅"
12 🍅 2/8
# Block until the Pomodoro finishes
$ pomodoro status --wait
12:34 🍅
12:33
See below for documentation on the status format string.
$ pomodoro status
❗🍅
$ pomodoro clear
$ pomodoro status
$ pomodoro status
12:34 🍅
$ pomodoro cancel
$ pomodoro status
$ pomodoro status
1:23 🍅
$ pomodoro finish
23:37
$ pomodoro status
❗️🍅
$ pomodoro break
4:59
$ pomodoro break 15
14:59
$ pomodoro repeat
25:00 🍅
Writing a blog post
writing,personal
# Block until the Pomodoro finishes
$ pomodoro repeat --wait
25:00 🍅
Writing a blog post
writing,personal
24:59
$ pomodoro history
2015-06-14T12:34:00-04:00 description="Blog post" duration=25 tags=writing,personal
# Output in JSON format
$ pomodoro history --output json
{
"pomodoros": [
{
"start_time": "2015-06-14T12:34:56-04:00",
"description": "Blog Post",
"duration": 25,
"tags": [
"writing",
"personal"
]
}
]
}
# Output in iCal format
$ pomodoro history --output ical > ~/Pomodoros.ics
tmux-color
returns a color for the current Pomodoro status.
# Active Pomodoro
$ pomodoro tmux-color
colour2 # Green
# Finished Pomodoro
$ pomodoro tmux-color
colour1 # Red
Nothing is output if no Pomodoro is active.
Colors can be used within a Tmux configuration like so:
set -g status-left '#[bg=#(pomodoro tmux-color)]🍅'
You can also define custom colors:
# Active Pomodoro
$ pomodoro tmux-color --active colour166 --done colour165
colour166 # Orange
# Finished Pomodoro
$ pomodoro tmux-color --active colour166 --done colour165
colour165 # Purple
All commands which display the status of a single Pomodoro can take an additional --format
/ -f
argument.
This argument controls how to display the Pomodoro.
By default, it displays the time remaining (or an Emoji exclamation point if zero), an Emoji tomato, the description, and tags. Consecutive spaces and newlines are de-duplicated.
$ pomodoro status
12:34 🍅
Writing a blog post
writing,personal
$ pomodoro status --format "%R ⏱ %c/%g 🍅\n%d"
13 ⏱ 2/8 🍅
Writing a blog post
# Time
%r - Time remaining in mm:ss
%R - Time remaining in minutes, rounded
%!r - Same as %r, but with an exclamation point if the Pomodoro is done
%!R - Same as %R, but with an exclamation point if the Pomodoro is done
%l - Length of the Pomodoro in mm:ss
%L - Length of the Pomodoro in minutes
# Metadata
%d - Pomodoro description
%t - Pomodoro tags, joined by a comma
# Goals
%g - Daily Pomodoro goal
%!g - Daily Pomodoro goal, with a preceding slash
%c - Completed Pomodoros today
%l - Pomodoros remaining (left) to reach goal
Hooks can be run when Pomodoros change state. There are 3 possible hooks:
break
start
stop
Commands which run hooks:
break
:break
immediately,stop
when break is overcancel
:stop
clear
:stop
finish
:stop
repeat
:start
start
:start
To enable a hook, create an executable file in the hooks
subdirectory within your configuration directory. For example:
#!/usr/bin/env bash
set -exo pipefail
say "Pomodoro started"
$ chmod +x ~/.pomodoro/hooks/start