starlight

README

starlight₊‧⁺˖⋆

an astrological toolkit for the terminal.

made with bubbletea🧋 and lipgloss💄.

displays simple, not-so-accurate charts for fun.
accompanied by placement tables for actually-accurate analysis.

features

• command line interface and guided huh form chart builder
• uses swephgo for astronomical calculations
• switch between planetary positions and aspects table
• customizable color schemes with JSON

to be added:

• additional objects search (asteroids, nodal axis)
• transit chart overlays

installation

starlight requires the Swiss Ephemeris library to calculate positions.

1. you can find instructions on installing (and compiling!!) the library in swephgo's README.md

2. download the following files from the Swiss Ephemeris repo:

• sepl_18.se1 (planets)
• semo_18.se1 (moon)
• seas_18.se1 (main asteroids)

1. place them in your local data directory:

• Linux/Mac: ~/.local/share/starlight/ephe/
• Windows: you'll need wsl2 to access this program's swisseph dependencies! see WINDOWS.md for more detailed instructions!

(note: starlight follows the XDG Base Directory specification. you can override the location by setting $XDG_DATA_HOME).

install the binary

go install github.com/amilleah/starlight@latest

usage

run without arguments to enter the chart wizard(₊‧⁺˖⋆) or load saved charts.

interactive mode

starlight

quick cast (one-shot)

starlight cast --lat 40.71 --lon -74.00 --tz "America/New_York" --name "nyc now"

load saved chart

starlight load "my natal chart"

flags

flag	description	default
--theme	set color theme (terminal, meow)	meow
--date	date (YYYY-MM-DD)	current
--time	time (HH:MM)	current

keybindings

key	action
tab	toggle table view
h	toggle house system (placidus / whole sign)
?	toggle help
←/→	scroll table views (chart / aspects / help)
↑/↓	scroll table contents
ctrl+c	quit

config

configuration is stored in ~/.config/starlight/settings.json. you can manually edit this file to set your default latitude/longitude, theme, or house system preference.

faq

Q: why not use Kitty (etc.) for more accurate terminal graphics?
A: starlight is designed for the terminal. this tool is for programmer-astrologers who want quick reference, scripting capability, and the fun aesthetic of a TUI.

Q: the chart looks slightly different than Astro.com?
A: ASCII charts are an approximation. while the math behind starlight is accurate (using the same C library as professional software), plotting planets on a 80x24 text grid requires some rounding. use the table view for exact degrees.

Q: meow?
A: meow.