ephem

a minimal, opinionated astrology CLI tool

ephem is a linux-native cli for astrologers, built on hellenistic tradition with electional and horary practice in mind. it generates horoscopes and monthly ephemerides with professional accuracy, and stores time and geodata in a local database that can be edited as YAML files.

currently supports:

• all 47 sidereal offsets from the Swiss Ephemeris
• the sun, moon, and eight planets (mercury–pluto)
• choice of lunar node calculation method
• clear table output for charts and ephemerides
• graceful handling of incomplete data

deliberately out of scope:

• house cusps and placements
• graphical charts
• asteroids

table of contents

• installation
• usage
  • examples
  • tutorial
• testing
• contributing
• acknowledgments
• license

installation

build dependencies

because pyswisseph wraps the Swiss Ephemeris C library, you'll need to run the following:

• debian-based: sudo update && sudo apt install build-essential python3-dev pipx
• fedora/rhel: sudo dnf install @development-tools python3-devel pipx
• arch: sudo pacman -Syu base-devel python python-pipx
• alpine: doas apk add base python3-dev pipx

note: if you use uv, feel free to exclude pipx.

stable

the stable release of ephem can be installed directly from pypi:

global installation

# using pipx
pipx install ephem-cli

# using uv
uv tool install ephem-cli

run directly

# run directly without installing
uvx --from ephem-cli ephem

build from source

git clone https://codeberg.org/sailorfe/ephem.git
cd ephem
uv run ephem                        # run directly
# or
uv sync && uv run ephem             # for development

testing

you can install the current pre-release from codeberg:

# run pre-release directly from codeberg
uvx --from https://codeberg.org/sailorfe/ephem ephem-cli

# or install pre-release
uv tool install ephem-cli \
  --index https://codeberg.org/api/packages/sailorfe/pypi/simple/ \
  --prerelease allow

usage

ephem {now,cast,cal,data}

• now and cast to calculate and optionally save charts
• cal to calculate monthly ephemerides
• data to interact with chart database

examples

get a chart for right now:

ephem now

save your location to avoid typing coordinates every time:

ephem now -y 30 -x -80 --save-config

cast a chart for a specific date and time:

ephem cast 1996-08-26 17:20 "Jeon Soyeon" -z Asia/Seoul -y 37.488167 -x 127.085472

get a monthly ephemeris:

ephem cal 1989 dec

tutorial

for more detailed examples, see the ephem tutorial. (i think it's pretty good.)

testing

ephem has a test suite. run it with:

make test

these tests currently focus on CLI behavior and database interactions since core calculations are handled by the Swiss Ephemeris library. more tests are planned as the project grows!

contributing

ephem is in early development. contributions are welcome, especially from developers with experience in astrology software, but what it really needs at this stage is testers. join the humble discord server!

acknowledgments

ephem draws inspiration from:

• Swiss Ephemeris and Astro.com
• Astrolog by Walter Pullen
• Planetdance by Jean Cremers
• The American Ephemeris by Neil F. Michelsen and Rique Pottenger
• Astrological Chart Calculations by Bruce Scofield

license

licensed under AGPL v3 per the Swiss Ephemeris; see LICENSE file for details.