CLI to manage timers

One server owns a timer, any number of clients drive it and watch it. This project is composed of 3 feature-gated layers:

Low-level contract: the pure timer state machine and the JSON-RPC 2.0 method surface, no_std-compatible and free of any I/O
Mid-level client and server: a blocking client over one connection, and a server owning the timer behind the listeners it binds
High-level CLI: the client and the server behind a flat command grammar, a TOML configuration and per-event hooks

Features

Shared timer: one server owns it, any number of clients drive it.
Push notifications: comodoro watch subscribes, the server pushes, nothing polls.
Local socket and TCP: either transport, or both at once.
Standard protocol: plain JSON-RPC 2.0, drivable from any language.
Pomodoro-style cycles: any named durations, looping forever or a fixed number of times.
Per-event hooks: a shell command or a desktop notification on any timer event.
Status-bar friendly: second, minute or hour precision, plus --json for scripts.

Installation

Pre-built binary

Comodoro 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.

For a more up-to-date version than the latest release, check out the releases GitHub workflow and look for the Artifacts section. These pre-built binaries are built from the master branch.

Note

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

Cargo

cargo install comodoro --locked

For a more up-to-date version than the latest release:

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

Without desktop notifications, which drops the D-Bus system dependency:

cargo install comodoro --locked \
  --no-default-features \
  --features cli

Nix

If you have the Flakes feature enabled:

nix profile install github:pimalaya/comodoro

Or run without installing:

nix run github:pimalaya/comodoro

Sources

git clone https://github.com/pimalaya/comodoro
cd comodoro
nix run

Configuration

Run comodoro with no command: it offers to generate a first account, which comodoro configure does again later. Everything beyond its presets is written by hand, against the annotated config.sample.toml.

A configuration is loaded from the first valid path among $XDG_CONFIG_HOME/comodoro/config.toml, $HOME/.config/comodoro/config.toml and $HOME/.comodororc. Override it with -c <PATH> or COMODORO_CONFIG=<PATH>, :-separated to deep-merge several files on top of the first.

An account only needs its cycles. Everything else defaults: a socket under $XDG_RUNTIME_DIR, TCP on loopback port 9999, an endless loop, a precision of one minute. Which transport a server binds is what comodoro server start [TRANSPORTS] says, and which one a client talks over is what socket.default or tcp.default says. The TCP listener is unauthenticated, so keep it on loopback unless you mean otherwise.

Usage

Generate a first account, unless you wrote the configuration by hand already:

comodoro

Start the server, which owns the timer and stays in the foreground:

comodoro server start

Then drive the timer from anywhere:

comodoro start
comodoro get
comodoro pause
comodoro resume
comodoro set 300
comodoro stop

Feed a status bar without polling, which prints the timer once and then on every change until interrupted:

comodoro watch

Every command takes an optional transport, socket or tcp, and falls back to the one the configuration marks as default. The server takes the list of transports to bind, and binds the default one when given none:

comodoro server start socket tcp
comodoro get tcp

Every command and every flag is documented behind --help. The library API is documented on docs.rs, and complete runnable programs live in ./examples.

Logs go to stderr, so they can be redirected to a file while the command output stays on stdout:

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

Use --log-file <PATH> to append them to a file directly. When --log-level is omitted the RUST_LOG environment variable is consulted, and RUST_BACKTRACE=1 adds the full error backtrace.