somaos-cli

Official command-line interface for the SomaOS Developer API — Vedic astrology & numerology intelligence platform.

Generate birth charts, get Panchang, stream AI insights from Soma, manage API keys, and check quota — all from your terminal.

Installation

npm install -g somaos-cli

Requires Node.js 18+.

Quick Start

# 1. Get your API key from https://asksoma.ai/developer
soma auth login

# 2. Run your first chart
soma chart natal --dob 1990-03-14 --tob 08:30 --lat 28.61 --lon 77.20 --tz Asia/Kolkata

Authentication

# Interactive prompt
soma auth login

# Pass key directly
soma auth login --key sk_live_xxxxxxxxxxxx

# Check current auth status and quota
soma auth status

Commands

soma chart natal

Generate a full Vedic natal (birth) chart.

soma chart natal \
  --dob 1990-03-14 \
  --tob 08:30 \
  --lat 28.61 \
  --lon 77.20 \
  --tz Asia/Kolkata

| Flag | Description | |------|-------------| | --dob | Date of birth (YYYY-MM-DD) | | --tob | Time of birth (HH:MM or HH:MM:SS) | | --lat | Latitude (-90 to 90) | | --lon | Longitude (-180 to 180) | | --tz | IANA timezone (e.g. Asia/Kolkata, America/New_York) |

soma panchang

Get Vedic Panchang (Tithi, Nakshatra, Yoga, Karana) for any date and location.

soma panchang \
  --lat 28.61 \
  --lon 77.20 \
  --date 2026-04-01 \
  --tz Asia/Kolkata

Omit --date to use today.

soma insight generate

Generate a personalised AI insight for a life category.

soma insight generate \
  --category career \
  --dob 1990-03-14 \
  --tob 08:30 \
  --lat 28.61 \
  --lon 77.20 \
  --tz Asia/Kolkata

Available categories: career, wealth, health, love, education, travel, spirituality, remedies, and more.

soma insight chat

Start an interactive streaming chat session with Soma (AI Vedic astrologer).

soma insight chat \
  --dob 1990-03-14 \
  --tob 08:30 \
  --lat 28.61 \
  --lon 77.20 \
  --tz Asia/Kolkata

Soma streams responses in real time. Type exit or press Ctrl+C to quit.

soma compat synastry

Compare two birth charts for compatibility.

soma compat synastry \
  --p1-dob 1990-03-14 --p1-tob 08:30 --p1-lat 28.61 --p1-lon 77.20 --p1-tz Asia/Kolkata \
  --p2-dob 1992-07-22 --p2-tob 14:15 --p2-lat 19.07 --p2-lon 72.87 --p2-tz Asia/Kolkata

soma keys

Manage your API keys.

soma keys list                        # List all active keys
soma keys create --name "My App"      # Create a new sandbox key
soma keys revoke <key-id>             # Revoke a key by ID

The plaintext key is shown only once on creation. Save it immediately.

soma usage

Show API quota usage for the current key.

soma usage

Global Options

These options work with every command:

| Option | Description | |--------|-------------| | --output <format> | Output format: table (default), json, yaml | | -q | Quiet mode — minimal output | | --key <sk_live_...> | Override stored API key for this call only | | --version | Show CLI version | | --help | Show help for any command |

JSON / YAML output

soma chart natal ... --output json
soma chart natal ... --output yaml

# Pipe into jq
soma chart natal ... --output json | jq '.lagna'

Configuration

The CLI stores your API key and preferences at ~/.soma/config.json.

| Setting | Default | |---------|---------| | api_key | (set via soma auth login) | | api_base_url | SomaOS production API | | default_output | table |

Override the API base URL at runtime:

SOMA_API_URL=https://your-custom-url.com soma chart natal ...

Get an API Key

Sign up for a free sandbox key (200 calls lifetime) at asksoma.ai.

| Tier | Calls | |------|-------| | Sandbox | 200 lifetime | | Builder | 1,000/month | | Growth | 10,000/month | | Scale | 100,000/month | | Enterprise | Unlimited |

License

MIT © AskSoma