A modern, digital clock that effortlessly runs in your terminal.
clock-rs is a terminal-based clock written in Rust, designed to be a new alternative to tty-clock. It offers several improvements, which include:
- The use of a single configuration file to manage its settings, with the ability to overwrite them through the command line,
- Many additional features such as a timer and a stopwatch,
- And greater flexibility as well as better user experience!
To install clock-rs globally using Cargo, simply run $ cargo install clock-rs.
You can then run the executable via the clock-rs command.
Usage: clock-rs [OPTIONS] [COMMAND]
Commands:
clock Display the current time (default)
timer Create a timer
stopwatch Start a stopwatch
help Print this message or the help of the given subcommand(s)
Options:
-c, --color <COLOR> Specify the clock color
-x, --x-pos <X_POS> Set the position along the horizontal axis
-y, --y-pos <Y_POS> Set the position along the vertical axis
--fmt <FMT> Set the date format
-t Use the 12h format
-i, --interval <INTERVAL> Set the polling interval in milliseconds
--utc Use UTC time
-s, --hide-seconds Do not show seconds
-B, --blink Set the colon to blink
-b, --bold Use bold text
-h, --help Print help
-V, --version Print version
Usage: clock-rs timer [OPTIONS] <SECS>
Arguments:
<SECS> Specify the timer duration in seconds
Options:
-k, --kill Terminate the application when the timer finishes
-h, --help Print help
To exit the application, press either Escape, q, or Ctrl-C.
Note
If no command is specified, the clock command is used by default.
Therefore, running $ clock-rs clock or simply $ clock-rs will both display the current time.
clock-rs uses the TOML file format for its settings.
By default, the configuration file is named conf.toml and is stored in the OS configuration directory, within the clock-rs subdirectory.
| Platform | Configuration file path |
|---|---|
| Linux | ~/.config/clock-rs/conf.toml |
| MacOS | ~/Library/Application Support/clock-rs/conf.toml |
| Windows | C:\Users\%USERNAME%\AppData\Local\clock-rs\conf.toml |
You can change this path by setting the CONF_PATH environment variable.
If you wish to run the application without automatically using the existing conf.toml file, you can set CONF_PATH to None.
Any argument passed in the command line will overwrite the settings inside the conf.toml file.
Here's a list of the available fields inside the conf.toml file.
| Field | Description | Possible values | Default |
|---|---|---|---|
general.color |
Specify the color of the clock | "black", "red", "green", "yellow", "blue", "magenta", "cyan", or "white". Optionally, prefix them with bright-. |
"white" |
general.interval |
Set the polling interval in milliseconds | An unsigned integer, e.g. 250. |
200 |
general.blink |
Set the colon to blink | true or false. |
false |
general.bold |
Use bold text | true or false. |
false |
position.horizontal |
Set the position along the horizontal axis | "start", "center", or "end". |
"center" |
position.vertical |
Set the position along the vertical axis | "start", "center", or "end". |
"center" |
date.fmt |
Specify the date format | A string, e.g. %A, %B %d, %Y. |
"%d-%m-%Y" |
date.use_12h |
Use the 12h format | true or false. |
false |
date.utc |
Use UTC time | true or false. |
false |
date.hide_seconds |
Do not show seconds | true or false. |
false |
The conf.toml file could look like this:
[general]
color = "magenta"
interval = 250
blink = true
bold = true
[position]
horizontal = "start"
vertical = "end"
[date]
fmt = "%A, %B %d, %Y"
use_12h = true
utc = true
hide_seconds = trueThe default configuration can be found here.
Feel free to report bugs, suggest features or contribute code.
Any help is appreciated!
Copyright © 2024 Oughie
This repository is licensed under the Apache License 2.0 - See here for more information.