Metadata-Version: 2.4
Name: tclock
Version: 1.3.0
Summary: A clock, timer, stopwatch and countdown for your terminal, built with Textual
Keywords: clock,timer,stopwatch,countdown,tui,textual,terminal
Author: Eivind Teig
Author-email: Eivind Teig <eivind.teig@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Utilities
Requires-Dist: textual>=8.0
Requires-Dist: typer>=0.15
Requires-Dist: platformdirs>=4.0
Requires-Dist: shellingham>=1.5
Requires-Dist: tzdata ; sys_platform == 'win32'
Requires-Dist: tomli>=2.0 ; python_full_version < '3.11'
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/eivl/tclock
Project-URL: Repository, https://github.com/eivl/tclock
Project-URL: Issues, https://github.com/eivl/tclock/issues
Project-URL: Original, https://github.com/race604/clock-tui
Description-Content-Type: text/markdown

# tclock

A clock, timer, stopwatch and countdown for your terminal, drawn with big block digits.
Built with [Textual](https://textual.textualize.io/). A Python port of
[race604/clock-tui](https://github.com/race604/clock-tui).

Works on Linux, macOS and Windows. Requires Python 3.10 or newer.

## Install

```shell
uv tool install tclock
# or
pipx install tclock
# or
pip install tclock
```

## Usage

```shell
tclock                 # clock (default mode)
tclock clock -z Asia/Tokyo -D      # another timezone, no date line
tclock timer -d 25m -d 5m -t Work -t Break -r
tclock stopwatch
tclock countdown -t 2027-01-01 -T "New year"
tclock -c '#e63946' -s 2           # colour and size apply to every mode
```

Keys while running:

| Key              | Action                                 |
|------------------|----------------------------------------|
| `q`, `Ctrl+C`    | quit                                   |
| `Space`          | pause / resume (timer and stopwatch)   |
| `c`              | switch to clock                        |
| `w`              | switch to stopwatch                    |
| `t`              | switch to timer (defaults from config) |
| `?`              | show / hide the key overlay            |

A key bar with the same bindings appears along the bottom whenever you touch the keyboard
or mouse and fades out after a few seconds, so the clock stays clean at rest.

Run `tclock --help` or `tclock <mode> --help` for every flag.

### Clock

`tclock clock [-z TZ] [-D] [-S] [-m]` shows the current time. `-z` takes an IANA zone such
as `Europe/Oslo`. `-D` hides the date, `-S` hides seconds, `-m` shows tenths of a second.

### Timer

`tclock timer -d 5m` counts down five minutes. Durations are a number plus `s`, `m`, `h`
or `d`. Repeat `-d` to run several durations in sequence and `-t` to title each of them.
`-r` repeats the sequence, `-P` starts paused, `-Q` quits when time is up, `-M` hides
tenths.

`-e` runs a shell command when the timer ends and shows its result in the footer:

```shell
tclock timer -d 25m -e 'notify-send tclock "Time is up"'      # Linux
tclock timer -d 25m -e 'osascript -e "display notification \"Time is up\""'   # macOS
tclock timer -d 25m -e 'msg * Time is up'                       # Windows
```

When the timer runs out the screen flashes green until you quit or switch mode.

### Stopwatch

`tclock stopwatch` counts up. Press `Space` to pause. The final time is printed to the
terminal after you quit.

### Countdown

`tclock countdown -t WHEN [-T TITLE] [-c] [-r] [-m]` shows the time until `WHEN`, which
can be `20:00`, `20:00:00` (today), `2027-01-01` (midnight), `2026-12-25 20:00:00` (local
time) or RFC 3339 such as `2026-12-25T20:00:00-04:00`. `-c` keeps counting (negative)
after the moment has passed instead of blinking `0:00`; `-r` counts up since the moment.

## Shell completion

Completion for commands and flags is available for bash, zsh, fish and PowerShell
(`powershell` and `pwsh`).

```shell
tclock --install-completion   # detects the shell, installs, and prints how to activate it now
tclock completion             # checks whether it is installed, up to date and active here
tclock --show-completion      # prints the script for the current shell
```

`tclock completion --script --shell fish` prints the script for another shell, for example to
put in `~/.config/fish/completions/tclock.fish` by hand. The installed hook exports
`TCLOCK_COMPLETION=<shell>`, which is how `tclock completion` knows whether the shell you are
typing in has loaded it (fish loads completions on first use and needs no hook). Elvish, nushell and other shells are
not supported by the completion machinery tclock uses (Typer and Click).

## Configuration

tclock reads an optional TOML file:

| OS      | Path                                                        |
|---------|-------------------------------------------------------------|
| Linux   | `~/.config/tclock/config.toml` (honours `$XDG_CONFIG_HOME`) |
| macOS   | `~/Library/Application Support/tclock/config.toml`          |
| Windows | `%APPDATA%\tclock\config.toml`                              |

`tclock config init` writes a starter file to that location with every key listed at its
default and commented out, ready to edit. `tclock config path` prints the location. Use
`--path FILE` to write elsewhere and `--force` to overwrite an existing file.

Command-line flags override the file; the file overrides built-in defaults. Every key is
optional. The full schema, with the built-in defaults:

```toml
[default]
mode = "clock"          # clock, timer, stopwatch or countdown when no mode is given
color = "green"
size = 1

[clock]
show_date = true
show_seconds = true
show_millis = false
# timezone = "Europe/Oslo"

[timer]
durations = ["25m", "5m"]
titles = []
repeat = false
show_millis = true
start_paused = false
auto_quit = false
execute = []            # joined with spaces into one shell command

[countdown]
# time = "2027-01-01"
# title = "New year"
show_millis = false
continue_on_zero = false
reverse = false
```

A broken file or a wrong value produces a warning on stderr and the default is used.

## Differences from the Rust clock-tui

- Flags that took several values now repeat instead: `-d 25m -d 5m`, `-t Work -t Break`.
- `--execute` takes one quoted shell string instead of a list of words.
- The config file lives in the platform-native location listed above rather than always
  in `~/.config/tclock/`.
- `tclock timer` without `-d` uses the `[timer] durations` from the config file
  (`25m`, `5m` by default) instead of a fixed `5m`.
- `tclock countdown` without `--time` falls back to `[countdown] time` in the config file.
- `Ctrl+C` quits. In the Rust binary it switches to clock mode, because its key matcher
  ignores the Ctrl modifier (so `Ctrl+Q`, `Ctrl+W` and `Ctrl+T` also act like the plain
  letters there).
- Mode keys work from every mode. In the Rust binary a widget, once created, stays in a
  fixed priority order (clock > timer > stopwatch > countdown), so e.g. `t` from the
  clock has no visible effect and `w` from a timer keeps showing the timer.
- The `?` help overlay and the auto-hiding key bar are additions.

## Development

```shell
uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check . && uv run mypy src
uv run tclock
```

`uv run tox` runs the suite on every supported Python (3.10 to 3.14, plus the 3.15 release
candidate) and lint and mypy.
Missing interpreters are downloaded by uv. `uv run tox -e py310` runs a single version.

## Releasing

There is no manual release step. Every pull request merged into `main` is released to
[PyPI](https://pypi.org/project/tclock/) and gets a GitHub release with generated notes.
Control what happens with labels on the pull request:

| Label           | Effect                                        |
| --------------- | --------------------------------------------- |
| *(none)*        | Patch release, for example `0.1.4` to `0.1.5` |
| `release:minor` | Minor release, `0.1.5` to `0.2.0`             |
| `release:major` | Major release, `0.2.0` to `1.0.0`             |
| `skip-release`  | Merge without releasing, for docs or CI work  |

Release notes are grouped by the PR's other labels (`enhancement`, `bug`, `documentation`,
`ci`, `dependencies`). Pre-release bumps (`rc`, `stable`) are run by hand from the
**Release** workflow in the Actions tab. Never bump the version or push tags manually.

## License

MIT. Original clock-tui by Race604, also MIT.
