solunatus 0.4.0

High-precision astronomical calculation library and CLI for sun/moon positions, rise/set times, and lunar phases
Documentation

Solunatus

Crates.io Downloads Documentation License: MIT

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

Solunatus targets the latest stable Rust release for active development. The current release line supports stable Rust versions compatible with rust-version = "1.91", and that floor may rise in a minor release when security, dependency compatibility, or maintainability require it. If you need an older Rust toolchain, use an older Solunatus release that still supports it.

To upgrade an existing installation from crates.io:

cargo install solunatus --force

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.4.0"
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.

Releases

Crates.io is the supported distribution channel for published releases:

cargo install solunatus

GitHub Releases are used for tags and release notes for each published version. They should not be treated as a guaranteed source of fresh binary artifacts unless a specific release explicitly says otherwise.

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:

License

MIT (LICENSE)