---
name: thoth-cli
version: 0.2.27
description: "Hermetic divination CLI: astrology (natal, transits, electional, returns, synastry), tarot (cryptographic random), gematria (Hebrew/Greek/English), numerology (Pythagorean). ALWAYS run CLI first—never fabricate positions or draws."
author: aklo360
homepage: https://thothcli.com
repository: https://github.com/aklo360/thoth-cli
npm: https://www.npmjs.com/package/thoth-cli
license: MIT
metadata:
  openclaw:
    emoji: "𓅝"
    requires:
      bins: ["thoth"]
    install:
      - id: npm
        kind: node
        package: thoth-cli
        bins: ["thoth"]
        registry: https://www.npmjs.com/package/thoth-cli
---

# thoth-cli — Hermetic Divination Tools

𓅝 **v0.2.27** | Swiss Ephemeris • secrets.SystemRandom • Classical Gematria • Pythagorean Numerology

**Source:** https://github.com/aklo360/thoth-cli  
**npm:** https://www.npmjs.com/package/thoth-cli  
**Author:** aklo360

## ⚖️ GOLDEN RULE

**NEVER fabricate planetary positions, card draws, or calculated values. Run the CLI first, then interpret.**

```
CLI = DATA (empirical)    →    Agent = INTERPRETATION (Hermetic)
```

---

## Installation

```bash
npm install -g thoth-cli
```

---

## 🔮 ACP Services (Agent Commerce Protocol)

**No CLI access? Order readings directly via ACP.**

### Seller Wallet
```
0x7C8BA596afb5FD55B58FcCFCaAB926f1C1D2d9aA
```

### Available Services

| Service | Price | Description |
|---------|-------|-------------|
| `tarot_single` | $0.25 | Single card draw with Hermetic interpretation |
| `tarot_spread` | $0.50 | 3-card Past/Present/Future spread |
| `gematria_reading` | $0.50 | Letter-number analysis (Hebrew/Greek/English) |
| `numerology_full` | $0.50 | Life Path, Expression, Soul Urge, Personality |
| `transit_reading` | $1.00 | Current planetary transits to your natal chart |
| `cosmic_weather` | $1.00 | Universal sky report (no birth data needed) |
| `electional_astrology` | $1.00 | Optimal timing for events |
| `natal_chart` | $2.00 | Complete birth chart with full interpretation |
| `agent_natal_chart` | $2.00 | AI agent charts (first tx = birth moment) |

### Service Parameters

#### tarot_single
```json
{ "question": "What should I focus on today?" }
```

#### tarot_spread
```json
{ "question": "Career guidance", "spread": "3-card" }
```

#### natal_chart
```json
{ "name": "Name", "date": "YYYY-MM-DD", "time": "HH:MM", "city": "City", "nation": "XX" }
```

#### agent_natal_chart
```json
{ "agent_name": "MyAgent", "wallet_address": "0x..." }
```

#### transit_reading
```json
{ "date": "YYYY-MM-DD", "time": "HH:MM", "city": "City", "nation": "XX" }
```

#### cosmic_weather
```json
{}
```
*Optional: `city`, `nation`, `focus` (love/career/etc)*

#### electional_astrology
```json
{ "event_type": "product launch", "start_date": "2026-03-15", "end_date": "2026-04-15", "location_city": "New York", "location_nation": "US" }
```

#### gematria_reading
```json
{ "text": "THOTH", "compare_to": "HERMES" }
```

#### numerology_full
```json
{ "date": "YYYY-MM-DD", "name": "Full Name" }
```

### Response Format
All readings include a CDN download link:
```
## 🔮 THOTH ORACLE READING DELIVERED
**📥 DOWNLOAD:** https://readings.thothcli.com/xxx.md
```

---

## CLI Commands

### Astrology

#### Natal Chart
```bash
thoth chart --date 1879-03-14 --time 11:30 --city "Ulm" --nation DE
```

#### Transits
```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 --transit-date 2027-01-15
```

