Overview

Clox is a terminal-based clock application designed for terminal enthusiasts who appreciate simplicity, elegance, and productivity within their command-line environment. Whether you're coding, monitoring tasks, or simply enjoying the terminal aesthetic, Clox brings a stylish and customizable time display to your workspace.

PyPI Counter
Github Stars

Branch	main	dev
CI

Code Quality

Installation

Source Code

• Download Version 1.7 or Latest Source
• pip install .

PyPI

• Check Python Packaging User Guide
• pip install clox==1.7

Usage

ℹ️ You can use clox or python -m clox to run this program

Version

clox --version

Info

clox --info

Basic

ℹ️ Press Ctrl + C to exit

clox

Face

clox --face=3

• Use --face=-1 for random mode
• Faces List: clox --faces-list

Timezone

clox --timezone="Etc/GMT+7"

• Timezones List: clox --timezones-list

Manual Offset

ℹ️ The local and timezone offset both have default values of 0

These arguments allow you to manually adjust the time by ±X hours. This is especially useful when daylight saving time (DST) is not correctly applied by the system or timezone database.

clox --offset-local=1 --offset-timezone=-1

Country

The --country argument allows you to specify a country using its ISO 3166 code format

ℹ️ When the --country argument is provided, the --timezone argument will be ignored

ℹ️ If the specified country has multiple timezones, the first timezone will be selected automatically

clox --country="DE"

• Countries List: clox --countries-list

Vertical/Horizontal Shift

ℹ️ The vertical and horizontal shift both have default values of 0

clox --v-shift=20 --h-shift=30

No Blink

Disable blinking mode

clox --no-blink

Once

Print current time once and exit immediately

clox --once

Hide Date

In this mode, the date will not be shown

clox --hide-date
clox --no-date

Hide Timezone

In this mode, the timezone will not be shown

clox --hide-timezone
clox --no-timezone

12-Hour Mode

In this mode, the clock will be displayed in 12-hour format.

clox --12h
clox --am-pm

Vertical Mode

clox --vertical

Calendar Mode

In this mode, the calendar will be displayed

ℹ️ Valid choices: [MONTH, YEAR]

clox --calendar=month --first-weekday="SUNDAY"

Date System

ℹ️ Valid choices: [GREGORIAN, JALALI]

ℹ️ The default date system is GREGORIAN

clox --date-system=jalali

Date Format

ℹ️ Valid choices: [ISO, US, US-SHORT, EU, EU-SHORT, DOT, DASH, YMD, DMY, MDY, FULL]

ℹ️ The default date format is FULL

clox --date-system=jalali --date-format=EU

• Date Formats List: clox --date-formats-list

Color

⚠️ This mode may not be supported on all systems

ℹ️ Valid choices: [BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, LIGHTBLACK, LIGHTRED, LIGHTGREEN, LIGHTYELLOW, LIGHTBLUE, LIGHTMAGENTA, LIGHTCYAN, LIGHTWHITE, RANDOM]

ℹ️ The default color is WHITE

clox --date-system=jalali --color="red"

Background Color

⚠️ This mode may not be supported on all systems

ℹ️ Valid choices: [BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, LIGHTBLACK, LIGHTRED, LIGHTGREEN, LIGHTYELLOW, LIGHTBLUE, LIGHTMAGENTA, LIGHTCYAN, LIGHTWHITE, RANDOM]

ℹ️ The default background color is BLACK

clox --date-system=jalali --color="red" --bg-color="blue"

Intensity

⚠️ This mode may not be supported on all systems

ℹ️ Valid choices: [NORMAL, BRIGHT, DIM, RANDOM]

ℹ️ The default intensity is NORMAL

clox --color="red" --intensity="bright"

Screen Record

Try Clox Online!

Clox can be used online in interactive Jupyter Notebooks via the Binder or Colab services! Try it out now! :

• Open notebook.ipynb

Issues & Bug Reports

Just fill an issue and describe it. We'll check it ASAP!

• Please complete the issue template

Show Your Support

