# Task Timer CLI

A small command-line timer-cli/stopwatch tool written in Rust. It can count down, count up, wait until a specific time of day, notify you when done, and resume a timer after being closed and reopened.

## Features

- **Countdown (`--wait`)** — wait for a duration, then send a desktop notification.
- **Wait until a clock time (`--wait-to`)** — wait until a specific `HH:MM:SS` today, then notify.
- **Stopwatch (`--count`)** — count elapsed time indefinitely, with no target duration.
- **Resume (`--load`)** — reload the last saved timer-cli and pick up where it left off.
- **Count time while closed (`--count-inactive`)** — when resuming, add the wall-clock time that passed while the tool wasn't running.
- **Silent mode (`--silenced`)** — suppress the desktop notification when a timer-cli finishes.
- **Background input (`--background-input`)** — while a timer-cli runs, read commands from stdin to query progress without stopping it.
- **State persistence** — the current timer-cli is saved to disk after every tick, so it survives a restart.

## Installation

Build from source with Cargo:

```bash
cargo build --release
```

The resulting binary will be in `target/release/`.

## Usage

```bash
timer-cli [OPTIONS]
```

### Flags and options

| Flag | Description |
|---|---|
| `--wait <DURATION>` | Count down for the given duration, then notify. |
| `--wait-to <HH:MM:SS>` | Count down until the given time of day, then notify. |
| `-c`, `--count` | Count up indefinitely (stopwatch mode). |
| `-l`, `--load` | Load and resume the previously saved timer-cli. |
| `-s`, `--silenced` | Don't show a notification when the timer-cli finishes. |
| `-b`, `--background-input` | Start a background stdin listener for progress queries while the timer-cli runs. |
| `--count-inactive` | When used with `--load`, add elapsed time from while the tool was closed. |

Exactly one of `--wait`, `--wait-to`, `--count`, or `--load` should be provided; the tool checks them in that priority order.

### Duration format (`--wait`)

Durations are written as a number immediately followed by a unit, and multiple durations can be chained with `+`:

| Unit | Meaning |
|---|---|
| `ns` | nanoseconds |
| `us` / `µs` | microseconds |
| `ms` | milliseconds |
| `s` | seconds |
| `m` | minutes |
| `h` | hours |
| `d` | days |

Examples:

```bash
timer-cli --wait 30s
timer-cli --wait 1h+30m
timer-cli --wait 90m+15s
```

### Wait-to format (`--wait-to`)

Takes a 24-hour clock time as `HH:MM:SS` and waits until that time is reached:

```bash
timer-cli --wait-to 18:30:00
```

### Examples

Count down 25 minutes (a Pomodoro), notify when done:

```bash
timer-cli --wait 25m
```

Count down, but suppress the notification:

```bash
timer-cli --wait 10m --silenced
```

Wait until 09:00:00, accounting for lost time if the tool was closed and reopened:

```bash
timer-cli --wait-to 09:00:00
timer-cli --load --count-inactive
```

Run a stopwatch with a background query interface:

```bash
timer-cli --count --background-input
```

While `--background-input` is active, you can type commands on stdin:

```
elapsed --format seconds
left --format minutes
```

`--format` accepts: `nanoseconds`, `microseconds`, `milliseconds`, `seconds` (default), `minutes`, `hours`, `days`.

## Persistence

While a timer-cli runs, its state (elapsed time, target duration, task type, and a timestamp) is written to:

```
<platform data dir>/.tasks/tasks.json
```

<!-- Run with `--load` to resume the most recently saved timer-cli of the same type. Add `--count-inactive` to also credit the timer with the wall-clock time that passed since it was last saved. -->

## Notifications

Desktop notifications are sent via [`notify-rust`](https://crates.io/crates/notify-rust) when a `--wait` or `--wait-to` timer-cli completes. Pass `-s`/`--silenced` to disable this.

## Project Structure

timer-cli
├src
│ ├main.rs             # CLI argument parsing and dispatch
│ ├handlers.rs          # Core logic for wait, wait-to, count, and load commands
│ ├task.rs              # TaskState — tracks elapsed/target duration and task type
│ ├magazine.rs          # Save/load of task state to/from tasks.json
│ ├time.rs              # Duration and HH:MM:SS string parsing
│ └background_input.rs  # Stdin-driven interface for querying a running timer-cli
└Cargo.toml             # Project configuration