transitui

A terminal UI (TUI) for planning exoplanet transit observations using the NASA Exoplanet Archive Transit & Ephemeris Service API.

Type a planet and a date window, pick from the published ephemerides the archive has for that planet, browse the predicted (and observable) transits for your site, and generate an airmass plot for any night — right in the terminal or as a PDF.

Query  ─►  Ephemerides  ─►  Transits  ─►  Airmass plot

Install & run

Clone the repository first:

git clone ssh://forgejo@git.astro.lavail.net/alexis/transitui.git
cd transitui

The project is managed with uv. If you don't have it yet, install it with the standalone installer — or via pip install uv, Homebrew, etc.; see the install docs for every method (including Windows):

curl -LsSf https://astral.sh/uv/install.sh | sh    # macOS / Linux

With uv you don't have to create a virtualenv or install anything by hand — uv run builds an isolated environment from pyproject.toml + uv.lock on first use:

uv run transitui                 # launch the TUI

Install it as a tool on your PATH, or run it once without installing:

uv tool install .                # then just:  transitui
uvx --from . transitui           # run once, no install

For a development checkout, sync the locked environment explicitly:

uv sync                          # creates .venv from uv.lock

Usage

TUI

uv run transitui        # or:  transitui  ·  python -m transitui  ·  python run.py

• Enter a planet name (e.g. HD 209458 b, WASP-12 b, TRAPPIST-1 b).
• Set the start/end dates (UTC, YYYY-MM-DD) and choose an observatory.
• Press Enter in any field (or Ctrl+R) to search.
• Select an ephemeris, then a transit, to open its airmass plot.
• On the plot screen press s to save a PDF, Esc to go back, q to quit.

Headless / scripting

A non‑interactive mode runs the same pipeline and is handy for scripts or a quick check:

uv run transitui --list-sites

uv run transitui --selftest "HD 209458 b" 2026-06-12 2026-07-05 \
    --site kitt_peak --pdf airmass.pdf

You can also pass --lat/--lon/--height for a custom site and --vis-alt/--vis-air/--twilight to constrain visibility.

How it works

• Transit predictions come from the archive's transit API (nph-transits-api). One call returns every ephemeris for the planet, each row tagged with its reference, period, propagated midpoint uncertainty, and — when a site is supplied — per‑phase airmass/altitude. The service restricts results to transits observable from that site; relax --vis-alt/--twilight to see more.
• The ephemeris menu and transit list are derived from that single response by grouping rows on the reference name, so the two views are always self‑consistent.
• Airmass curves are computed locally with astropy from the target's RA/Dec and the observer location (airmass = sec z), sampled across the whole night between twilight bounds.

Notes & caveats

• No API key is required. Please be considerate with query volume.

License

Released under the MIT License.

Data courtesy of the NASA Exoplanet Archive, operated by Caltech/IPAC under contract with NASA.