Star This Repo

Give a ⭐️ if this project helped you!

Donate to Our Project

Bitcoin

1KtNLEEeUbTEK9PdN6Ya3ZAKXaqoKUuxCy

Ethereum

0xcD4Db18B6664A9662123D4307B074aE968535388

Litecoin

Ldnz5gMcEeV8BAdsyf8FstWDC6uyYR6pgZ

Doge

DDUnKpFQbBqLpFVZ9DfuVysBdr249HxVDh

Tron

TCZxzPZLcJHr2qR3uPUB1tXB6L3FDSSAx7

Ripple

rN7ZuRG7HDGHR5nof8nu5LrsbmSB61V1qq

Binance Coin

bnb1zglwcf0ac3d0s2f6ck5kgwvcru4tlctt4p5qef

Tether

0xcD4Db18B6664A9662123D4307B074aE968535388

Dash

Xd3Yn2qZJ7VE8nbKw2fS98aLxR5M6WUU3s

Stellar

GALPOLPISRHIYHLQER2TLJRGUSZH52RYDK6C3HIU4PSMNAV65Q36EGNL

Zilliqa

zil1knmz8zj88cf0exr2ry7nav9elehxfcgqu3c5e5

Coffeete

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased

1.7 - 2026-10-14

Added

• --no-timezone argument
• --no-date argument
• --12h argument
• get_datetime_library function

Changed

• Test system modified
• Build system modified
• Dependencies structure modified
• CLI arguments modified
• run_clock function modified
• print_calendar function modified
• print_clox_info function modified
• README.md updated
• Python 3.7 support dropped

1.6 - 2026-02-17

Added

• Color random mode
• Background-color random mode
• Intensity random mode

Changed

• Screen record updated
• README.md updated
• Test system modified

1.5 - 2025-12-29

Added

• --intensity argument
• --once argument
• Light colors

Changed

• README.md updated
• Test system modified
• notebook.ipynb updated

1.4 - 2025-12-16

Added

• --color argument
• --bg-color argument

Changed

• README.md updated
• Test system modified

1.3 - 2025-11-28

Added

• notebook.ipynb
• Jupyter notebook support
• detect_environment function

Changed

• clear_screen function modified
• run_clock function modified
• print_calendar function modified
• Python 3.14 added to test.yml
• README.md updated

1.2 - 2025-09-02

Added

• --offset-local argument
• --offset-timezone argument

Changed

• README.md updated
• Test system modified
• _get_weekday_id function renamed to get_weekday_id
• clox_info function renamed to print_clox_info

1.1 - 2025-05-23

Added

• --first-weekday argument
• --date-format argument
• --date-formats-list argument

Changed

• README.md updated
• Test system modified

1.0 - 2025-05-06

Added

• Local time

Changed

• clox_info function modified
• run_clock function modified

0.9 - 2025-04-14

Added

• Timezone difference

Changed

• Python typing features added to all modules
• Test system modified
• Python 3.6 support dropped

0.8 - 2025-03-16

Added

• --country argument
• --countries-list argument
• COUNTRIES.md

Changed

• Input case sensitivity bug fixed
• Test system modified
• README.md updated

0.7 - 2025-03-06

Added

• Jalali calendar
• --date-system argument

Changed

• README.md updated

0.6 - 2025-02-25

Added

• --calendar argument

Changed

• README.md updated

0.5 - 2025-02-14

Added

• --hide-date argument
• --hide-timezone argument
• --am-pm argument

Changed

• README.md updated

0.4 - 2025-01-18

Added

• Date
• --info argument

0.3 - 2025-01-10

Added

• Logo
• --vertical argument

Changed

• show_faces_list function updated
• AUTHORS.md updated

0.2 - 2025-01-01

Added

• Blink mode
• --no-blink argument

Changed

• README.md updated

0.1 - 2024-12-24

Added

• --v-shift and --h-shift arguments
• --timezone argument
• --face argument
• run_clock and main functions
• TIMEZONES.md
• FACES.md