empyrean-cli

Command-line interface for empyrean — orbit propagation, ephemeris generation, orbit determination, and event detection

empyrean-cli is the command-line interface to empyrean. It publishes one binary — empyrean — that runs every headline pipeline (orbit propagation, ephemeris generation, orbit determination, and event detection) and emits Parquet output you can join in pandas / Polars / DuckDB.

Install

cargo install empyrean-cli

or grab a pre-built binary for your platform from GitHub Releases. The installed binary is named empyrean.

Quickstart

# One-time: download SPICE kernels into ~/.empyrean/data/.
empyrean init

# Propagate Apophis 10 years past its SBDB epoch.
empyrean propagate --object-id 99942 --epoch 64922.0 --out-dir ./out

# Generate an ephemeris from the same orbit at observatory 568.
empyrean ephemeris --object-id 99942 --observers 568 --epoch 64922.0 --out-dir ./out

# Fit an orbit from an ADES PSV.
empyrean determine apophis.psv --out-dir ./out

# Confirm the build provenance — every binary carries the `<tag>+<sha>`
# strings of the villeneuve / scott / hyperjet commits it was built against.
empyrean version

All commands emit Parquet tables under --out-dir. The schemas match the Python and Rust API outputs exactly — same orbit_id / object_id join keys, same time scales, same physical units — so you can mix-and-match channels for the same workflow.

Runtime requirement

The empyrean binary links against libempyrean.{dylib,so,dll}, which is distributed separately as a binary release on GitHub and inside the published Python wheel. cargo install empyrean-cli will build the binary and expects to find the dylib on the system library path at runtime.

License

Source code in this crate is licensed under the BSD 3-Clause License. The installed empyrean binary — which embeds the closed-source libempyrean runtime — is governed by a separate proprietary binary license; see the main repository for the dual-license breakdown.

Copyright © 2024–2026 Joachim Moeyens. All rights reserved.