{"id":46144798,"url":"https://github.com/aklo360/thoth-cli","last_synced_at":"2026-03-02T07:04:34.624Z","repository":{"id":340944241,"uuid":"1168226541","full_name":"aklo360/thoth-cli","owner":"aklo360","description":"𓅝 Hermetic astrology from the command line. Swiss Ephemeris precision.","archived":false,"fork":false,"pushed_at":"2026-02-27T08:07:15.000Z","size":98,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-27T13:53:36.333Z","etag":null,"topics":["astrology","cli","ephem","ephemeris","hermet","hermeti","horoscope","kabbal","natal-chart","python","qabba","swiss-ephemeris","tarot","typescript","zodiac"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aklo360.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-27T06:28:48.000Z","updated_at":"2026-02-27T08:14:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aklo360/thoth-cli","commit_stats":null,"previous_names":["aklo360/thoth-cli"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/aklo360/thoth-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aklo360%2Fthoth-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aklo360%2Fthoth-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aklo360%2Fthoth-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aklo360%2Fthoth-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aklo360","download_url":"https://codeload.github.com/aklo360/thoth-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aklo360%2Fthoth-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29992999,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astrology","cli","ephem","ephemeris","hermet","hermeti","horoscope","kabbal","natal-chart","python","qabba","swiss-ephemeris","tarot","typescript","zodiac"],"created_at":"2026-03-02T07:04:34.164Z","updated_at":"2026-03-02T07:04:34.616Z","avatar_url":"https://github.com/aklo360.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 𓅝 thoth-cli\n\n**Hermetic astrology from the command line.**\n\nA powerful astrological calculation CLI built on [Kerykeion](https://github.com/g-battaglia/kerykeion) and Swiss Ephemeris. Designed for AI agents, developers, and modern practitioners who need precise calculations with clean output.\n\n## Features\n\n- **Natal Charts** — Full birth charts with planets, houses, aspects, and balances\n- **Transits** — Current planetary positions relative to your natal chart\n- **Solar Returns** — Annual birthday charts for year-ahead themes\n- **Lunar Returns** — Monthly emotional cycle charts\n- **Synastry** — Relationship compatibility between two charts\n- **Composite Charts** — Merged relationship chart (midpoint method)\n- **Progressions** — Secondary progressions (day-for-a-year)\n- **Solar Arc** — Solar arc directions for timing\n- **Horary** — Question-based divination charts with traditional rules\n- **Ephemeris** — Position of any celestial body on any date\n- **Ephemeris Range** — Track a planet through signs over time\n- **Moon Phases** — Current lunar phase and position\n- **Symbol Reference** — Complete guide to astrological symbols and meanings\n- **Sephirotic Colors** — Kabbalistic color correspondences throughout\n- **JSON Output** — Machine-readable output for AI/automation\n\n## Installation\n\n```bash\nnpm install -g thoth-cli\n```\n\nThe binary downloads automatically on first install (~18MB).\n\n## Quick Start\n\n```bash\n# Natal chart\nthoth chart --date 1991-07-08 --time 14:06 --city \"New York\"\n\n# Current transits\nthoth transit --natal-date 1991-07-08 --natal-time 14:06 --city \"New York\"\n\n# Solar return for 2026\nthoth solar-return --natal-date 1991-07-08 --natal-time 14:06 --city \"New York\" --year 2026\n\n# Horary divination\nthoth horary --question \"Should I take the job?\" --city \"New York\"\n\n# Relationship synastry\nthoth synastry --date1 1991-07-08 --time1 14:06 --city1 \"NYC\" \\\n               --date2 1990-03-15 --time2 09:30 --city2 \"LA\"\n\n# Moon phase\nthoth moon\n\n# Where is Pluto?\nthoth ephemeris --body pluto\n\n# Symbol reference\nthoth key\n```\n\n---\n\n## Commands\n\n### `thoth chart` — Natal Chart\n\nCalculate a complete birth chart.\n\n```bash\nthoth chart --date 1991-07-08 --time 14:06 --city \"New York\"\nthoth chart --date 1991-07-08 --time 14:06 --lat 40.7128 --lng -74.0060\nthoth chart --date 1991-07-08 --time 14:06 --city \"New York\" --svg-file chart.svg\n```\n\n| Flag | Description | Required |\n|------|-------------|----------|\n| `--date` | Birth date (YYYY-MM-DD) | Yes |\n| `--time` | Birth time (HH:MM) | Yes |\n| `--city` | City name | Yes* |\n| `--nation` | Country code (default: US) | No |\n| `--lat` / `--lng` | Coordinates | Yes* |\n| `--name` | Name for the chart | No |\n| `--svg` | Output SVG chart | No |\n| `--svg-file` | Save SVG to file | No |\n| `--json` | Output raw JSON | No |\n\n*Either `--city` or both `--lat` and `--lng` required.\n\n---\n\n### `thoth transit` — Current Transits\n\nCalculate transits to a natal chart.\n\n```bash\nthoth transit --natal-date 1991-07-08 --natal-time 14:06 --city \"New York\"\nthoth transit --natal-date 1991-07-08 --natal-time 14:06 --city \"NYC\" --orb 1\n```\n\n| Flag | Description | Required |\n|------|-------------|----------|\n| `--natal-date` | Birth date | Yes |\n| `--natal-time` | Birth time | Yes |\n| `--city` | City name | Yes* |\n| `--lat` / `--lng` | Coordinates | Yes* |\n| `--transit-date` | Transit date (default: today) | No |\n| `--orb` | Aspect orb in degrees (default: 3) | No |\n| `--json` | Output raw JSON | No |\n\n---\n\n### `thoth solar-return` — Annual Chart\n\nCalculate solar return chart for a specific year.\n\n```bash\nthoth solar-return --natal-date 1991-07-08 --natal-time 14:06 --city \"NYC\" --year 2026\n```\n\n| Flag | Description | Required |\n|------|-------------|----------|\n| `--natal-date` | Birth date | Yes |\n| `--natal-time` | Birth time | Yes |\n| `--city` | City name | Yes |\n| `--year` | Return year | Yes |\n| `--json` | Output raw JSON | No |\n\n---\n\n### `thoth lunar-return` — Monthly Chart\n\nCalculate next lunar return from a given date.\n\n```bash\nthoth lunar-return --natal-date 1991-07-08 --natal-time 14:06 --city \"NYC\" --from 2026-03-01\n```\n\n| Flag | Description | Required |\n|------|-------------|----------|\n| `--natal-date` | Birth date | Yes |\n| `--natal-time` | Birth time | Yes |\n| `--city` | City name | Yes |\n| `--from` | Date to search from | Yes |\n| `--json` | Output raw JSON | No |\n\n---\n\n### `thoth synastry` — Relationship Aspects\n\nCalculate synastry aspects between two charts.\n\n```bash\nthoth synastry --date1 1991-07-08 --time1 14:06 --city1 \"NYC\" \\\n               --date2 1990-03-15 --time2 09:30 --city2 \"LA\"\n```\n\n| Flag | Description | Required |\n|------|-------------|----------|\n| `--date1` / `--time1` | Person 1 birth data | Yes |\n| `--city1` or `--lat1/--lng1` | Person 1 location | Yes |\n| `--date2` / `--time2` | Person 2 birth data | Yes |\n| `--city2` or `--lat2/--lng2` | Person 2 location | Yes |\n| `--orb` | Aspect orb (default: 6) | No |\n| `--json` | Output raw JSON | No |\n\n---\n\n### `thoth composite` — Relationship Chart\n\nCalculate composite (midpoint) chart for a relationship.\n\n```bash\nthoth composite --date1 1991-07-08 --time1 14:06 --city1 \"NYC\" \\\n                --date2 1990-03-15 --time2 09:30 --city2 \"LA\"\n```\n\nSame options as synastry. Creates a merged chart representing the relationship itself.\n\n---\n\n### `thoth progressions` — Secondary Progressions\n\nCalculate secondary progressions (day-for-a-year method).\n\n```bash\nthoth progressions --natal-date 1991-07-08 --natal-time 14:06 --city \"NYC\" \\\n                   --target-date 2026-03-01\n```\n\n| Flag | Description | Required |\n|------|-------------|----------|\n| `--natal-date` | Birth date | Yes |\n| `--natal-time` | Birth time | Yes |\n| `--city` or `--lat/--lng` | Birth location | Yes |\n| `--target-date` | Progression target date | Yes |\n| `--json` | Output raw JSON | No |\n\n---\n\n### `thoth solar-arc` — Solar Arc Directions\n\nCalculate solar arc directions (all planets advance by Sun's arc).\n\n```bash\nthoth solar-arc --natal-date 1991-07-08 --natal-time 14:06 --city \"NYC\" \\\n                --target-date 2026-03-01\n```\n\nSame options as progressions. Shows directed positions and aspects to natal.\n\n---\n\n### `thoth horary` — Question Divination\n\nCast a horary chart for yes/no or situational questions.\n\n```bash\nthoth horary --question \"Should I take the job?\" --city \"New York\"\nthoth horary --question \"Will we reconcile?\" --lat 40.7128 --lng -74.0060\n```\n\n| Flag | Description | Required |\n|------|-------------|----------|\n| `--question` | Your question | Yes |\n| `--city` or `--lat/--lng` | Your current location | Yes |\n| `--json` | Output raw JSON | No |\n\n**Output includes:**\n- Planetary hour and day ruler\n- Strictures against judgment (void of course, etc.)\n- Querent significator (1st house ruler)\n- Quesited significator (relevant house ruler)\n- Moon's last and next aspects\n- Reception and dignity analysis\n\n---\n\n### `thoth moon` — Lunar Phase\n\nGet current moon phase and position.\n\n```bash\nthoth moon\nthoth moon --date 2026-03-14\n```\n\n---\n\n### `thoth ephemeris` — Planet Position\n\nGet the position of any celestial body.\n\n```bash\nthoth ephemeris --body pluto\nthoth ephemeris --body saturn --date 2027-01-15\n```\n\n**Bodies:** sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto\n\n---\n\n### `thoth ephemeris-range` — Track Planet Over Time\n\nGet ephemeris positions over a date range.\n\n```bash\nthoth ephemeris-range --body pluto --from 2024-01-01 --to 2030-01-01 --step month\n```\n\n| Flag | Description | Required |\n|------|-------------|----------|\n| `--body` | Celestial body | Yes |\n| `--from` | Start date | Yes |\n| `--to` | End date | Yes |\n| `--step` | Interval: day, week, month | No (default: month) |\n\n---\n\n### `thoth key` — Symbol Reference\n\nDisplay the complete astrological symbol reference.\n\n```bash\nthoth key\n```\n\n**Includes:**\n- Planets — meanings, rulerships, Sephirotic correspondences\n- Points — Chiron, Lilith, Nodes\n- Zodiac Signs — element, modality, ruler, \"I AM\" mantras\n- Houses — all 12 life areas\n- Aspects — degrees, meanings, orbs\n- Elements \u0026 Modalities\n- Dignities — domicile, exaltation, detriment, fall\n\n---\n\n## Color System\n\nthoth-cli uses **Sephirotic colors** based on Kabbalistic correspondences:\n\n| Planet | Sephira | Color |\n|--------|---------|-------|\n| ☉ Sun | Tiphareth | Gold |\n| ☽ Moon | Yesod | Silver |\n| ☿ Mercury | Hod | Orange |\n| ♀ Venus | Netzach | Green |\n| ♂ Mars | Geburah | Red |\n| ♃ Jupiter | Chesed | Royal Blue |\n| ♄ Saturn | Binah | Indigo |\n| ♅ Uranus | Chokmah | Cyan |\n| ♆ Neptune | — | Sea Green |\n| ♇ Pluto | — | Dark Red |\n\n---\n\n## JSON Output\n\nAll commands support `--json` for programmatic use:\n\n```bash\nthoth chart --date 1991-07-08 --time 14:06 --city \"NYC\" --json\nthoth horary --question \"Test\" --city \"NYC\" --json\n```\n\nPerfect for AI agents, automation, and integration.\n\n---\n\n## Privacy\n\n**thoth-cli collects no data. Ever.**\n\n- ✅ All calculations run locally\n- ✅ No analytics, no telemetry, no tracking\n- ✅ No network requests except city geocoding (via GeoNames)\n- ✅ Your birth data stays on your machine\n\n---\n\n## Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `KERYKEION_GEONAMES_USERNAME` | Custom GeoNames username for geocoding (optional, avoids rate limits) |\n\nGet a free username at [geonames.org/login](https://www.geonames.org/login)\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/aklo360/thoth-cli.git\ncd thoth-cli\n\n# Python core\ncd packages/core\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n\n# TypeScript CLI\ncd ../cli\nnpm install\nnpm run build\n\n# Test\nnode dist/bin.js chart --date 1991-07-08 --time 14:06 --city \"New York\"\n```\n\n---\n\n## Credits\n\n- [Kerykeion](https://github.com/g-battaglia/kerykeion) — Python astrology library\n- [Swiss Ephemeris](https://www.astro.com/swisseph/) — Precise planetary calculations\n- [Commander.js](https://github.com/tj/commander.js) — CLI framework\n\n---\n\n## License\n\n**MIT** — Use it for anything. Free forever.\n\n---\n\n*\"As above, so below; as the universe, so the soul.\"*\n\n𓅝\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faklo360%2Fthoth-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faklo360%2Fthoth-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faklo360%2Fthoth-cli/lists"}