Klio

A command-line tool for astrological calculations, health analysis, and personalized astrology insights.

Features:

• Command-line interface for astrological calculations
• Web-based GUI for easy exploration
• Health data analysis from Apple Health exports
• CSV data analysis with statistical testing
• Personalized astrology with multiple chart support
• AI integration for astrological insights

Prerequisites

For Linux Users

The Swiss Ephemeris library (swisseph) requires Python and C development tools on Linux systems:

# On Debian/Ubuntu
sudo apt-get install python3-dev build-essential

# On Fedora/RHEL
sudo dnf install python3-devel gcc-c++

Installation

npm install -g klio

Usage

klio [options]

Web Interface

AstroCLI includes a web-based GUI that you can launch with the --gui flag:

klio --gui

This will start a web server on port 37421 (or a different port if specified) and open a browser interface where you can:

• Run commands directly from the browser
• View command output in a formatted display
• Browse all available commands with examples and documentation
• Access command history to reuse previous commands

Custom Port:

klio --gui --gui-port 8080

Running with Docker

You can also run the GUI using Docker for easy deployment:

# Build the Docker image
docker build -t astrocli-gui .

# Run the container
docker run -p 3006:37421 astrocli-gui

This will start the GUI on http://localhost:37421.

Demo

Try a live demo of klio web here:

🌐 https://klio.up.railway.app

Configuration

• Show status: --status - Shows the stored configuration data
• Setup: --setup - Setup for a default chart which can be accessed with --i for example klio --a --i for displaying the natal aspects. In this setup you can also set up a local AI model for LM-Studio.

Commands and Options

Basic Astrological Data

• Show planet data: klio [planet] - Displays astrological data for a specific planet
• Show planet data with house and house system: klio [planet] --hs koch
• Aspect calculations: klio [planet] [planet2] --k - Shows aspects between two planets
• Aspect calculations: klio [planet] [planet2] --k --i - Shows aspects between two planets in the natal chart
• All aspects: klio --a - Shows all current aspects with orb, status and exact time (takes a while to load because the exact time)
• All aspects: klio [planet] --a - Shows all current aspects with orb, status and exact time of the specified planet
• Planet positions: klio --s - Shows all planet positions in a table with signs, degrees, and houses
• Natal planet positions: --s --i - Shows all natal planet positions in a table with signs, degrees, and houses
• Different house system: klio --s --hs placidus also possible with --i (try placidus, koch, porphyry, regiomontanus, campanus, equal, wholesign, gauquelin, vehlow, topocentric, alcabitius, morinus)

House Systems

• House system display: --hs <system> - Shows planet + house position (Placidus, Koch, Porphyry, Regiomontanus, Campanus, Equal, WholeSign, Gauquelin, Vehlow, Topocentric, Alcabitius, Morinus)

Date and Time

• Specific date: --d <date> - Use a specific date for calculations (Format: DD.MM.YYYY or "DD.MM.YYYY HH:MM") note the quotes when using it with a time in 24h format.

Health Analysis

It's possible to analyze Apple Health data. This happens on the device and no server is involved like everything from this CLI. It just parses the export XML.

• Sleep analysis: klio [planet] --apple <filepath> --sleep - Analyzes Apple Health Export XML file and shows the most frequent aspects during sleep deprivation (Top 10):
• Step analysis: klio [planet] --apple <filepath> --steps - Analyzes step patterns of any planet
• Stress analysis: klio [planet] --apple <filepath> --stress - Analyzes stress patterns of planet sign stress based on HRV
• Late night analysis: klio [planet] --apple <filepath> --night - Analyzes late night sleep patterns (after 2am) and shows the most frequent aspects during these times
• All-nighter analysis: klio [planet] --apple <filepath> --night-all - Analyzes all-nighter sleep patterns (starting at 04:00 or 06:00) and shows the most frequent aspects during these times

CSV Analysis

It's possible to analyze a csv with a column of either ISO date time or unix time stamp.

