⏱ Comodoro

CLI to manage timers

Table of contents

• Features
• Installation
  • Pre-built binary
  • Cargo
  • Nix
  • Sources
• Configuration
• FAQ
• Social
• Sponsoring

Features

• Centralized server timer controllable by multiple clients at the same time
• Multi protocols (Unix sockets and TCP only supported for now)
• Cycles customizable via config file (Pomodoro style, 52/17 style, custom)
• Server and timer hooks customizable via config file (send system notification or run shell command)

Comodoro CLI is written in Rust, and relies on cargo features to enable or disable functionalities. Default features can be found in the features section of the Cargo.toml, or on docs.rs.

Installation

Pre-built binary

Comodoro CLI can be installed with the install.sh installer:

As root:

curl -sSL https://raw.githubusercontent.com/pimalaya/comodoro/master/install.sh | sudo sh

As a regular user:

curl -sSL https://raw.githubusercontent.com/pimalaya/comodoro/master/install.sh | PREFIX=~/.local sh

These commands install the latest binary from the GitHub releases section.

If you want a more up-to-date version than the latest release, check out the releases GitHub workflow and look for the Artifacts section. You will find a pre-built binary matching your OS. These pre-built binaries are built from the master branch.

Such binaries are built with the default cargo features. If you need more features, please use another installation method.

Cargo

Comodoro CLI can be installed with cargo:

cargo install comodoro --locked

With only server support:

cargo install comodoro --locked --no-default-features --features server

You can also use the git repository for a more up-to-date (but less stable) version:

cargo install --locked --git https://github.com/pimalaya/comodoro.git

Nix

Comodoro CLI can be installed with Nix:

nix-env -i comodoro

You can also use the git repository for a more up-to-date (but less stable) version:

nix-env -if https://github.com/pimalaya/comodoro/archive/master.tar.gz

Or, from within the source tree checkout:

nix-env -if .

If you have the Flakes feature enabled:

nix profile install comodoro

Or, from within the source tree checkout:

nix profile install

You can also run Comodoro directly without installing it:

nix run comodoro

Sources

Comodoro CLI can be installed from sources.

First you need to install the Rust development environment (see the rust installation documentation):

curl https://sh.rustup.rs -sSf | sh

Then, you need to clone the repository and install dependencies:

git clone https://github.com/pimalaya/comodoro.git
cd comodoro
cargo check

Now, you can build Comodoro:

cargo build --release

Binaries are available under the target/release folder.

Configuration

The wizard is not yet available (it should come soon), meanwhile you can manually edit your own configuration from scratch:

• Copy the content of the documented ./config.sample.toml
• Paste it into a new file ~/.config/comodoro/config.toml
• Edit, then comment or uncomment the options you want

FAQ

How to debug Comodoro CLI?

The simplest way is to use --debug and/or --trace arguments.

The advanced way is based on environment variables:

• RUST_LOG=<level>: determines the log level filter, can be one of off, error, warn, info, debug and trace.
• RUST_BACKTRACE=1: enables the full error backtrace, which include source lines where the error originated from.

Logs are written to the stderr, which means that you can redirect them easily to a file:

comodoro server start --debug 2>/tmp/comodoro.log

Social

• Chat on Matrix
• News on Mastodon or RSS
• Mail at pimalaya.org@posteo.net

Sponsoring

Special thanks to the NLnet foundation and the European Commission that have been financially supporting the project for years:

• 2022: NGI Assure
• 2023: NGI Zero Entrust
• 2024: NGI Zero Core (still ongoing in 2026)

If you appreciate the project, feel free to donate using one of the following providers: