Solunatus

High-precision astronomical calculations for sun and moon events, available as both:

• A Rust library (solunatus)
• A CLI app (solunatus)

Solunatus runs offline for core calculations and supports historical/future dates (from astronomical year -0999 through 3000).

What You Get

• Sunrise, sunset, and solar noon
• Civil, nautical, and astronomical twilight
• Moonrise, moonset, and transit
• Moon phase, illumination, altitude/azimuth, distance
• Built-in city database (570+ cities)
• Interactive terminal UI (watch mode)
• JSON output and calendar export (HTML/JSON)
• Optional USNO validation reports
• Optional AI insights via local Ollama

Install

From crates.io

cargo install solunatus

From source

git clone https://github.com/FunKite/solunatus.git
cd solunatus
cargo install --path .

Quick Start

# Use a city from the built-in database
solunatus --city "New York"

# Or specify coordinates + timezone
solunatus --lat 40.7128 --lon -74.0060 --tz America/New_York

By default, Solunatus starts in interactive watch mode.
Press q to quit, s for settings, and r for reports.

Common CLI Usage

Single snapshot (non-interactive)

solunatus --city "Tokyo" --no-prompt

JSON output

solunatus --city "Tokyo" --json

Specific date

solunatus --city "Lisbon" --date 2026-01-15

Calendar export

solunatus --city "Lisbon" \
  --calendar \
  --calendar-start 2026-01-01 \
  --calendar-end 2026-01-31 \
  --calendar-format html \
  --calendar-output lisbon-jan-2026.html

USNO validation report (feature-enabled builds)

solunatus --city "San Diego" --validate

AI insights with Ollama (feature-enabled builds)

solunatus --city "Seattle" --ai-insights

Command Highlights

Core flags:

• --city <CITY>
• --lat <LAT> --lon <LON> --tz <TIMEZONE>
• --date <YYYY-MM-DD>
• --json
• --calendar --calendar-start <DATE> --calendar-end <DATE>
• --calendar-format <html|json>
• --calendar-output <PATH>
• --watch
• --no-prompt
• --no-save
• --strict

Optional flags (feature gated):

• --validate (usno-validation)
• --ai-insights, --ai-server, --ai-model, --ai-refresh-minutes (ai-insights)

For full CLI docs, see docs/features/cli-reference.md.

Optional Features

Default features:

• cpu-portable
• usno-validation
• ai-insights

Non-default feature:

• parallel (Rayon-based parallel processing)

Examples:

# Minimal build (no USNO validation, no AI insights)
cargo install solunatus --no-default-features

# USNO validation only
cargo install solunatus --no-default-features --features usno-validation

# AI insights only
cargo install solunatus --no-default-features --features ai-insights

# Add parallel processing
cargo install solunatus --features parallel

Library Usage

Add dependency:

[dependencies]
solunatus = "0.3.2"
chrono = "0.4"
chrono-tz = "0.10"

Basic example:

use chrono::Local;
use chrono_tz::America::New_York;
use solunatus::prelude::*;

fn main() {
    let location = Location::new(40.7128, -74.0060).unwrap();
    let now = Local::now().with_timezone(&New_York);

    if let Some(sunrise) = calculate_sunrise(&location, &now) {
        println!("Sunrise: {}", sunrise.format("%H:%M:%S"));
    }

    if let Some(sunset) = calculate_sunset(&location, &now) {
        println!("Sunset: {}", sunset.format("%H:%M:%S"));
    }

    let (phase_name, phase_emoji) = get_current_moon_phase(&location, &now);
    println!("Moon phase: {} {}", phase_emoji, phase_name);
}

More examples: examples/

Accuracy and Scope

Solunatus uses NOAA-based solar methods and Meeus-based lunar methods, with validation tooling aligned to USNO-style conventions.

This project is intended for educational, planning, and general-purpose astronomical use.
It is not certified for safety-critical navigation or legal timing decisions.

Configuration

CLI settings are saved to:

~/.solunatus.json

Use --no-save to avoid writing configuration.

Development

# Build
cargo build

# Test
cargo test

# Safer local test runner
./scripts/safe_local_test.sh

Project docs index: docs/README.md

Contributing

Issue reports and feature requests are welcome:

• GitHub Issues
• Contributing Guide
• Code of Conduct
• Security Policy

License

MIT (LICENSE)