Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/open-pomodoro/openpomodoro-cli
A command-line Pomodoro tracker which uses the Open Pomodoro Format
https://github.com/open-pomodoro/openpomodoro-cli
pomodoro pomodoro-cli pomodoro-timer
Last synced: about 2 months ago
JSON representation
A command-line Pomodoro tracker which uses the Open Pomodoro Format
- Host: GitHub
- URL: https://github.com/open-pomodoro/openpomodoro-cli
- Owner: open-pomodoro
- License: mit
- Created: 2016-11-12T00:59:33.000Z (about 8 years ago)
- Default Branch: main
- Last Pushed: 2024-02-27T06:11:31.000Z (10 months ago)
- Last Synced: 2024-08-01T16:27:59.696Z (5 months ago)
- Topics: pomodoro, pomodoro-cli, pomodoro-timer
- Language: Go
- Homepage:
- Size: 3.11 MB
- Stars: 322
- Watchers: 7
- Forks: 25
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Open-Pomodoro CLI
> A command-line Pomodoro tracker which uses the [Open Pomodoro Format](https://github.com/open-pomodoro/open-pomodoro-format/blob/master/README.md)
## Table of Contents
* [Installation](#installation)
* [Usage](#usage)
* [Start a Pomodoro](#start-a-pomodoro)
* [Amend the current Pomodoro](#amend-the-current-pomodoro)
* [Check the status of the current Pomodoro](#check-the-status-of-the-current-pomodoro)
* [Clear a finished Pomodoro](#clear-a-finished-pomodoro)
* [Cancel an active Pomodoro](#cancel-an-active-pomodoro)
* [Finish a Pomodoro early (or late)](#finish-a-pomodoro-early-or-late)
* [Take a break](#take-a-break)
* [Repeat the last Pomodoro](#repeat-the-last-pomodoro)
* [Show Pomodoro history](#show-pomodoro-history)
* [Tmux Color](#tmux-color)
* [Status Format](#status-format)
* [Available Parts](#available-parts)
* [Hooks](#hooks)
## Installation
1. Download the latest package for your platform from the [Releases page](https://github.com/open-pomodoro/openpomodoro-cli/releases/latest).
2. Untar the package with `tar -zxvf openpomodoro-cli*.tar.gz`.
3. 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](https://golang.org/doc/install):
```
go install github.com/open-pomodoro/openpomodoro-cli/cmd/pomodoro@latest
```
> If you already have another command named `pomodoro`, use `go get github.com/open-pomodoro/openpomodoro-cli` to install the `openpomodoro-cli` command.
## Usage
### Start a Pomodoro
```
$ 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
```
### Amend the current Pomodoro
```
$ 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
```
### Check the status of the current Pomodoro
```
$ 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 [](#status-format) below for documentation on the status format string.
### Clear a finished Pomodoro
```
$ pomodoro status
❗🍅
$ pomodoro clear
$ pomodoro status
```
### Cancel an active Pomodoro
```
$ pomodoro status
12:34 🍅
$ pomodoro cancel
$ pomodoro status
```
### Finish a Pomodoro early (or late)
```
$ pomodoro status
1:23 🍅
$ pomodoro finish
23:37
$ pomodoro status
❗️🍅
```
### Take a break
```
$ pomodoro break
4:59
$ pomodoro break 15
14:59
```
### Repeat the last Pomodoro
```
$ 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
```
### Show Pomodoro history
```
$ 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
`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:
```tmux
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
```
## Status Format
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
```
### Available Parts
```
# 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
```
## Hooks
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 over
* `cancel`: `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:
```sh
#!/usr/bin/env bash
set -exo pipefail
say "Pomodoro started"
```
```shellsession
$ chmod +x ~/.pomodoro/hooks/start
```