• Show house and sign distribution of the datetime column: klio [planet] --csv <file-path>

• Show aspect type distribution between two planets: klio [planet1] [planet2] --csv <file-path> --a

• Specify date column name: klio [planet] --csv <file-path> --date-col "Buchungsdatum" (e.g., --date-col "Date")

• Filter CSV data by column value: klio [planet] --csv <file-path> --filter "column:value" (e.g., --filter "Item:coffee")

• Filter CSV data by contains operator: klio [planet] --csv <file-path> --filter "column*text" (e.g., --filter "Buchungstext*Gutschrift")

• Filter CSV data by excludes operator: klio [planet] --csv <file-path> --filter "column!text" (e.g., --filter "Buchungstext!Gutschrift")

• Filter CSV data by multiple conditions: klio [planet] --csv <file-path> --filter "column1:value1,column2:value2" (e.g., --filter "FTR:H,HomeTeam:Liverpool")

• Filter CSV data with comparison operators: klio [planet] --csv <file-path> --filter "column>value" (e.g., --filter "Amount>100")

• Creating a bar chart: Create a bar chart and save the image to the downloads' folder. The image shows the aspect distribution of your csv datetime values: klio moon sun --csv /home/user/Downloads/coffee.csv --filter "Item:cookie" --a --title "Eaten cookies during sun-moon aspects"

• The command also returns a Chi-Square.

Adding different charts

• Use personal data: --i - Uses birth data from setup for calculations
• Manage persons:
  • klio --person john "New York, United States, 17.01.1987, 18:23" - Creates or updates any person (Format: "Location, Country, DD.MM.YYYY HH:MM")
  • klio --person doe "57.32, 3.72, 17.01.1987, 18:23" - Creates or updates any person (Format: "Latitude, Longitude, DD.MM.YYYY HH:MM") useful when you're offline or places
  • --people - Lists all saved persons
  • --delete-person <id> - Deletes a person

Then, instead using --i for the commands from above you can use --wp <id> or --wp john

Advanced Features

• Retrograde planets: klio --rx - Shows all retrograde or stationary planets (beta, not very accurate yet and highly depends on the preference) combine with --wp <id> or --i
• Critical degrees: klio --c - Shows all planets on critical degrees. combine with --wp <id> or --i
• Element distribution: klio --el - Shows element distribution of planets in a horizontal chart. combine with --wp <id> or --i
• Aspect figures: klio --af - Shows active aspect figures like T-squares, Grand Trines, etc. Combine with --wp <id> or --i or --d <"DD.MM.YYYY HH:MM> or --hs <house-system>
• Transits: klio --tr - Shows personal transits based on birth data. Combine with --wp <id or --i> and optional --d <"DD.MM.YYYY HH:MM>
• Transit Houses: klio --s --tra --i

Past and Future Aspects

• Past aspects: klio --v <count> [planet1] [aspect-type] [planet2] - Shows past aspects (Format: --v planet1 aspectType planet2) Available aspect types: c, o, s, t, se (conjunction, opposition, square, trine, sextile)
• Future aspects: klio --z <count> [planet1] [aspect-type] [planet2] - Shows future aspects (Format: --z planet1 aspectType planet2)

Reference

• Transit frequency: [planet1] [aspect-type] [planet2] --o - Calculates how often a transit occurs in the sky using astronomical synodic periods
  • Example: klio saturn c neptune --o - Shows Saturn-Neptune conjunction frequency
  • Example: klio jupiter s pluto --o - Shows Jupiter-Pluto square frequency
  • Aspect types: c (conjunction), o (opposition), s (square), t (trine), se (sextile), q (quincunx)
  • Output: Shows frequency in readable format (e.g., "every 36 years") with approximate

Planet Ingresses