#### Electional (Optimal Timing)
```bash
thoth electional --start 2026-03-15 --end 2026-04-15
thoth electional --start 2026-03-15 --end 2026-04-15 --city "New York" --nation US
thoth electional --start 2026-03-15 --end 2026-04-15 --json
```
*Outputs: Moon phases, VOC Moon, retrogrades, aspects, quality scores*

#### Solar Return
```bash
thoth solar-return --natal-date 1879-03-14 --natal-time 11:30 --city "Ulm" --nation DE --year 2026
```

#### Lunar Return
```bash
thoth lunar-return --natal-date 1879-03-14 --natal-time 11:30 --city "Ulm" --nation DE --year 2026 --month 3
```

#### Synastry
```bash
thoth synastry --date1 1879-03-14 --time1 11:30 --city1 "Ulm" --nation1 DE \
               --date2 1990-01-15 --time2 09:30 --city2 "Los Angeles" --nation2 US
```

#### Composite
```bash
thoth composite --date1 1879-03-14 --time1 11:30 --city1 "Ulm" --nation1 DE \
                --date2 1990-01-15 --time2 09:30 --city2 "Los Angeles" --nation2 US
```

#### Compatibility Score
```bash
thoth score --date1 1879-03-14 --time1 11:30 --city1 "Ulm" --nation1 DE \
            --date2 1990-01-15 --time2 09:30 --city2 "Los Angeles" --nation2 US
```

#### Progressions & Solar Arc
```bash
thoth progressions --natal-date 1879-03-14 --natal-time 11:30 --city "Ulm" --nation DE --prog-year 2026
thoth solar-arc --natal-date 1879-03-14 --natal-time 11:30 --city "Ulm" --nation DE --arc-year 2026
```

#### Horary
```bash
thoth horary --question "Should I take the job?" --city "New York" --nation US
```

#### Moon Phase
```bash
thoth moon                    # Current
thoth moon -e                 # Extended (eclipses, sunrise/sunset)
thoth moon --date 2026-03-14  # Specific date
```

#### Ephemeris
```bash
thoth ephemeris --body pluto
thoth ephemeris --body saturn --date 2027-01-15
thoth ephemeris-range --body pluto --from 2024-01-01 --to 2030-01-01 --step month
thoth ephemeris-multi --bodies sun,moon,mercury,venus,mars --from 2026-03-01 --to 2026-03-31 --step day
```

#### Transit Scan
```bash
thoth transit-scan --natal-date 1879-03-14 --natal-time 11:30 --city "Ulm" --nation DE \
                   --start-year 2026 --end-year 2027 --orb 1
```

### Tarot

```bash
thoth tarot                   # Single card
thoth tarot -s 3-card         # Past/Present/Future
thoth tarot -s celtic         # Celtic Cross (10)
thoth tarot -s horseshoe      # Horseshoe (7)
thoth tarot -s relationship   # Relationship (6)
thoth tarot -s decision       # Decision (5)
thoth tarot -q "Question?"    # With question
thoth tarot --no-reversals    # Upright only
thoth tarot --json            # Raw JSON
thoth tarot-card "The Tower"  # Card lookup
thoth tarot-deck              # All 78 cards
thoth tarot-spreads           # Available spreads
```

### Gematria

```bash
thoth gematria "Word"                      # All systems
thoth gematria "Love" --compare "Will"     # Compare
thoth gematria "אהבה"                        # Hebrew text
thoth gematria-lookup 93                   # Find words = 93
```

Systems: hebrew-standard, hebrew-ordinal, hebrew-reduced, greek, english-ordinal, english-reduced, english-sumerian, english-reverse

### Numerology

```bash
thoth numerology --date 1879-03-14 --name "Full Name"
thoth numerology --date 1879-03-14          # Life Path only
thoth numerology-year --date 1879-03-14     # Personal cycles
```

Core numbers: Life Path, Expression, Soul Urge, Personality

### Reference

```bash
thoth key                                   # Symbol reference
```

---

## Interpretation Protocol

1. Run CLI → get raw data
2. Note ALL positions/cards/values
3. Identify dominant patterns
4. Synthesize holistically
5. Ground in Hermetic-Kabbalistic tradition
6. Acknowledge uncertainty — pattern, not fate