https://github.com/ingk/chrono-ntp
Simple command-line tool that synchronizes with an NTP server, displaying the precise date and time in your terminal. Set your mechanical or digital watches or use it as a minimal distraction-free terminal clock.
https://github.com/ingk/chrono-ntp
clocks ntp time watches
Last synced: about 1 month ago
JSON representation
Simple command-line tool that synchronizes with an NTP server, displaying the precise date and time in your terminal. Set your mechanical or digital watches or use it as a minimal distraction-free terminal clock.
- Host: GitHub
- URL: https://github.com/ingk/chrono-ntp
- Owner: ingk
- License: mit
- Created: 2025-08-10T15:50:43.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-05-03T16:42:40.000Z (about 1 month ago)
- Last Synced: 2026-05-03T17:29:06.766Z (about 1 month ago)
- Topics: clocks, ntp, time, watches
- Language: Go
- Homepage:
- Size: 207 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# chrono-ntp
## About the Project
chrono-ntp is a simple command-line tool that synchronizes with an NTP (Network Time Protocol) server to account for any difference between your computer’s clock and the actual time, displaying the precise date and time in your terminal.
You can use chrono-ntp to set your mechanical or digital watches or as a minimal distraction-free terminal clock.
## Getting Started
Download the latest release from the [releases page on GitHub](https://github.com/ingk/chrono-ntp/releases) and choose the binary for your platform.
### Supported Platforms
| OS | CPU Architectures |
|---------|-------------------|
| Linux | x86_64, arm64 |
| macOS | x86_64, arm64 |
| Windows | x86_64, arm64 |
### Installation via Homebrew
macOS or Linux users can use [Homebrew](https://brew.sh/) to install chrono-ntp.
```bash
brew tap ingk/chrono-ntp
brew install chrono-ntp
```
## Usage
Run chrono-ntp from your terminal:
```sh
chrono-ntp [options]
```
```
Usage of chrono-ntp:
-server string
NTP server to sync time from (default "time.google.com")
-time-zone string
Time zone name (e.g., 'America/New_York') (default "Local")
-show-time-zone
Show the time zone below time
-date-format string
Date display format (YYYY-MM-DD, DD/MM/YYYY, MM/DD/YYYY, DD.MM.YYYY) (default "YYYY-MM-DD")
-time-format string
Time display format (ISO8601, 12h, 12h_AM_PM, .beat, septimal, mars, lunar, unix) (default "ISO8601")
-hide-date
Hide the current date
-hide-status-bar
Hide the status bar
-beeps
Play 6 beeps at the end of each minute, with the sixth beep at second 0 (emulates the Greenwich Time Signal)
-offline
Run in offline mode (use system time, ignore NTP server)
-write-config
Write configuration file (merged from existing configuration file and flags)
-debug
Show debug information (e.g. offset from NTP server), then exit
```
### Example
```sh
chrono-ntp -server time.google.com -time-zone Europe/Berlin
```
### Time Format Options
The `-time-format` option (or `time-format` in the [configuration file](#configuration-file)) controls how the time is displayed. The following formats are available:
| Name | Configuration Value | Example |
|---------------------------------------------------------------------------------------|---------------------|-------------|
| ISO 8601 | ISO8601 | 14:30:00 |
| 12-hour | 12h | 02:30:00 |
| 12-hour (AM/PM) | 12h_AM_PM | 02:30:00 PM |
| [Swatch Internet Time](https://en.wikipedia.org/wiki/Swatch_Internet_Time) | .beat | @625.00 |
| [Septimal Time](http://the-light.com/cal/veseptimal.html) (base-7 pairs) | septimal | 43 11 52 |
| [Coordinated Mars Time (MTC)](https://en.wikipedia.org/wiki/Timekeeping_on_Mars) | mars | 12:34:56 |
| [Coordinated Lunar Time (LTC)](https://en.wikipedia.org/wiki/Timekeeping_on_the_Moon) | lunar | 12:34:56 |
| Unix Timestamp (seconds since epoch) | unix | 1696173377 |
### Configuration File
chrono-ntp supports a configuration file for default values. You can create a TOML file at `~/.chrono-ntp.toml` to specify your preferred options, which will be loaded automatically on startup.
Example `~/.chrono-ntp.toml`:
```toml
server = "time.google.com"
time-zone = "Europe/Berlin"
show-time-zone = true
date-format = "YYYY-MM-DD"
time-format = "ISO8601"
hide-date = false
hide-status-bar = false
beeps = true
```
Any command-line options will override the values set in the configuration file.
### Periodic Offset Refresh
By default, chrono-ntp automatically refreshes its time offset from the NTP server every 15 minutes while running (unless started in offline mode). This ensures the displayed time remains accurate even if your system clock drifts.
## Build from Source
To build chrono-ntp from source, you will need Go installed (version 1.18 or newer recommended).
Clone the repository, build, and run:
```sh
git clone https://github.com/ingk/chrono-ntp.git
cd chrono-ntp
make build
./chrono-ntp
```
## Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
Don't forget to give the project a star! Thanks again!
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
This project is distributed under the MIT License. See `LICENSE.txt` for details.