stardial

A space-anime themed terminal clock, with starfield backgrounds, themes, and gentle effects.

Demo

Quickstart

# Default clock
$ stardial

# Large nebula clock with dense stars and blinking colon
$ stardial --size 3 --theme nebula --stars 100 --blink

# Solar theme, no effects, with date display
$ stardial --size 3 --theme solar --no-effects --date

# 12-hour luna clock with dense stars and blinking colon
$ stardial --size 2 --theme luna --stars 100 --blink --twelve

Features

• Big block-character digits (7-segment style) with adjustable size (--size 1-5)
• 12/24-hour format, optional seconds, blinking colon
• Date display
• 4 color themes: void (cyan), nebula (pink), luna (silver), solar (gold)
• Custom accent color via --color '#RRGGBB' or a named color (red, green, blue, cyan, magenta, yellow, white, black)
• Animated starfield background with parallax layers
• Shooting star effect (rare, tasteful)
• Scanline overlay for CRT/anime feel
• Deterministic visuals with --seed
• Handles terminal resize gracefully
• Panic-safe terminal restoration
• Optional debug logging to file

Installation

Snap

sudo snap install stardial

Homebrew

brew tap hisuic/stardial
brew install stardial

Arch Linux (AUR)

yay -S stardial

From source

Requires the Rust toolchain (cargo).

make
sudo make install

This installs:

• /usr/bin/stardial
• /usr/share/man/man1/stardial.1
• /usr/share/licenses/stardial/LICENSE

To customize the prefix:

make install PREFIX=/usr/local DESTDIR=/tmp/pkg

To uninstall:

sudo make uninstall

For AUR manual builds, clean chroot builds, and namcap verification, see docs/packaging.md.

Usage

# Default 24h clock with void theme
stardial

# 12-hour with date
stardial --twelve --date

# Nebula theme, blinking colon, no seconds
stardial --theme nebula --blink --no-seconds

# Custom color, dense stars
stardial --color '#ff6ac1' --stars 80

# Larger clock face (2x)
stardial --size 2

# Plain clock, no effects
stardial --no-effects

# Deterministic starfield for screenshots
stardial --seed 42 --fps 24

# Debug logging
stardial --log /tmp/stardial.log

Themes

Theme	Vibe	Accent Color
void	Deep space cyan	#00ffff
nebula	Purple-pink haze	#ff6ac1
luna	Silver moonlight	#c8d2f0
solar	Golden sun	#ffc832

Controls

Key	Action
q/Esc	Quit
Ctrl-C	Quit

Performance

• Default 30 FPS with adaptive frame timing
• Starfield uses simple float math, no allocations per frame
• Ratatui's diff-based rendering minimizes terminal writes
• CPU usage typically <1% on modern hardware

Man page

man stardial

Releases

Tagged releases follow semver: v0.1.0, v0.2.0, etc.

License

MIT — see LICENSE.

Links

• Repository: https://github.com/hisuic/stardial