• Planet ingress: klio [planet] --in [count] - Shows when a planet enters a new zodiac sign. Optional count parameter for multiple ingresses (default: 1). Works with any planet (moon, mercury, venus, etc.)
  • Example: klio moon --in - Shows next moon ingress
  • Example: klio saturn --in 2 - Shows next 2 Saturn ingresses (note: slow planets may have limited future data)
  • Example: klio mercury --in --d "15.03.2026" - Shows next Mercury ingress from a specific date

Wikidata Integration

• Search for people with specific aspects: [planet1] [aspect-type] [planet2] --wiki <occupation> [limit] - Searches Wikidata for people with specific astrological aspects
  • Available occupations for now: authors, scientists, artists, musicians, politicians, actors, philosophers
  • Aspect types: c (conjunction), o (opposition), s (square), t (trine), se (sextile), q (quincunx)
  • Example: klio moon c neptune --wiki authors 50 - Tries to find authors with Moon conjunct Neptune aspect with a limit of 50. Is faster but less common aspects are maybe not found with 50
  • Example: klio saturn s pluto --wiki scientists 100 - Finds scientists with Saturn square Pluto aspect
  • Example: klio sun t moon --wiki artists 200 - Finds artists with Sun trine Moon aspect

AI Integration

• AI model selection: --ai <model> - Sets a specific AI model (e.g., "google/gemma-3n-e4b") for LM Studio (lmstudio.ai)
• System prompt: --system <prompt> - Sets a custom system prompt for all AI requests. e.g. "klio --system "Answer only with a quote" or "focus on mental health""
• Ask questions: --p <prompt> - Asks a question to the AI model (e.g., "Which careers suit this position?"). Add this to most commands. Some are not yet implemented.

File Analysis

When were the files created on a system folder and in which house was the planet?

• Folder analysis: klio [planet]--folder <path> - Analyzes house distribution of all files in the folder
• House filters: --h1 through --h12 - Filters files with planet in specific houses

Note Taking

Klio includes a note-taking system:

Basic Note Taking

• Add a note to any astrological situation: klio [planet] --note "your observation"

  • Example: klio saturn --note "Boundaries, Limitations..."
  • Example: klio moon --note "Full moon in Scorpio"

• List all notes: klio --notes - Shows all saved notes with timestamps and astrological context

• Search notes: klio --search-notes "keyword" - Searches notes by astrological situation

  • Example: klio --search-notes "house" - Finds all house-related notes
  • Example: klio --search-notes "saturn" - Finds all Saturn-related notes

House Notation

• House-specific notes: klio h[n] --note "house observation"

  • Example: klio h[4] --note "4th house observation - family matters"
  • Example: klio h[10] --note "10th house - career focus"

• Planet in house notes: klio h[n] [planet] --note "planet in house observation"

  • Example: klio h[4] moon --note "Moon in 4th house - emotional security"
  • Example: klio h[7] venus --note "Venus in 7th house - relationship harmony"

Aspect Notation

• Aspect-specific notes: klio [planet1] [planet2] --note "aspect observation" --aspect [type]
  • Example: klio saturn moon --note "Saturn conjunction Moon - emotional challenges" --aspect c
  • Example: klio venus mars --note "Venus square Mars - relationship tension" --aspect s
  • Example: klio jupiter uranus --note "Jupiter trine Uranus - sudden opportunities" --aspect t

Aspect Type Shorthands

• c - Conjunction
• s - Square
• t - Trine
• se - Sextile
• o - Opposition

Advanced Features

• House system integration: Notes include house information when using --hs option
• Date-specific notes: Use --d option to add notes for specific dates
• JSON storage: All notes are stored with full astrological context in ~/.config/astrocli/notes.json

Examples

# Basic planet note
klio mars --note "Mars in Aries - high energy period"

# House note
klio h[7] --note "7th house focus - relationships this month"

# Planet in house note  
klio h[10] saturn --note "Saturn in 10th house - career challenges"

# Aspect note with shorthand
klio sun moon --note "Sun trine Moon - emotional harmony" --aspect t

# List all notes
klio --notes

# Search for specific notes
klio --search-notes "saturn"

License

ISC