ephem-cli 2.0.3

A minimal and configurable astrology CLI

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

stable

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

# run directly without installing
uvx ephem-cli

# or install globally
uv tool install ephem-cli

# traditional methods
pip install --user ephem-cli    # if you use pip
pipx install ephem-cli          # if you use pipx, especially debian/ubuntu

or you can build it from source from the main branch:

git clone https://codeberg.org/sailorfe/ephem.git
cd ephem
uv run -m ephem.cli             # run directly
# or
uv sync && uv run -m ephem.cli     # 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.