thoth-cli 0.2.13 → 0.2.15

package/README.md

@@ -8,12 +8,19 @@ A powerful astrological calculation CLI built on [Kerykeion](https://github.com/
 
 - **Natal Charts** — Full birth charts with planets, houses, aspects, and balances
 - **Transits** — Current planetary positions relative to your natal chart
-- **Moon Phases** — Current lunar phase and position
+- **Solar Returns** — Annual birthday charts for year-ahead themes
+- **Lunar Returns** — Monthly emotional cycle charts
+- **Synastry** — Relationship compatibility between two charts
+- **Composite Charts** — Merged relationship chart (midpoint method)
+- **Progressions** — Secondary progressions (day-for-a-year)
+- **Solar Arc** — Solar arc directions for timing
+- **Horary** — Question-based divination charts with traditional rules
 - **Ephemeris** — Position of any celestial body on any date
+- **Ephemeris Range** — Track a planet through signs over time
+- **Moon Phases** — Current lunar phase and position
 - **Symbol Reference** — Complete guide to astrological symbols and meanings
-- **Kabbalistic Colors** — Sephirotic color correspondences throughout
+- **Sephirotic Colors** — Kabbalistic color correspondences throughout
 - **JSON Output** — Machine-readable output for AI/automation
-- **City Geocoding** — Use city names instead of coordinates
 
 ## Installation
 
@@ -21,100 +28,215 @@ A powerful astrological calculation CLI built on [Kerykeion](https://github.com/
 npm install -g thoth-cli
 ```
 
-**Requirements:**
-- Node.js 18+
-- Python 3.10+
-
-The Python core (Kerykeion) installs automatically.
+The binary downloads automatically on first install (~18MB).
 
 ## Quick Start
 
 ```bash
-# Calculate a natal chart
-thoth chart --date 1879-03-14 --time 11:30 --city "Ulm" --nation "DE" --name "Einstein"
+# Natal chart
+thoth chart --date 1991-07-08 --time 14:06 --city "New York"
+
+# Current transits
+thoth transit --natal-date 1991-07-08 --natal-time 14:06 --city "New York"
 
-# Get current transits to a natal chart
-thoth transit --natal-date 1879-03-14 --natal-time 11:30 --city "Ulm" --nation "DE"
+# Solar return for 2026
+thoth solar-return --natal-date 1991-07-08 --natal-time 14:06 --city "New York" --year 2026
 
-# Current moon phase
+# Horary divination
+thoth horary --question "Should I take the job?" --city "New York"
+
+# Relationship synastry
+thoth synastry --date1 1991-07-08 --time1 14:06 --city1 "NYC" \
+               --date2 1990-03-15 --time2 09:30 --city2 "LA"
+
+# Moon phase
 thoth moon
 
-# Where is Pluto right now?
+# Where is Pluto?
 thoth ephemeris --body pluto
 
-# Symbol reference guide
+# Symbol reference
 thoth key
 ```
 
+---
+
 ## Commands
 
-### `thoth chart`
+### `thoth chart` — Natal Chart
 
-Calculate a natal chart.
+Calculate a complete birth chart.
 
 ```bash
-thoth chart --date 1879-03-14 --time 11:30 --city "Ulm" --nation "DE" --name "Einstein"
+thoth chart --date 1991-07-08 --time 14:06 --city "New York"
+thoth chart --date 1991-07-08 --time 14:06 --lat 40.7128 --lng -74.0060
+thoth chart --date 1991-07-08 --time 14:06 --city "New York" --svg-file chart.svg
 ```
 
-**Options:**
 | Flag | Description | Required |
 |------|-------------|----------|
 | `--date` | Birth date (YYYY-MM-DD) | Yes |
 | `--time` | Birth time (HH:MM) | Yes |
 | `--city` | City name | Yes* |
-| `--nation` | Country code (US, UK, DE, etc.) | No (default: US) |
-| `--lat` | Latitude | Yes* |
-| `--lng` | Longitude | Yes* |
+| `--nation` | Country code (default: US) | No |
+| `--lat` / `--lng` | Coordinates | Yes* |
 | `--name` | Name for the chart | No |
+| `--svg` | Output SVG chart | No |
+| `--svg-file` | Save SVG to file | No |
 | `--json` | Output raw JSON | No |
 
 *Either `--city` or both `--lat` and `--lng` required.
 
-**Output includes:**
-- Ascendant and Midheaven
-- All 10 planets + Chiron, Lilith, Nodes
-- House placements
-- All 12 house cusps
-- Element balance (Fire/Earth/Air/Water)
-- Modality balance (Cardinal/Fixed/Mutable)
-- Top 15 natal aspects
-- Lunar phase at birth
-
 ---
 
-### `thoth transit`
+### `thoth transit` — Current Transits
 
-Calculate current transits to a natal chart.
+Calculate transits to a natal chart.
 
 ```bash
-thoth transit --natal-date 1879-03-14 --natal-time 11:30 --city "Ulm" --nation "DE"
-thoth transit --natal-date 1879-03-14 --natal-time 11:30 --city "Ulm" --nation "DE" --orb 1
-thoth transit --natal-date 1879-03-14 --natal-time 11:30 --city "Ulm" --nation "DE" --transit-date 2027-01-15
+thoth transit --natal-date 1991-07-08 --natal-time 14:06 --city "New York"
+thoth transit --natal-date 1991-07-08 --natal-time 14:06 --city "NYC" --orb 1
 ```
 
-**Options:**
 | Flag | Description | Required |
 |------|-------------|----------|
-| `--natal-date` | Birth date (YYYY-MM-DD) | Yes |
-| `--natal-time` | Birth time (HH:MM) | Yes |
+| `--natal-date` | Birth date | Yes |
+| `--natal-time` | Birth time | Yes |
 | `--city` | City name | Yes* |
-| `--nation` | Country code | No (default: US) |
 | `--lat` / `--lng` | Coordinates | Yes* |
 | `--transit-date` | Transit date (default: today) | No |
 | `--orb` | Aspect orb in degrees (default: 3) | No |
 | `--json` | Output raw JSON | No |
 
+---
+
+### `thoth solar-return` — Annual Chart
+
+Calculate solar return chart for a specific year.
+
+```bash
+thoth solar-return --natal-date 1991-07-08 --natal-time 14:06 --city "NYC" --year 2026
+```
+
+| Flag | Description | Required |
+|------|-------------|----------|
+| `--natal-date` | Birth date | Yes |
+| `--natal-time` | Birth time | Yes |
+| `--city` | City name | Yes |
+| `--year` | Return year | Yes |
+| `--json` | Output raw JSON | No |
+
+---
+
+### `thoth lunar-return` — Monthly Chart
+
+Calculate next lunar return from a given date.
+
+```bash
+thoth lunar-return --natal-date 1991-07-08 --natal-time 14:06 --city "NYC" --from 2026-03-01
+```
+
+| Flag | Description | Required |
+|------|-------------|----------|
+| `--natal-date` | Birth date | Yes |
+| `--natal-time` | Birth time | Yes |
+| `--city` | City name | Yes |
+| `--from` | Date to search from | Yes |
+| `--json` | Output raw JSON | No |
+
+---
+
+### `thoth synastry` — Relationship Aspects
+
+Calculate synastry aspects between two charts.
+
+```bash
+thoth synastry --date1 1991-07-08 --time1 14:06 --city1 "NYC" \
+               --date2 1990-03-15 --time2 09:30 --city2 "LA"
+```
+
+| Flag | Description | Required |
+|------|-------------|----------|
+| `--date1` / `--time1` | Person 1 birth data | Yes |
+| `--city1` or `--lat1/--lng1` | Person 1 location | Yes |
+| `--date2` / `--time2` | Person 2 birth data | Yes |
+| `--city2` or `--lat2/--lng2` | Person 2 location | Yes |
+| `--orb` | Aspect orb (default: 6) | No |
+| `--json` | Output raw JSON | No |
+
+---
+
+### `thoth composite` — Relationship Chart
+
+Calculate composite (midpoint) chart for a relationship.
+
+```bash
+thoth composite --date1 1991-07-08 --time1 14:06 --city1 "NYC" \
+                --date2 1990-03-15 --time2 09:30 --city2 "LA"
+```
+
+Same options as synastry. Creates a merged chart representing the relationship itself.
+
+---
+
+### `thoth progressions` — Secondary Progressions
+
+Calculate secondary progressions (day-for-a-year method).
+
+```bash
+thoth progressions --natal-date 1991-07-08 --natal-time 14:06 --city "NYC" \
+                   --target-date 2026-03-01
+```
+
+| Flag | Description | Required |
+|------|-------------|----------|
+| `--natal-date` | Birth date | Yes |
+| `--natal-time` | Birth time | Yes |
+| `--city` or `--lat/--lng` | Birth location | Yes |
+| `--target-date` | Progression target date | Yes |
+| `--json` | Output raw JSON | No |
+
+---
+
+### `thoth solar-arc` — Solar Arc Directions
+
+Calculate solar arc directions (all planets advance by Sun's arc).
+
+```bash
+thoth solar-arc --natal-date 1991-07-08 --natal-time 14:06 --city "NYC" \
+                --target-date 2026-03-01
+```
+
+Same options as progressions. Shows directed positions and aspects to natal.
+
+---
+
+### `thoth horary` — Question Divination
+
+Cast a horary chart for yes/no or situational questions.
+
+```bash
+thoth horary --question "Should I take the job?" --city "New York"
+thoth horary --question "Will we reconcile?" --lat 40.7128 --lng -74.0060
+```
+
+| Flag | Description | Required |
+|------|-------------|----------|
+| `--question` | Your question | Yes |
+| `--city` or `--lat/--lng` | Your current location | Yes |
+| `--json` | Output raw JSON | No |
+
 **Output includes:**
-- Current sky (all planets with signs, degrees, houses)
-- Side-by-side house comparison (transit vs natal)
-- Transit-to-natal aspects with orbs
-- House flow notation (e.g., 2H→4H)
-- Current lunar phase
-- Retrograde indicators
+- Planetary hour and day ruler
+- Strictures against judgment (void of course, etc.)
+- Querent significator (1st house ruler)
+- Quesited significator (relevant house ruler)
+- Moon's last and next aspects
+- Reception and dignity analysis
 
 ---
 
-### `thoth moon`
+### `thoth moon` — Lunar Phase
 
 Get current moon phase and position.
 
@@ -123,15 +245,9 @@ thoth moon
 thoth moon --date 2026-03-14
 ```
 
-**Options:**
-| Flag | Description |
-|------|-------------|
-| `--date` | Date (default: today) |
-| `--json` | Output raw JSON |
-
 ---
 
-### `thoth ephemeris`
+### `thoth ephemeris` — Planet Position
 
 Get the position of any celestial body.
 
@@ -140,38 +256,49 @@ thoth ephemeris --body pluto
 thoth ephemeris --body saturn --date 2027-01-15
 ```
 
-**Options:**
+**Bodies:** sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto
+
+---
+
+### `thoth ephemeris-range` — Track Planet Over Time
+
+Get ephemeris positions over a date range.
+
+```bash
+thoth ephemeris-range --body pluto --from 2024-01-01 --to 2030-01-01 --step month
+```
+
 | Flag | Description | Required |
 |------|-------------|----------|
-| `--body` | Celestial body (sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto) | Yes |
-| `--date` | Date (default: today) | No |
-| `--json` | Output raw JSON | No |
+| `--body` | Celestial body | Yes |
+| `--from` | Start date | Yes |
+| `--to` | End date | Yes |
+| `--step` | Interval: day, week, month | No (default: month) |
 
 ---
 
-### `thoth key`
+### `thoth key` — Symbol Reference
 
-Display the complete symbol reference guide.
+Display the complete astrological symbol reference.
 
 ```bash
 thoth key
 ```
 
-Includes:
-- **Planets** — Meanings, rulerships, Sephirotic correspondences
-- **Points** — Chiron, Lilith, Nodes
-- **Zodiac Signs** — Element, modality, ruler, mantra
-- **Houses** — Life areas for all 12 houses
-- **Aspects** — Degrees, meanings, Hermetic colors
-- **Elements** — Signs, temperaments, Jungian functions
-- **Modalities** — Cardinal, Fixed, Mutable
-- **Dignities** — Domicile, Exaltation, Detriment, Fall
+**Includes:**
+- Planets — meanings, rulerships, Sephirotic correspondences
+- Points — Chiron, Lilith, Nodes
+- Zodiac Signs — element, modality, ruler, "I AM" mantras
+- Houses — all 12 life areas
+- Aspects — degrees, meanings, orbs
+- Elements & Modalities
+- Dignities — domicile, exaltation, detriment, fall
 
 ---
 
 ## Color System
 
-thoth-cli uses a **Kabbalistic color system** based on Sephirotic correspondences:
+thoth-cli uses **Sephirotic colors** based on Kabbalistic correspondences:
 
 | Planet | Sephira | Color |
 |--------|---------|-------|
@@ -186,8 +313,6 @@ thoth-cli uses a **Kabbalistic color system** based on Sephirotic correspondence
 | ♆ Neptune | — | Sea Green |
 | ♇ Pluto | — | Dark Red |
 
-Zodiac signs inherit their ruling planet's color. Aspects inherit their corresponding Sephira's color.
-
 ---
 
 ## JSON Output
@@ -195,81 +320,54 @@ Zodiac signs inherit their ruling planet's color. Aspects inherit their correspo
 All commands support `--json` for programmatic use:
 
 ```bash
-thoth chart --date 1879-03-14 --time 11:30 --city "Ulm" --nation "DE" --json
+thoth chart --date 1991-07-08 --time 14:06 --city "NYC" --json
+thoth horary --question "Test" --city "NYC" --json
 ```
 
-Perfect for AI agents, automation, and integration with other tools.
+Perfect for AI agents, automation, and integration.
 
 ---
 
-## Examples
-
-### Famous Charts
-
-```bash
-# Albert Einstein — Pisces Sun, Sagittarius Moon
-thoth chart --date 1879-03-14 --time 11:30 --city "Ulm" --nation "DE" --name "Einstein"
-
-# Carl Jung — Leo Sun, Taurus Moon  
-thoth chart --date 1875-07-26 --time 19:29 --city "Kesswil" --nation "CH" --name "Jung"
-
-# Nikola Tesla — Cancer Sun, Libra Moon
-thoth chart --date 1856-07-10 --time 00:00 --city "Smiljan" --nation "HR" --name "Tesla"
-```
-
-### Transit Analysis
+## Privacy
 
-```bash
-# Current transits with tight orb
-thoth transit --natal-date 1879-03-14 --natal-time 11:30 --city "Ulm" --nation "DE" --orb 1
+**thoth-cli collects no data. Ever.**
 
-# Future transits
-thoth transit --natal-date 1879-03-14 --natal-time 11:30 --city "Ulm" --nation "DE" --transit-date 2027-01-15
-```
+- ✅ All calculations run locally
+- ✅ No analytics, no telemetry, no tracking
+- ✅ No network requests except city geocoding (via GeoNames)
+- ✅ Your birth data stays on your machine
 
 ---
 
-## Architecture
+## Environment Variables
 
-```
-thoth-cli/
-├── packages/
-│   ├── core/           # Python calculations (Kerykeion + Swiss Ephemeris)
-│   │   ├── thoth_core/
-│   │   │   ├── __init__.py
-│   │   │   └── cli.py
-│   │   └── pyproject.toml
-│   └── cli/            # TypeScript CLI (Commander.js)
-│       ├── src/
-│       │   ├── bin.ts
-│       │   └── lib/
-│       │       ├── core.ts
-│       │       └── format.ts
-│       └── package.json
-├── CHANGELOG.md
-└── README.md
-```
+| Variable | Purpose |
+|----------|---------|
+| `KERYKEION_GEONAMES_USERNAME` | Custom GeoNames username for geocoding (optional, avoids rate limits) |
+
+Get a free username at [geonames.org/login](https://www.geonames.org/login)
 
 ---
 
 ## Development
 
 ```bash
-# Clone
 git clone https://github.com/aklo360/thoth-cli.git
 cd thoth-cli
 
-# Install Python dependencies
+# Python core
 cd packages/core
+python -m venv .venv
+source .venv/bin/activate
 pip install -e .
 
-# Install TypeScript dependencies and build
+# TypeScript CLI
 cd ../cli
 npm install
 npm run build
 
-# Run locally
-node dist/bin.js chart --date 1879-03-14 --time 11:30 --city "Ulm" --nation "DE"
+# Test
+node dist/bin.js chart --date 1991-07-08 --time 14:06 --city "New York"
 ```
 
 ---
@@ -282,19 +380,6 @@ node dist/bin.js chart --date 1879-03-14 --time 11:30 --city "Ulm" --nation "DE"
 
 ---
 
-## Privacy
-
-**thoth-cli collects no data. Ever.**
-
-- ✅ All calculations run locally on your machine
-- ✅ No analytics, no telemetry, no tracking
-- ✅ No network requests except geocoding (via Geonames)
-- ✅ Your birth data stays on your computer
-
-The oracle sees but does not record.
-
----
-
 ## License
 
 **MIT** — Use it for anything. Free forever.

package/dist/bin.js

@@ -88,7 +88,7 @@ EPHEMERIS & MOON
 \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
 REFERENCE
 \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
-  thoth key                                           # full symbol reference`).version("0.2.13");
+  thoth key                                           # full symbol reference`).version("0.2.15");
 program.command("chart").description("Calculate a natal chart").requiredOption("--date <date>", "Birth date (YYYY-MM-DD)").requiredOption("--time <time>", "Birth time (HH:MM)").option("--lat <lat>", "Latitude", parseFloat).option("--lng <lng>", "Longitude", parseFloat).option("--city <city>", "City name").option("--nation <nation>", "Country code", "US").option("--name <name>", "Name", "Subject").option("--json", "Output raw JSON").option("--svg", "Output SVG chart").option("--svg-file <path>", "Save SVG to file").action(async (options) => {
   if (!options.city && (!options.lat || !options.lng)) {
     console.error(chalk.red("Error: Must provide either --city or both --lat and --lng"));
@@ -665,6 +665,6 @@ program.command("key").description("Symbol reference guide").action(() => {
   console.log("");
 });
 console.log(chalk.dim(""));
-console.log(chalk.yellow("  \u{1315D}") + chalk.dim(" thoth-cli v0.2.13"));
+console.log(chalk.yellow("  \u{1315D}") + chalk.dim(" thoth-cli v0.2.15"));
 console.log(chalk.dim(""));
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thoth-cli",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "𓅝 Astrological calculations from the command line. Swiss Ephemeris precision. Built for humans and agents.",
   "author": "AKLO <aklo@aklolabs.com>",
   "license": "MIT",

package/scripts/postinstall.js

@@ -14,7 +14,7 @@ import https from 'https';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-const VERSION = '0.2.13';
+const VERSION = '0.2.15';
 const REPO = 'aklo360/thoth-cli';
 
 // Use jsDelivr CDN for faster downloads (mirrors GitHub releases)