AstroTUI 🌌

English | 中文 | 日本語

Explore the cosmos interactively — A beautiful TUI for querying astronomical databases

✨ What is AstroTUI?

AstroTUI is an interactive terminal user interface for Astro CLI. Built with Ink (React for CLI), it provides a rich, keyboard-driven experience for querying 17+ astronomical databases — no need to remember command flags or syntax.

Select a service. Enter a target. Get results. All from a single interactive screen.

🧩 Supported Data Sources

Access 17 astronomical databases and services through a unified interactive interface:

| Service | Description | Key | |---------|------------|------| | SIMBAD | Astronomical data & object identification | simbad | | VizieR | Catalog database search | vizier | | ALMA | ALMA radio telescope observations | alma | | Gaia | ESA Gaia mission data | gaia | | IRSA | Infrared Science Archive | irsa | | HEASARC | X-ray and Gamma-ray data | heasarc | | JPL Horizons | Solar System ephemerides | jpl | | MAST | Space Telescope Archive (HST, JWST) | mast | | ADS | Astrophysics literature search | ads | | NED | Extragalactic Database | ned | | NIST | Atomic spectra database | nist | | NASA Exoplanet | Exoplanet catalog | exoplanet | | SDSS | Sloan Digital Sky Survey | sdss | | ESO | European Southern Observatory | eso | | Splatalogue | Molecular line database | splatalogue | | AAVSO VSX | Variable Star Index | aavso | | Fermi-LAT | Gamma-ray telescope data | fermi |

🌟 Key Features

• 🎮 Interactive TUI: Keyboard-driven interface with ↑↓ navigation, Tab focus, scrollable results
• 📦 17 Data Sources: Query SIMBAD, VizieR, Gaia, ALMA, ADS, and more from one screen
• 🔄 Shared Environment: Reuses ~/.aqc/config.ini and Python venv with Astro CLI
• ⚡ Zero Config: Auto-detects Python, manages virtual environment, installs dependencies
• 📊 Scrollable Results: Browse large query results with ↑↓ keys, line-by-line or page-by-page
• 🚀 npx Ready: Run instantly with npx astrotui — no global install needed
• 🎨 Beautiful UI: Built with Ink (React for CLI) — styled, colored, responsive layout

📦 Installation

Method 1: npx (No Install Required)

npx astrotui

Method 2: npm Global Install

npm install -g astrotui
astrotui

Method 3: Install from Source

git clone https://github.com/inoribea/astrotui.git
cd astrotui
npm install
npm run build
npm start

Prerequisites

• Node.js ≥ 18
• Python ≥ 3.11 (auto-detected, managed in isolated venv)

📚 Usage

Quick Start

# Launch the TUI
astrotui

Keyboard Controls

| Screen | Key | Action | |--------|-----|--------| | Menu | ↑ ↓ | Navigate services | | Menu | Enter | Select service | | Menu | q | Quit | | Query | Tab | Switch between subcommand / query fields | | Query | Enter | Submit query | | Query | Esc | Back to menu | | Results | ↑ ↓ | Scroll results | | Results | n | New query (same service) | | Results | Esc | Back to menu | | Results | q | Quit | | Any | Ctrl+C | Force quit |

Workflow

★ AstroTUI — Query astronomical databases from your terminal
  17 data sources · Interactive · Powered by astroquery

  Select a data service:

    ❯ SIMBAD        Astronomical database & object identification
      VizieR        Catalog database search
      Gaia          ESA Gaia mission data
      ...

↑↓ Navigate · Enter Select · q Quit

                ↓ Select SIMBAD

  SIMBAD — Astronomical database & object identification

  Available: object
  ▸ Subcommand: object
    Query:      M31

Tab Switch · Enter Submit · Esc Back

                ↓ Enter

  ✓ SIMBAD → M31
  ┌──────────────────────────────────────────┐
  │ main_id    ra          dec        otype  │
  │ M 31       10.6847083  41.2687500 Galaxy │
  │ ...                                      │
  └──────────────────────────────────────────┘

↑↓ Scroll · n New query · Esc Menu · q Quit

🔧 Shared Configuration

AstroTUI shares the same configuration as Astro CLI:

Config File

~/.aqc/config.ini — used by both astrocli and astrotui:

[Environment]
ADS_DEV_KEY = your_key_here
# AQC_LANG = en
# AQC_DEBUG = true

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | AQC_PYTHON | Python interpreter path | Auto-detected | | AQC_VENV_DIR | Virtual environment directory | ~/.cache/astroquery-cli | | AQC_LANG | Output language (en/zh/ja) | en | | AQC_DEBUG | Enable debug mode | false | | AQC_FORCE_INSTALL | Force reinstall Python deps | - | | ADS_DEV_KEY | ADS API key | - |

Shared Resources

| Resource | Path | Shared With | |----------|------|-------------| | Config | ~/.aqc/config.ini | astrocli | | Python venv | ~/.cache/astroquery-cli/venv | astrocli | | Python package | astroquery-cli (PyPI) | astrocli |

🛠️ Development

Project Structure

astrotui/
├── src/
│   ├── index.tsx                # Entry point
│   ├── components/
│   │   ├── App.tsx              # Main controller, single useInput router
│   │   ├── Header.tsx           # Title bar
│   │   ├── LoadingScreen.tsx    # Boot spinner + env detection
│   │   ├── MainMenu.tsx         # Service selection list
│   │   ├── QueryForm.tsx        # Subcommand + query input
│   │   └── ResultView.tsx       # Scrollable results display
│   └── utils/
│       ├── config.ts            # ~/.aqc/config.ini parser
│       ├── python-bridge.ts     # Python venv management + query runner
│       └── services.ts          # 17 data source definitions
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── README.md

Build & Dev

npm install          # Install dependencies
npm run build        # Build for production
npm run dev          # Watch mode
npm start            # Run built output

Tech Stack

| Layer | Technology | |-------|-----------| | UI Framework | Ink 6 (React for CLI) | | Runtime | Node.js ≥ 18 | | Language | TypeScript + TSX | | Bundler | tsup | | Backend | astroquery-cli via Python subprocess |

🤝 Related Projects

• astrocli — The CLI backend this TUI wraps
• aqc-mcp — MCP server for AI assistants
• astroquery — Python library for astronomical data access
• Ink — React for building CLI apps

📄 License

BSD 3-Clause License

🙏 Acknowledgments

• astrocli — The CLI engine behind the TUI
• Ink — Making React work in the terminal
• Astroquery — Astronomical data access library
• Astropy — Core Python library for astronomy