clock-rs

Overview

A modern, digital clock that effortlessly runs in your terminal.

Detected project type: Rust.

This repository was migrated from upstream source github.com/shafiqalibhai/clock-rs and is preserved here for archival, reference, or continued local development.

At a glance

• Default branch: main
• Visibility: public
• Size: 2.0 MB
• Created: 2026-04-27
• Last updated: 2026-04-27
• Stars / Forks / Open issues: 0 / 0 / 0
• License: Apache-2.0

Languages

Language	Bytes	Share
Rust	30,405 bytes	100.0%

Repository structure

• public/
• src/
• .gitignore (8 B)
• build.rs (820 B)
• Cargo.lock (24,808 B)
• Cargo.toml (939 B)
• LICENSE (11,336 B)
• NOTICE (2,220 B)
• README.md (10,037 B)

Getting started

Clone the repository:

git clone https://forgejo.deployview.com/ssa/clock-rs.git
cd clock-rs

Installation

cargo build --release

Usage

cargo run --release

Original README

The content below is preserved from the previous README. Headings have been demoted so they don't compete with the new top-level sections.

A modern, digital clock that effortlessly runs in your terminal.

Table of Contents

• Introduction
• Installation
  • Using Cargo
  • Using a package manager
  • Building from source
• Usage
  • Reloading the configuration
  • Shell completion
• Configuration
  • Fields
  • Example
• Contributing
• License

Introduction

clock-rs is a terminal-based clock written in Rust, designed to be a new alternative to tty-clock.
It supports all major platforms and offers several improvements, which include:

• The use of a single configuration file to manage its settings, with the ability to override them through the command line,
• Many additional features such as a timer and a stopwatch,
• And greater flexibility as well as better user experience!

Installation

Using Cargo

To install clock-rs globally using Cargo, simply run the following command:

$ cargo install clock-rs

You can then run the executable via the clock-rs command.

Using a package manager

Arch Linux

A package is available from the AUR (Arch User Repository). To install it, use your preferred AUR manager:

$ yay -S clock-rs-git

or manually clone from the AUR:

$ git clone https://aur.archlinux.org/clock-rs-git.git && cd clock-rs-git && makepkg -si

Homebrew

You can install clock-rs via Homebrew:

$ brew install clock-rs

NetBSD

A package is available from the official pkgsrc repositories. To install it, simply run:

### pkgin install clock-rs

NixOS

clock-rs is available in the Nixpkgs repository. To install it on NixOS, use the following command:

$ nix-env -iA nixos.clock-rs

If you use Nix on a different operating system, use either of the following commands:

$ nix-env -iA nixpkgs.clock-rs # Without flakes 
$ nix profile install nixpkgs#clock-rs # With flakes

Caution

Using nix-env is generally unrecommended, since it requires you to manually manage installed packages. Consider using $ nix-shell -p clock-rs to make the application temporarily available instead.

You could also add the following to your configuration.nix:

environment.systemPackages = with pkgs; [
    clock-rs
    # ...
];

If you use Home-Manager to configure your dotfiles, you can use the following to set up clock-rs declaratively:

programs.clock-rs = {
  enable = true;

  settings = {
    general = {
      color = "magenta";
      interval = 250;
      blink = true;
      bold = true;
    };

    position = {
      horizontal = "center";
      vertical = "center";
    };

    date = {
      fmt = "%A, %B %d, %Y";
      use_12h = true;
      utc = true;
      hide_seconds = true;
    };
  };
};

Building from source

If you prefer installing clock-rs from source, follow these steps:

1. Download the repository from the releases page or clone it using $ git clone https://github.com/Oughie/clock-rs.

2. Depending on your platform, extract the archive and navigate into its directory.

3. Inside the directory, run $ cargo build --release to build the application manually. This will place the executable inside the clock-rs/target/release directory. However, if you want to install it globally instead, run $ cargo install --path ..

Usage

Usage: clock-rs [OPTIONS] [COMMAND]

Commands:
  clock      Display the current time (default)
  timer      Create a timer (5 minutes if no time is specified)
  stopwatch  Start a stopwatch
  help       Print this message or the help of the given subcommand(s)

Options:
  -c, --color <COLOR>        Specify the clock color
  -i, --interval <INTERVAL>  Set the polling interval in milliseconds
  -B, --blink                Set the colon to blink
  -b, --bold                 Use bold text
  -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
      --utc                  Use UTC time
  -s, --hide-seconds         Do not show seconds
  -h, --help                 Print help
  -V, --version              Print version

Create a timer (5 minutes if no time is specified)

Usage: clock-rs timer [OPTIONS]

Options:
  -S, --seconds <SECONDS>  Add seconds to the timer
  -M, --minutes <MINUTES>  Add minutes to the timer
  -H, --hours <HOURS>      Add hours to the timer
  -k, --kill               Terminate the application when the timer finishes
  -h, --help               Print help

Start a stopwatch

Usage: clock-rs stopwatch

Options:
  -h, --help  Print help

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.

The timer converts time units by itself, so that e.g. $ clock-rs timer -M 90 starts a timer with 1 hour and 30 minutes.
The maximum timer duration is 99 hours, 59 minutes and 59 seconds.

Press P to toggle the pause on the timer or stopwatch, and R to restart.
To exit the application, press Escape, Q, or Ctrl + C.

Reloading the configuration

You can reload the configuration file without restarting the application
by either pressing Ctrl + R or sending the SIGUSR1 signal on Unix-like systems.
Note that this will overwrite any settings previously set by command-line arguments.

Shell completion

Shell completion files are automatically generated and placed inside the target/completions directory.
The following shells are supported: Bash, Zsh, Fish, PowerShell, Elvish

Configuration

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 override the settings inside the conf.toml file.

Fields

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-" or use a hex color code in the form of "#rrggbb".	"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 chrono format 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

Example

The conf.toml file could look like this:

[general]
color = "magenta"
interval = 250
blink = true
bold = true

[position]
horizontal = "center"
vertical = "center"

[date]
fmt = "%A, %B %d, %Y"
use_12h = true
utc = true
hide_seconds = true

The default configuration can be found here.

Contributing

Feel free to report bugs, suggest features or contribute code.
Any help is appreciated!

License

Copyright © 2024 Oughie

This repository is licensed under the Apache License 2.0 - See here for more information.

Contributing

Contributions are welcome. The typical workflow is:

1. Open an issue describing the change you'd like to make.
2. Fork the repository (or create a feature branch if you have write access).
3. Commit your changes with clear, descriptive messages.
4. Open a pull request against the main branch.

Please follow the existing code style and include tests or reproduction steps where relevant.

License

This project is licensed under the Apache-2.0 license. See the LICENSE file for the full text.

Repository

• Browse: https://forgejo.deployview.com/ssa/clock-rs
• Clone (HTTPS): https://forgejo.deployview.com/ssa/clock-rs.git
• Clone (SSH): ssh://git@forgejo.deployview.com:30143/ssa/clock-rs.git
• Upstream / origin: github.com/shafiqalibhai/clock-rs

---

This README was generated automatically based on repository metadata, contents, and any prior README content. Edit any section above to add project-specific detail.